---

Input and output (pyart.io)

Functions to read and write radar and grid data to and from a number of file formats.

Reading radar data

In most cases the pyart.io.read() function should be used to read in radar data from a file. In certain cases the function the read function for the format in question should be used.

read(filename[, use_rsl])	Read a radar file and return a radar object.
read_rsl(filename[, field_names, …])	Read a file supported by RSL.
read_mdv(filename[, field_names, …])	Read a MDV file.
read_sigmet(filename[, field_names, …])	Read a Sigmet (IRIS) product file.
read_cfradial(filename[, field_names, …])	Read a Cfradial netCDF file.
read_cfradial2(filename[, field_names, …])	Read a Cfradial2 netCDF file.
read_chl(filename[, field_names, …])	Read a CSU-CHILL CHL file.
read_nexrad_archive(filename[, field_names, …])	Read a NEXRAD Level 2 Archive file.
read_nexrad_cdm(filename[, field_names, …])	Read a Common Data Model (CDM) NEXRAD Level 2 file.
read_nexrad_level3(filename[, field_names, …])	Read a NEXRAD Level 3 product.
read_uf(filename[, field_names, …])	Read a UF File.

Writing radar data

write_cfradial(filename, radar[, format, …])	Write a Radar object to a CF/Radial compliant netCDF file.
write_uf(filename, radar[, uf_field_names, …])	Write a Radar object to a UF file.

Reading grid data

read_grid(filename[, exclude_fields, …])	Read a netCDF grid file produced by Py-ART.
read_grid_mdv(filename[, field_names, …])	Read a MDV file to a Grid Object.

Writing grid data

write_grid(filename, grid[, format, …])	Write a Grid object to a CF-1.5 and ARM standard netCDF file.
write_grid_mdv(filename, grid[, …])	Write grid object to MDV file.
write_grid_geotiff(grid, filename, field[, …])	Write a Py-ART Grid object to a GeoTIFF file.

Reading Sonde data

read_arm_sonde(filename)	Read a ARM sonde file returning a wind profile.
read_arm_sonde_vap(filename[, radar, …])	Read a ARM interpolated or merged sonde returning a wind profile.

Special use

prepare_for_read(filename)	Return a file like object read for reading.
make_time_unit_str(dtobj)	Return a time unit string from a datetime object.

pyart.io.make_time_unit_str(dtobj)

Return a time unit string from a datetime object.

pyart.io.prepare_for_read(filename)

Return a file like object read for reading.

Open a file for reading in binary mode with transparent decompression of Gzip and BZip2 files. The resulting file-like object should be closed.

Parameters:

filename : str or file-like object

Filename or file-like object which will be opened. File-like objects will not be examined for compressed data.

Returns:

file_like : file-like object

File like object from which data can be read.

pyart.io.read(filename, use_rsl=False, **kwargs)

Read a radar file and return a radar object.

Additional parameters are passed to the underlying read_* function.

Parameters:

filename : str

Name of radar file to read.

use_rsl : bool

True will use the TRMM RSL library to read files which are supported both natively and by RSL. False will choose the native read function. RSL will always be used to read a file if it is not supported natively.

Returns:

radar : Radar

Radar object. A TypeError is raised if the format cannot be determined.

Other Parameters:  

field_names : dict, optional

Dictionary mapping file data type names to radar field names. If a data type found in the file does not appear in this dictionary or has a value of None it will not be placed in the radar.fields dictionary. A value of None, the default, will use the mapping defined in the metadata configuration file.

additional_metadata : dict of dicts, optional

Dictionary of dictionaries to retrieve metadata from during this read. This metadata is not used during any successive file reads unless explicitly included. A value of None, the default, will not introduct any addition metadata and the file specific or default metadata as specified by the metadata configuration file will be used.

file_field_names : bool, optional

True to use the file data type names for the field names. If this case the field_names parameter is ignored. The field dictionary will likely only have a ‘data’ key, unless the fields are defined in additional_metadata.

exclude_fields : list or None, optional

List of fields to exclude from the radar object. This is applied after the file_field_names and field_names parameters.

delay_field_loading : bool

True to delay loading of field data from the file until the ‘data’ key in a particular field dictionary is accessed. In this case the field attribute of the returned Radar object will contain LazyLoadDict objects not dict objects. Not all file types support this parameter.

pyart.io.read_arm_sonde(filename)

Read a ARM sonde file returning a wind profile.

Parameters:

filename : str

Name of ARM sonde NetCDF file to read data from.

pyart.io.read_arm_sonde_vap(filename, radar=None, target_datetime=None)

Read a ARM interpolated or merged sonde returning a wind profile.

Parameters:

filename : str

Name of ARM interpolate or merged sonde NetCDF file to read data from.

radar : Radar, optional

If provided the profile returned is that which is closest in time to the first ray collected in this radar. Either radar or target_datetime must be provided.

target_datetime : datetime, optional

If specified the profile returned is that which is closest in time to this datetime.

pyart.io.read_cfradial(filename, field_names=None, additional_metadata=None, file_field_names=False, exclude_fields=None, include_fields=None, delay_field_loading=False, **kwargs)

Read a Cfradial netCDF file.

Parameters:

filename : str

Name of CF/Radial netCDF file to read data from.

field_names : dict, optional

Dictionary mapping field names in the file names to radar field names. Unlike other read functions, fields not in this dictionary or having a value of None are still included in the radar.fields dictionary, to exclude them use the exclude_fields parameter. Fields which are mapped by this dictionary will be renamed from key to value.

additional_metadata : dict of dicts, optional

This parameter is not used, it is included for uniformity.

file_field_names : bool, optional

True to force the use of the field names from the file in which case the field_names parameter is ignored. False will use to field_names parameter to rename fields.

exclude_fields : list or None, optional

List of fields to exclude from the radar object. This is applied after the file_field_names and field_names parameters. Set to None to include all fields specified by include_fields.

include_fields : list or None, optional

List of fields to include from the radar object. This is applied after the file_field_names and field_names parameters. Set to None to include all fields not specified by exclude_fields.

delay_field_loading : bool

True to delay loading of field data from the file until the ‘data’ key in a particular field dictionary is accessed. In this case the field attribute of the returned Radar object will contain LazyLoadDict objects not dict objects. Delayed field loading will not provide any speedup in file where the number of gates vary between rays (ngates_vary=True) and is not recommended.

Returns:

radar : Radar

Radar object.

Notes

This function has not been tested on “stream” Cfradial files.

pyart.io.read_cfradial2(filename, field_names=None, additional_metadata=None, file_field_names=False, exclude_fields=None, include_fields=None, delay_field_loading=False, **kwargs)

Read a Cfradial2 netCDF file.

Parameters:

filename : str

Name of CF/Radial netCDF file to read data from.

field_names : dict, optional

Dictionary mapping field names in the file names to radar field names. Unlike other read functions, fields not in this dictionary or having a value of None are still included in the radar.fields dictionary, to exclude them use the exclude_fields parameter. Fields which are mapped by this dictionary will be renamed from key to value.

additional_metadata : dict of dicts, optional

This parameter is not used, it is included for uniformity.

file_field_names : bool, optional

True to force the use of the field names from the file in which case the field_names parameter is ignored. False will use to field_names parameter to rename fields.

exclude_fields : list or None, optional

List of fields to exclude from the radar object. This is applied after the file_field_names and field_names parameters. Set to None to include all fields specified by include_fields.

include_fields : list or None, optional

List of fields to include from the radar object. This is applied after the file_field_names and field_names parameters. Set to None to include all fields not specified by exclude_fields.

delay_field_loading : bool

True to delay loading of field data from the file until the ‘data’ key in a particular field dictionary is accessed. In this case the field attribute of the returned Radar object will contain LazyLoadDict objects not dict objects. Delayed field loading will not provide any speedup in file where the number of gates vary between rays (ngates_vary=True) and is not recommended.

Returns:

radar : Radar

Radar object.

Notes

This function has not been tested on “stream” Cfradial files.

pyart.io.read_chl(filename, field_names=None, additional_metadata=None, file_field_names=None, exclude_fields=None, include_fields=None, use_file_field_attributes=True, **kwargs)

Read a CSU-CHILL CHL file.

Parameters:

filename : str

Name of CHL file.

field_names : dict, optional

Dictionary mapping CHL field names to radar field names. If a data type found in the file does not appear in this dictionary or has a value of None it will not be placed in the radar.fields dictionary. A value of None, the default, will use the mapping defined in the Py-ART configuration file.

additional_metadata : dict of dicts, optional

Dictionary of dictionaries to retrieve metadata from during this read. This metadata is not used during any successive file reads unless explicitly included. A value of None, the default, will not introduct any addition metadata and the file specific or default metadata as specified by the Py-ART configuration file will be used.

file_field_names : bool, optional

True to use the CHL field names for the field names in the radar object. If this case the field_names parameter is ignored. The field dictionary will likely only have a ‘data’ key, unless the fields are defined in additional_metadata.

exclude_fields : list or None, optional

List of fields to exclude from the radar object. This is applied after the file_field_names and field_names parameters.

include_fields : list or None, optional

List of fields to include from the radar object. This is applied after the field_file_names and field_names parameters. Set to None to include all fields not in exclude_fields.

use_file_field_attributes : bool, optional

True to use information provided by in the file to set the field attribute long_name, units, valid_max, and valid_min. False will not set these unless they are defined in the configuration file or in additional_metadata.

Returns:

radar : Radar

Radar object containing data from CHL file.

pyart.io.read_grid(filename, exclude_fields=None, include_fields=None, **kwargs)

Read a netCDF grid file produced by Py-ART.

Parameters:

filename : str

Filename of netCDF grid file to read. This file must have been produced by write_grid() or have identical layout.

Returns:

grid : Grid

Grid object containing gridded data.

Other Parameters:  

exclude_fields : list or None, optional

List of fields to exclude from the radar object. This is applied after the file_field_names and field_names parameters. Set to None to include all fields specified by include_fields.

include_fields : list or None, optional

List of fields to include from the radar object. This is applied after the file_field_names and field_names parameters. Set to None to include all fields not specified by exclude_fields.

pyart.io.read_grid_mdv(filename, field_names=None, additional_metadata=None, file_field_names=False, exclude_fields=None, delay_field_loading=False, **kwargs)

Read a MDV file to a Grid Object.

Parameters:

filename : str

Name of MDV file to read or file-like object pointing to the beginning of such a file.

field_names : dict, optional

Dictionary mapping MDV data type names to radar field names. If a data type found in the file does not appear in this dictionary or has a value of None it will not be placed in the radar.fields dictionary. A value of None, the default, will use the mapping defined in the Py-ART configuration file.

additional_metadata : dict of dicts, optional

Dictionary of dictionaries to retrieve metadata from during this read. This metadata is not used during any successive file reads unless explicitly included. A value of None, the default, will not introduct any addition metadata and the file specific or default metadata as specified by the Py-ART configuration file will be used.

file_field_names : bool, optional

True to use the MDV data type names for the field names. If this case the field_names parameter is ignored. The field dictionary will likely only have a ‘data’ key, unless the fields are defined in additional_metadata.

exclude_fields : list or None, optional

List of fields to exclude from the grid object. This is applied after the file_field_names and field_names parameters.

delay_field_loading : bool

True to delay loading of field data from the file until the ‘data’ key in a particular field dictionary is accessed. In this case the field attribute of the returned Radar object will contain LazyLoadDict objects not dict objects.

Returns:

grid : Grid

Grid object containing data from MDV file.

Notes

This function can only read cartesian MDV files with fields compressed with gzip or zlib. For polar files see pyart.io.read_mdv()

MDV files and Grid object are not fully interchangeable. Specific limitation include:

• All fields must have the same shape and dimensions.
• All fields must have the same projection.
• Vlevels types must not vary.
• Projection must not be PROJ_POLAR_RADAR (9) or PROJ_RHI_RADAR (13).
• Correct unit in the Z axis are just availible for ‘vlevel_type’ equal to VERT_TYPE_Z(4), VERT_TYPE_ELEV(9), VERT_TYPE_AZ(17), VERT_TYPE_PRESSURE(3) and VERT_TYPE_THETA(7).
• The behavior in cases of 2D data is unknown but most likely will not fail.

pyart.io.read_mdv(filename, field_names=None, additional_metadata=None, file_field_names=False, exclude_fields=None, include_fields=None, delay_field_loading=False, **kwargs)

Read a MDV file.

Parameters:

filename : str

Name of MDV file to read or file-like object pointing to the beginning of such a file.

field_names : dict, optional

Dictionary mapping MDV data type names to radar field names. If a data type found in the file does not appear in this dictionary or has a value of None it will not be placed in the radar.fields dictionary. A value of None, the default, will use the mapping defined in the Py-ART configuration file.

additional_metadata : dict of dicts, optional

Dictionary of dictionaries to retrieve metadata from during this read. This metadata is not used during any successive file reads unless explicitly included. A value of None, the default, will not introduct any addition metadata and the file specific or default metadata as specified by the Py-ART configuration file will be used.

file_field_names : bool, optional

True to use the MDV data type names for the field names. If this case the field_names parameter is ignored. The field dictionary will likely only have a ‘data’ key, unless the fields are defined in additional_metadata.

exclude_fields : list or None, optional

List of fields to exclude from the radar object. This is applied after the file_field_names and field_names parameters. Set to None to include all fields specified by include_fields.

include_fields : list or None, optional

List of fields to include from the radar object. This is applied after the file_field_names and field_names parameters. Set to None to include all fields not specified by exclude_fields.

delay_field_loading : bool

True to delay loading of field data from the file until the ‘data’ key in a particular field dictionary is accessed. In this case the field attribute of the returned Radar object will contain LazyLoadDict objects not dict objects. Not all file types support this parameter.

Returns:

radar : Radar

Radar object containing data from MDV file.

Notes

Currently this function can only read polar MDV files with fields compressed with gzip or zlib.

pyart.io.read_nexrad_archive(filename, field_names=None, additional_metadata=None, file_field_names=False, exclude_fields=None, include_fields=None, delay_field_loading=False, station=None, scans=None, linear_interp=True, **kwargs)

Read a NEXRAD Level 2 Archive file.

Parameters:

filename : str

Filename of NEXRAD Level 2 Archive file. The files hosted by at the NOAA National Climate Data Center [1] as well as on the UCAR THREDDS Data Server [2] have been tested. Other NEXRAD Level 2 Archive files may or may not work. Message type 1 file and message type 31 files are supported.

field_names : dict, optional

Dictionary mapping NEXRAD moments to radar field names. If a data type found in the file does not appear in this dictionary or has a value of None it will not be placed in the radar.fields dictionary. A value of None, the default, will use the mapping defined in the metadata configuration file.

additional_metadata : dict of dicts, optional

Dictionary of dictionaries to retrieve metadata from during this read. This metadata is not used during any successive file reads unless explicitly included. A value of None, the default, will not introduct any addition metadata and the file specific or default metadata as specified by the metadata configuration file will be used.

file_field_names : bool, optional

True to use the NEXRAD field names for the field names. If this case the field_names parameter is ignored. The field dictionary will likely only have a ‘data’ key, unless the fields are defined in additional_metadata.

exclude_fields : list or None, optional

List of fields to exclude from the radar object. This is applied after the file_field_names and field_names parameters. Set to None to include all fields specified by include_fields.

include_fields : list or None, optional

List of fields to include from the radar object. This is applied after the file_field_names and field_names parameters. Set to None to include all fields not specified by exclude_fields.

delay_field_loading : bool, optional

True to delay loading of field data from the file until the ‘data’ key in a particular field dictionary is accessed. In this case the field attribute of the returned Radar object will contain LazyLoadDict objects not dict objects.

station : str or None, optional

Four letter ICAO name of the NEXRAD station used to determine the location in the returned radar object. This parameter is only used when the location is not contained in the file, which occur in older NEXRAD message 1 files.

scans : list or None, optional

Read only specified scans from the file. None (the default) will read all scans.

linear_interp : bool, optional

True (the default) to perform linear interpolation between valid pairs of gates in low resolution rays in files mixed resolution rays. False will perform a nearest neighbor interpolation. This parameter is not used if the resolution of all rays in the file or requested sweeps is constant.

Returns:

radar : Radar

Radar object containing all moments and sweeps/cuts in the volume. Gates not collected are masked in the field data.

References

[1]	http://www.ncdc.noaa.gov/

[2]	http://thredds.ucar.edu/thredds/catalog.html

pyart.io.read_nexrad_cdm(filename, field_names=None, additional_metadata=None, file_field_names=False, exclude_fields=None, include_fields=None, station=None, **kwargs)

Read a Common Data Model (CDM) NEXRAD Level 2 file.

Parameters:

filename : str

File name or URL of a Common Data Model (CDM) NEXRAD Level 2 file. File of in this format can be created using the NetCDF Java Library tools [1]. A URL of a OPeNDAP file on the UCAR THREDDS Data Server [2] is also accepted the netCDF4 library has been compiled with OPeNDAP support.

field_names : dict, optional

Dictionary mapping NEXRAD moments to radar field names. If a data type found in the file does not appear in this dictionary or has a value of None it will not be placed in the radar.fields dictionary. A value of None, the default, will use the mapping defined in the metadata configuration file.

additional_metadata : dict of dicts, optional

Dictionary of dictionaries to retrieve metadata from during this read. This metadata is not used during any successive file reads unless explicitly included. A value of None, the default, will not introduct any addition metadata and the file specific or default metadata as specified by the metadata configuration file will be used.

file_field_names : bool, optional

True to use the NEXRAD field names for the field names. If this case the field_names parameter is ignored. The field dictionary will likely only have a ‘data’ key, unless the fields are defined in additional_metadata.

exclude_fields : list or None, optional

List of fields to exclude from the radar object. This is applied after the file_field_names and field_names parameters. Set to None to include all fields specified by include_fields.

include_fields : list or None, optional

List of fields to include from the radar object. This is applied after the file_field_names and field_names parameters. Set to None to include all fields not specified by exclude_fields.

station : str

Four letter ICAO name of the NEXRAD station used to determine the location in the returned radar object. This parameter is only used when the location is not contained in the file, which occur in older NEXRAD files. If the location is not provided in the file and this parameter is set to None the station name will be determined from the filename.

Returns:

radar : Radar

Radar object containing all moments and sweeps/cuts in the volume. Gates not collected are masked in the field data.

References

[1]	http://www.unidata.ucar.edu/software/netcdf-java/documentation.htm

[2]	http://thredds.ucar.edu/thredds/catalog.html

pyart.io.read_nexrad_level3(filename, field_names=None, additional_metadata=None, file_field_names=False, exclude_fields=None, include_fields=None, **kwargs)

Read a NEXRAD Level 3 product.

Parameters:

filename : str

Filename of NEXRAD Level 3 product file. The files hosted by at the NOAA National Climate Data Center [1] as well as on the NWS WSR-88D Level III Data Collection and Distribution Network have been tests. Other NEXRAD Level 3 files may or may not work. A file-like object pointing to the beginning of such a file is also supported.

field_names : dict, optional

Dictionary mapping NEXRAD level 3 product number to radar field names. If the product number of the file does not appear in this dictionary or has a value of None it will not be placed in the radar.fields dictionary. A value of None, the default, will use the mapping defined in the metadata configuration file.

additional_metadata : dict of dicts, optional

Dictionary of dictionaries to retrieve metadata from during this read. This metadata is not used during any successive file reads unless explicitly included. A value of None, the default, will not introduct any addition metadata and the file specific or default metadata as specified by the metadata configuration file will be used.

file_field_names : bool, optional

True to use the product number for the field name. In this case the field_names parameter is ignored. The field dictionary will likely only have a ‘data’ key, unless the fields are defined in additional_metadata.

exclude_fields : list or None, optional

List of fields to exclude from the radar object. This is applied after the file_field_names and field_names parameters. Set to None to include all fields specified by include_fields.

include_fields : list or None, optional

List of fields to include from the radar object. This is applied after the file_field_names and field_names parameters. Set to None to include all fields not specified by exclude_fields.

Returns:

radar : Radar

Radar object containing all moments and sweeps/cuts in the volume. Gates not collected are masked in the field data.

References

[1]	http://www.ncdc.noaa.gov/

[2]	http://www.roc.noaa.gov/wsr88d/Level_III/Level3Info.asp

pyart.io.read_rsl(filename, field_names=None, additional_metadata=None, file_field_names=False, exclude_fields=None, delay_field_loading=False, include_fields=None, radar_format=None, callid=None, skip_range_check=False)

Read a file supported by RSL.

Parameters:

filename : str or RSL_radar

Name of file whose format is supported by RSL.

field_names : dict, optional

Dictionary mapping RSL data type names to radar field names. If a data type found in the file does not appear in this dictionary or has a value of None it will not be placed in the radar.fields dictionary. A value of None, the default, will use the mapping defined in the Py-ART configuration file.

additional_metadata : dict of dicts, optional

Dictionary of dictionaries to retrieve metadata from during this read. This metadata is not used during any successive file reads unless explicitly included. A value of None, the default, will not introduct any addition metadata and the file specific or default metadata as specified by the Py-ART configuration file will be used.

file_field_names : bool, optional

True to use the RSL data type names for the field names. If this case the field_names parameter is ignored. The field dictionary will likely only have a ‘data’ key, unless the fields are defined in additional_metadata.

exclude_fields : list or None, optional

List of fields to exclude from the radar object. This is applied after the file_field_names and field_names parameters. Set to None to include all fields specified by include_fields.

include_fields : list or None, optional

List of fields to include from the radar object. This is applied after the file_field_names and field_names parameters. Set to None to include all fields not specified by exclude_fields.

delay_field_loading : bool

True to delay loading of field data from the file until the ‘data’ key in a particular field dictionary is accessed. In this case the field attribute of the returned Radar object will contain LazyLoadDict objects not dict objects.

radar_format : str or None

Format of the radar file. Must be ‘wsr88d’ or None.

callid : str or None

Four letter NEXRAD radar Call ID, only used when radar_format is ‘wsr88d’.

skip_range_check : bool, optional

True to skip check for uniform range bin location, the reported range locations will only be verified true for the first ray. False will perform the check and raise a IOError when the locations of the gates change between rays.

Returns:

radar : Radar

Radar object.

pyart.io.read_sigmet(filename, field_names=None, additional_metadata=None, file_field_names=False, exclude_fields=None, include_fields=None, time_ordered='none', full_xhdr=None, noaa_hh_hdr=None, debug=False, ignore_xhdr=False, ignore_sweep_start_ms=None, **kwargs)

Read a Sigmet (IRIS) product file.

Parameters:

filename : str

Name of Sigmet (IRIS) product file to read or file-like object pointing to the beginning of such a file.

field_names : dict, optional

Dictionary mapping Sigmet data type names to radar field names. If a data type found in the file does not appear in this dictionary or has a value of None it will not be placed in the radar.fields dictionary. A value of None, the default, will use the mapping defined in the metadata configuration file.

additional_metadata : dict of dicts, optional

Dictionary of dictionaries to retrieve metadata from during this read. This metadata is not used during any successive file reads unless explicitly included. A value of None, the default, will not introduct any addition metadata and the file specific or default metadata as specified by the metadata configuration file will be used.

file_field_names : bool, optional

True to use the Sigmet data type names for the field names. If this case the field_names parameter is ignored. The field dictionary will likely only have a ‘data’ key, unless the fields are defined in additional_metadata.

exclude_fields : list or None, optional

List of fields to exclude from the radar object. This is applied after the file_field_names and field_names parameters. Set to None to include all fields specified by include_fields.

include_fields : list or None, optional

List of fields to include from the radar object. This is applied after the file_field_names and field_names parameters. Set to None to include all fields not specified by exclude_fields.

time_ordered : ‘none’, ‘sequential’, ‘full’, …, optional

Parameter controlling if and how the rays are re-ordered by time. The default, ‘none’ keeps the rays ordered in the same manner as they appears in the Sigmet file. ‘sequential’ will determind and apply an operation which maintains a sequential ray order in elevation or azimuth yet orders the rays according to time. If no operation can be found to accomplish this a warning is issue and the rays are returned in their original order. ‘roll’, ‘reverse’, and ‘reverse_and_roll’ will apply that operation to the rays in order to place them in time order, direct use of these is not recommended. ‘full’ will order the rays in strictly time increasing order, but the rays will likely become non-sequential, thisoption is not recommended unless strict time increasing order is required.

full_xhdr : bool or None

Flag to read in all extended headers for possible decoding. None will determine if extended headers should be read in automatically by examining the extended header type.

noaa_hh_hdr : bool or None

Flag indicating if the extended header should be decoded as those used by the NOAA Hurricane Hunters aircraft radars. None will determine if the extended header is of this type automatically by examining the header. The full_xhdr parameter is set to True when this parameter is True.

ignore_xhdr : bool, optional

True to ignore all data in the extended headers if they exist. False, the default, extracts milliseconds precision times and other parameter from the extended headers if they exists in the file.

ignore_sweep_start_ms : bool or None, optional

True to ignore the millisecond parameter in the start time for each sweep, False will uses this parameter when determining the timing of each ray. None, the default, will ignore the millisecond sweep start timing only when the file does not contain extended headers or when the extended header has been explicity ignored using the ignore_xhdr parameter. The TRMM RSL library ignores these times so setting this parameter to True is required to match the times determined when reading Sigmet files with pyart.io.read_rsl(). When there are not extended headers ignoring the millisecond sweep times provides time data which is always prior to the actual collection time with an error from 0 to 2 seconds.

debug : bool, optional

Print debug information during read.

Returns:

radar : Radar

Radar object.

pyart.io.read_uf(filename, field_names=None, additional_metadata=None, file_field_names=False, exclude_fields=None, include_fields=None, delay_field_loading=False, **kwargs)

Read a UF File.

Parameters:

filename : str or file-like

Name of Universal format file to read data from.

field_names : dict, optional

Dictionary mapping UF data type names to radar field names. If a data type found in the file does not appear in this dictionary or has a value of None it will not be placed in the radar.fields dictionary. A value of None, the default, will use the mapping defined in the Py-ART configuration file.

additional_metadata : dict of dicts, optional

Dictionary of dictionaries to retrieve metadata from during this read. This metadata is not used during any successive file reads unless explicitly included. A value of None, the default, will not introduce any addition metadata and the file specific or default metadata as specified by the Py-ART configuration file will be used.

file_field_names : bool, optional

True to force the use of the field names from the file in which case the field_names parameter is ignored. False will use to field_names parameter to rename fields.

exclude_fields : list or None, optional

List of fields to exclude from the radar object. This is applied after the file_field_names and field_names parameters. Set to None to include all fields specified by include_fields.

include_fields : list or None, optional

List of fields to include from the radar object. This is applied after the file_field_names and field_names parameters. Set to None to include all fields not specified by exclude_fields.

delay_field_loading : bool

This option is not implemented in the function but included for compatibility.

Returns:

radar : Radar

Radar object.

pyart.io.write_cfradial(filename, radar, format='NETCDF4', time_reference=None, arm_time_variables=False, physical=True)

Write a Radar object to a CF/Radial compliant netCDF file.

The files produced by this routine follow the CF/Radial standard. Attempts are also made to to meet many of the standards outlined in the ARM Data File Standards.

To control how the netCDF variables are created, set any of the following keys in the radar attribute dictionaries.

• _Zlib
• _DeflateLevel
• _Shuffle
• _Fletcher32
• _Continguous
• _ChunkSizes
• _Endianness
• _Least_significant_digit
• _FillValue

See the netCDF4 documentation for details on these settings.

Parameters:

filename : str

Filename to create.

radar : Radar

Radar object.

format : str, optional

NetCDF format, one of ‘NETCDF4’, ‘NETCDF4_CLASSIC’, ‘NETCDF3_CLASSIC’ or ‘NETCDF3_64BIT’. See netCDF4 documentation for details.

time_reference : bool

True to include a time_reference variable, False will not include this variable. The default, None, will include the time_reference variable when the first time value is non-zero.

arm_time_variables : bool

True to create the ARM standard time variables base_time and time_offset, False will not create these variables.

physical : bool

True to store the radar fields as physical numbers, False will store the radar fields as binary if the keyword ‘_Write_as_dtype’ is in the field metadata. The gain and offset can be specified in the keyword ‘scale_factor’ and ‘add_offset’ or calculated on the fly.

pyart.io.write_grid(filename, grid, format='NETCDF4', write_proj_coord_sys=True, proj_coord_sys=None, arm_time_variables=False, arm_alt_lat_lon_variables=False, write_point_x_y_z=False, write_point_lon_lat_alt=False)

Write a Grid object to a CF-1.5 and ARM standard netCDF file.

To control how the netCDF variables are created, set any of the following keys in the grid attribute dictionaries.

• _Zlib
• _DeflateLevel
• _Shuffle
• _Fletcher32
• _Continguous
• _ChunkSizes
• _Endianness
• _Least_significant_digit
• _FillValue

See the netCDF4 documentation for details on these settings.

Parameters:

filename : str

Filename to save grid to.

grid : Grid

Grid object to write.

format : str, optional

netCDF format, one of ‘NETCDF4’, ‘NETCDF4_CLASSIC’, ‘NETCDF3_CLASSIC’ or ‘NETCDF3_64BIT’. See netCDF4 documentation for details.

write_proj_coord_sys bool, optional

True to write information on the coordinate transform used in the map projection to the ProjectionCoordinateSystem variable following the CDM Object Model. The resulting file should be interpreted as containing geographic grids by tools which use the Java NetCDF library (THREDDS, toolsUI, etc).

proj_coord_sys : dict or None, optional

Dictionary of parameters which will be written to the ProjectionCoordinateSystem NetCDF variable if write_proj_coord_sys is True. A value of None will attempt to generate an appropriate dictionary by examining the projection attribute of the grid object. If the projection is not understood a warnings will be issued.

arm_time_variables : bool, optional

True to write the ARM standard time variables base_time and time_offset. False will not write these variables.

arm_alt_lat_lon_variables : bool, optional

True to write the ARM standard alt, lat, lon variables. False will not write these variables.

write_point_x_y_z : bool, optional

True to include the point_x, point_y and point_z variables in the written file, False will not write these variables.

write_point_lon_lat_alt : bool, optional

True to include the point_longitude, point_latitude and point_altitude variables in the written file, False will not write these variables.

pyart.io.write_grid_geotiff(grid, filename, field, rgb=False, level=None, cmap='viridis', vmin=0, vmax=75, color_levels=None, warp=False, sld=False, use_doublequotes=False)

Write a Py-ART Grid object to a GeoTIFF file.

The GeoTIFF can be the standard Azimuthal Equidistant projection used in Py-ART, or a lat/lon projection on a WGS84 sphere. The latter is typically more usable in web mapping applications. The GeoTIFF can contain a single float-point raster band, or three RGB byte raster bands. The former will require an SLD file for colorful display using standard GIS or web mapping software, while the latter will show colors “out-of-the-box” but lack actual data values. The function also can output an SLD file based on the user-specified inputs. User can specify the 2D vertical level to be output. If this is not specified, a 2D composite is created. User also can specify the field to output.

This function requires GDAL Python libraries to be installed. These are available via conda; e.g., ‘conda install gdal’

Parameters:

grid : pyart.core.Grid object

Grid object to write to file.

filename : str

Filename for the GeoTIFF.

field : str

Field name to output to file.

Other Parameters:  

rbg : bool, optional

True - Output 3-band RGB GeoTIFF

False - Output single-channel, float-valued GeoTIFF. For display,

likely will need an SLD file to provide a color table.

level : int or None, optional

Index for z-axis plane to output. None gives composite values (i.e., max in each vertical column).

cmap : str or matplotlib.colors.Colormap object, optional

Colormap to use for RGB output or SLD file.

vmin : int or float, optional

Minimum value to color for RGB output or SLD file.

vmax : int or float, optional

Maximum value to color for RGB output or SLD file.

color_levels : int or None, optional

Number of color levels in cmap. Useful for categorical colormaps with steps << 255 (e.g., hydrometeor ID).

warp : bool, optional

True - Use gdalwarp (called from command line using os.system)

to warp to a lat/lon WGS84 grid.

False - No warping will be performed. Output will be Az. Equidistant.

sld : bool, optional

True - Create a Style Layer Descriptor file (SLD) mapped to vmin/vmax

and cmap. File is named same as output TIFF, except for .sld extension.

False - Don’t do this.

use_doublequotes : bool, optional

True - Use double quotes in the gdalwarp call (requires warp=True),

which may help if that command is producing and error like: ‘Translating source or target SRS failed’.

False - Use single quotes instead.

pyart.io.write_grid_mdv(filename, grid, mdv_field_names=None, field_write_order=None)

Write grid object to MDV file.

Create a MDV file containing data from the provided grid instance.

The MDV file will contain parameters from the ‘source’ key if contained in grid.metadata. If this key or parameters related to the radar location and name are not present in the grid a default or sentinel value. will be written in the MDV file in the place of the parameter.

Grid fields will be saved in float32 unless the _Write_as_dtype key is present.

Parameters:

filename : str or file-like object.

Filename of MDV file to create. If a file-like object is specified data will be written using the write method.

grid : Grid

Grid object from which to create MDV file.

mdv_field_names : dict or None, optional

Mapping between grid fields and MDV data type names. Field names mapped to None or with no mapping will be excluded from writing. If None, the same field names will be used.

field_write_order : list or None, optional

Order in which grid fields should be written out in the MDV file. None, the default, will determine a valid order automatically.

Notes

Do to limitations of the MDV format, not all grid objects are writable. To write a grid the following conditions must be satisfied:

• XY grid must be regular (equal spacing), Z can be irregular.
• The number of Z levels must not exceed 122.
• Fields can be encoded in the file using the ‘_Write_as_dtype’ key specifying one of ‘uint8’, ‘uint16’ or ‘float32’. Use the ‘scale_factor’ and ‘add_offset’ keys to specify scaling. Field data in the Grid object should be uncompressed, that is to say it has had the scaling applied.

pyart.io.write_uf(filename, radar, uf_field_names=None, radar_field_names=False, exclude_fields=None, field_write_order=None, volume_start=None, templates_extra=None)

Write a Radar object to a UF file.

Create a UF file containing data from the provided radar instance. The UF file will contain instrument parameters from the following dictionaries if they contained in radar.instrument_parameters:

• radar_beam_width_h
• radar_beam_width_v
• radar_receiver_bandwidth
• frequency
• pulse_width
• prt
• polarization_mode
• nyquist_velocity

If any of these parameter are not present a default or sentinel value will be written in the UF file in the place of the parameter. This is also true for the data in the scan_rate attribute.

Radar fields will be scaled and rounded to integer values when writing to UF files. The scale factor for each field can be specified in the _UF_scale_factor key for each field dictionary. If not specified the default scaling (100) will be used.

Parameters:

filename : str or file-like object.

Filename of UF file to create. If a file-like object is specified data will be written using the write method.

radar : Radar

Radar object from which to create UF file.

uf_field_names : dict or None, optional

Mapping between radar fields and two character UF data type names. Field names mapped to None or with no mapping will be excluded from writing. If None, the default mappings for UF files will be used.

radar_field_names : bool, optional

True to use the radar field names as the field names of the UF fields. False to use the uf_field_names mapping to generate UF field names. The exclude_fields argument can still be used to exclude fields from the UF file when this parameter is True. When reading a UF file using file_field_names=True set this parameter to True to write a UF file with the same field names.

exclude_fields : list or None, optional

List of radar fields to exclude from writing.

field_write_order : list or None, optional

Order in which radar fields should be written out in the UF file. None, the default, will determine a valid order automatically.

volume_start : datetime, optional

Start of volume used to set UF volume structure elements.

templates_extra : dict of dict or None

Advanced usage parameter for setting UF structure templates. Elements defined in dictionaries with keys ‘mandatory_header’, ‘optional_header’, and ‘field_header’ will be used to build the structure template.