API

Data sources

Point observations

In general, these modules provide an add_data function for retrieving data, for example, monetio.aeronet.add_data().

AERONET

See AERONET for more information.

monetio.aeronet.add_data([dates, product, ...])

Load AERONET data from the AERONET Web Service.

monetio.aeronet.add_local(fname, *[, freq, ...])

Read a local file downloaded from the AERONET Web Service.

monetio.aeronet.get_valid_sites()

Load the AERONET site list as a DataFrame, reading from https://aeronet.gsfc.nasa.gov/aeronet_locations_v3.txt.
monetio.aeronet.add_data(dates=None, product='AOD15', *, inv_type=None, latlonbox=None, siteid=None, daily=False, lunar=False, freq=None, detect_dust=False, interp_to_aod_values=None, n_procs=1, verbose=10)

Load AERONET data from the AERONET Web Service.

Parameters

  • dates (array-like of datetime-like) – Expressing the desired min and max dates to retrieve. If unset, the current day will be fetched.

  • product (str)

  • inv_type (str) – Inversion product type.

  • latlonbox (array-like of float) – [lat1, lon1, lat2, lon2], where lat1, lon1 is the lower-left corner and lat2, lon2 is the upper-right corner.

  • siteid (str) – Site identifier string.

    See https://aeronet.gsfc.nasa.gov/aeronet_locations_v3.txt for all valid site IDs.

    Warning

    Whether you will obtain data depends on the sites active during the dates time period.

    Note

    siteid takes precedence over latlonbox if both are specified.

  • daily (bool) – Load daily averaged data.

  • lunar (bool) – Load provisional lunar “Direct Moon” data instead of the default “Direct Sun”. Only for non-inversion products.

  • freq (str) – Frequency used to resample the DataFrame.

  • detect_dust (bool)

  • interp_to_aod_values (array-like of float) – Values to interpolate AOD values to.

    Currently requires pytspack.

  • n_procs (int) – For joblib.

  • verbose (int) – For joblib.

Returns

pandas.DataFrame

monetio.aeronet.add_local(fname, *, freq=None, detect_dust=False, interp_to_aod_values=None)

Read a local file downloaded from the AERONET Web Service.

Parameters

fname – Suitable input for pandas.read_csv(), e.g. a relative path as a string or a path-like.

monetio.aeronet.get_valid_sites()

Load the AERONET site list as a DataFrame, reading from https://aeronet.gsfc.nasa.gov/aeronet_locations_v3.txt.

AirNow

See AirNow for more information.

monetio.airnow.add_data(dates, *[, ...])

Retrieve and load AirNow data as a DataFrame.
monetio.airnow.add_data(dates, *, download=False, wide_fmt=True, n_procs=1, daily=False, bad_utcoffset='drop')

Retrieve and load AirNow data as a DataFrame.

Note: to obtain full hourly data you must pass all desired hours in dates.

Parameters

  • dates (array-like of datetime-like) – Passed to build_urls().

  • download (bool, optional) – Whether to first download the AirNow files to the local directory.

  • wide_fmt (bool)

  • n_procs (int) – For Dask.

  • daily (bool) – Whether to get daily data only (only unique days in dates will be used).

    Info: https://files.airnowtech.org/airnow/docs/DailyDataFactSheet.pdf

    Note: daily_data_v2.dat (includes AQI) is not available for all times, so we use daily_data.dat.

  • bad_utcoffset ({'null', 'drop', 'fix', 'leave'}, default: 'drop') – How to handle bad UTC offsets (i.e. rows with UTC offset 0 but abs(longitude) > 20 degrees). 'fix' will use timezonefinder if it is installed.

Returns

pandas.DataFrame

Profile observations

GEOMS – The Generic Earth Observation Metadata Standard

This is a format for storing profile data, used by several LiDAR networks.

It is currently TOLNet’s format of choice.

For more info, see: https://evdc.esa.int/documentation/geoms/

monetio.geoms.open_dataset(fp, *[, ...])

Open a file in GEOMS format, e.g.
monetio.geoms.open_dataset(fp, *, rename_all=True, squeeze=True)

Open a file in GEOMS format, e.g. modern TOLNet files.

Parameters

  • fp – File path.

  • rename_all (bool, default: True) – Rename all non-coordinate variables:

    • lowercase

    • convert . to _

    as done for the coordinate variables regardless of this setting. These conversions allow for easy access to the variables as attributes, e.g.

    ds.integration_time

  • squeeze (bool, default: True) – Apply .squeeze() before returning the Dataset. This simplifies working with the Dataset for the case of one instrument/location.

Returns

xarray.Dataset

Utility functions

There are a few top-level utility functions.

monetio.rename_latlon(ds)

Rename latitude/longitude to 'lat'/'lon'.

monetio.rename_to_monet_latlon(ds)

Rename latitude/longitude to 'latitude'/'longitude'.

monetio.dataset_to_monet(ds, *[, lat_name, ...])

Apply coards_to_netcdf() if latlon2d is False.

monetio.coards_to_netcdf(ds, *[, lat_name, ...])

Assign 2-D latitude/longitude grid from 1-D latitude/longitude variables, setting 'x' and 'y' as 1-D zero-based index arrays.

Grid tools

monetio.grids