VPTS CSV

VPTS CSV is a community developed data exchange format for biological signals detected by weather radars. VPTS (vertical profile time series) express the density, speed and direction of biological signals such as birds, bats and insects within a weather radar volume, grouped into altitude layers (height) and measured over time (datetime).

VPTS CSV is a tabular format (rows and columns), allowing data to be expressed as CSV files. Columns/fields are defined below using Table Schema properties. The format aims to be simple rather than comprehensive, containing the most important information, rather than all the available metadata.

VPTS CSV is maintained at https://github.com/enram/vpts-csv.

Example

radar,datetime,height,u,v,w,ff,dd,sd_vvp,gap,eta,dens,dbz,dbz_all,n,n_dbz,n_all,n_dbz_all,rcs,sd_vvp_threshold,vcp,radar_longitude,radar_latitude,radar_height,radar_wavelength
KBGM,2016-09-01T00:02:00Z,0,,,,,,,TRUE,,,,,0,0,0,0,11,2,,-75.98472,42.19972,519,10.6
KBGM,2016-09-01T00:02:00Z,200,,,,,,,TRUE,,,,,0,0,0,0,11,2,,-75.98472,42.19972,519,10.6
KBGM,2016-09-01T00:02:00Z,400,,,,,,2.81,TRUE,30.8,2.8000000000000003,1.54,3.77,326,356,22485,28416,11,2,,-75.98472,42.19972,519,10.6
KBGM,2016-09-01T00:02:00Z,600,4.14,3.84,12.17,5.65,47.2,2.8,FALSE,46.9,4.263636363636364,3.36,0.5,9006,13442,65947,104455,11,2,,-75.98472,42.19972,519,10.6

Requirements

The key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL in this document are to be interpreted as described in RFC 2119.

  • Data MUST include the names of the fields (e.g. as a header row).
  • Data MUST refer to fields using the names defined below.
  • Data MUST at least include the required fields (indicated with * below).
  • Data MUST use this CSV dialect when expressed as CSV. See CSV dialect documentation.
  • nodata values SHOULD be expressed as NA.
  • undetect values SHOULD be expressed as NaN.
  • Field values SHOULD match the data types as defined below.
  • Field values SHOULD meet the constraints as defined below, except for NaN and NA values.
  • Data SHOULD be ordered by datetime and height within a radar.
  • Data SHOULD have the same heights for all datetimes of a radar.
  • Fields SHOULD be organized in the order presented below.

Fields

Source: https://github.com/enram/vpts-csv/blob/main/vpts-csv-table-schema.json

Name Definition Type Example
radar *

Radar identifier.

Constraints
  • required: true
string

KBGM

datetime *

Nominal date and time of the measurement, as an ISO 8601 formatted string in UTC.

Constraints
  • required: true
datetime

2016-09-01T00:02:00Z

height *

Lower bound of the altitude bin in m above sea level.

Constraints
  • required: true
  • minimum: -200
  • maximum: 25000
Also known as: HGHT, bin_lower
integer

600

u

Ground speed component west to east in m/s.

Constraints
  • minimum: -100
  • maximum: 100
number

4.14

v

Ground speed component north to south in m/s.

Constraints
  • minimum: -100
  • maximum: 100
number

3.84

w

Vertical speed in m/s.

number

12.17

ff *

Horizontal ground speed in m/s.

Constraints
  • required: true
  • minimum: 0
  • maximum: 100
Also known as: speed
number

5.65

dd *

Ground speed direction in degrees clockwise from north.

Constraints
  • required: true
  • minimum: 0
  • maximum: 360
Also known as: direction
number

47.2

sd_vvp *

VVP radial velocity standard deviation in m/s.

Constraints
  • required: true
  • minimum: 0
  • maximum: 100
Also known as: rmse
number

2.8

gap

Angular data gap detected.

boolean

FALSE

eta *

Animal reflectivity in cm^2/km^3.

Constraints
  • required: true
  • minimum: 0
  • maximum: Inf
Also known as: linear_eta
number

46.9

dens

Animal density in animals/km^3.

Constraints
  • minimum: 0
  • maximum: Inf
number

4.263636363636364

dbz

Animal reflectivity factor in dBZ.

Constraints
  • minimum: -Inf
  • maximum: 100
number

3.36

dbz_all

Total reflectivity factor (bio + meteo scattering) in dBZ.

Constraints
  • minimum: -Inf
  • maximum: 100
Also known as: DBZH
number

0.5

n

Number of data points used for the ground speed estimates (quantities u, v, w, ff, dd).

Constraints
  • minimum: 0
integer

9006

n_dbz

Number of data points used for reflectivity-based estimates (quantities dbz, eta, dens).

Constraints
  • minimum: 0
integer

13442

n_all

Number of data points used for the radial velocity standard deviation estimate (quantity sd_vvp).

Constraints
  • minimum: 0
integer

65947

n_dbz_all

Number of data points used for the total reflectivity estimate (quantity dbz_all).

Constraints
  • minimum: 0
Also known as: nbins
integer

104455

rcs

Radar cross section per bird in cm^2.

Constraints
  • minimum: 1e-15
  • maximum: Inf
number

11

sd_vvp_threshold

Lower threshold in radial velocity standard deviation (profile quantity sd_vvp) in m/s. Biological signals with sd_vvp < sd_vvp_threshold are set to zero. Defaults to 2 m/s for C-band radars and 1 m/s for S-band radars if not specified.

Constraints
  • minimum: 0
  • maximum: 100
number

2

vcp

Volume coverage pattern, unitless. Documented on Wikipedia for NEXRAD.

Constraints
  • enum: 12, 212, 112, 215, 121, 31, 32, 35
Also known as: scan_strategy
integer
radar_longitude *

Longitude of the radar location in decimal degrees, using the WGS84 datum. Constant for all records from the same radar.

Constraints
  • required: true
  • minimum: -180
  • maximum: 180
number

-75.98472

radar_latitude *

Latitude of the radar location in decimal degrees, using the WGS84 datum. Constant for all records from the same radar.

Constraints
  • required: true
  • minimum: -90
  • maximum: 90
number

42.19972

radar_height *

Height of the center of the radar antenna in m above sea level. Constant for all records from the same radar.

Constraints
  • required: true
  • minimum: -200
  • maximum: 9000
integer

519

radar_wavelength *

Wavelength of the radar in cm. Constant for all records from the same radar. Most C-band radars operate at approximately 5.3 cm wavelength, most S-band radars at 10.6 cm.

Constraints
  • required: true
  • minimum: 0.1
  • maximum: 100
number

10.6