monetio

coards_to_netcdf(ds, *, lat_name='lat', lon_name='lon')

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

Also normalizes the latitude/longitude names to 'latitude'/'longitude', with dimensions ('y', 'x').

.. note:: The name is a reference to the COARDS conventions.

Parameters:

Name	Type	Description	Default
ds	Dataset		required
lat_name	str	Current latitude and longitude names in ds.	'lat'
lon_name	str	Current latitude and longitude names in ds.	'lat'

Returns:

Type	Description
Dataset

Source code in monetio/__init__.py

def coards_to_netcdf(ds, *, lat_name="lat", lon_name="lon"):
    """Assign 2-D latitude/longitude grid from 1-D latitude/longitude variables,
    setting ``'x'`` and ``'y'`` as 1-D zero-based index arrays.

    Also normalizes the latitude/longitude names to ``'latitude'``/``'longitude'``,
    with dimensions ``('y', 'x')``.

    .. note::
       The name is a reference to the COARDS conventions.

    Parameters
    ----------
    ds : xarray.Dataset
    lat_name, lon_name : str
        Current latitude and longitude names in `ds`.

    Returns
    -------
    xarray.Dataset
    """
    from numpy import arange, meshgrid

    lon = ds[lon_name]
    lat = ds[lat_name]
    assert lon.ndim == lat.ndim == 1
    lons, lats = meshgrid(lon, lat)
    x = arange(len(lon))
    y = arange(len(lat))
    ds = ds.rename({lon_name: "x", lat_name: "y"})
    ds.coords["longitude"] = (("y", "x"), lons)
    ds.coords["latitude"] = (("y", "x"), lats)
    ds["x"] = x
    ds["y"] = y
    ds = ds.set_coords(["latitude", "longitude"])
    return ds

dataset_to_monet(ds, *, lat_name='lat', lon_name='lon', latlon2d=None)

Apply :func:coards_to_netcdf if latlon2d is False.

Parameters:

Name	Type	Description	Default
ds	Dataset		required
lat_name	str	Current latitude and longitude names in ds.	'lat'
lon_name	str	Current latitude and longitude names in ds.	'lat'
latlon2d	bool	If not provided, the value will be detected by examining .ndim of the latitude variable.	None

Returns:

Type	Description
Dataset

Source code in monetio/__init__.py

def dataset_to_monet(ds, *, lat_name="lat", lon_name="lon", latlon2d=None):
    """Apply :func:`coards_to_netcdf` if `latlon2d` is False.

    Parameters
    ----------
    ds : xarray.Dataset
    lat_name, lon_name : str
        Current latitude and longitude names in `ds`.
    latlon2d : bool, optional
        If not provided, the value will be detected by examining ``.ndim``
        of the latitude variable.

    Returns
    -------
    xarray.Dataset
    """
    if latlon2d is None:
        ndim_lat = ds[lat_name].ndim
        assert ndim_lat <= 2
        latlon2d = ndim_lat == 2
    # TODO: apply rename_to_monet_latlon ?
    if latlon2d is False:
        ds = coards_to_netcdf(ds, lat_name=lat_name, lon_name=lon_name)
    return ds

load(source, files=None, **kwargs)

Universal load function.

Usage: ds = monetio.load("cmaq", files="/path/to/data*.nc") df = monetio.load("airnow", files=["2023-01-01", "2023-01-02"])

Available sources: Models: cmaq, camx, chimere, hysplit, hytraj, icap_mme, ncep_grib, pardump, raqms, ufs, wrfchem, grib2, gfs, gefs, gdas, rrfs Obs: airnow, aeronet, aqs, cems, crn, eprofile, improve, ish, ish_lite, nadp, ndacc, ndbc, openaq, openaq_v2, openaq_aws, pams, pandora, skynet, solrad, surfrad Profile: actris, earlinet, geoms, gml_ozonesonde, iagos, icartt, igra2, mplnet, tolnet, umbc_aerosol Sat: goes, merra2, modis_l2, modis_ornl, mopitt, nasa_modis, nesdis_edr_viirs, nesdis_eps_viirs, nesdis_frp, nesdis_viirs_jrr, omps, omps_nadir, tempo, tropomi, viirs_jrr

Source code in monetio/__init__.py

def load(source: str, files=None, **kwargs):
    """
    Universal load function.

    Usage:
        ds = monetio.load("cmaq", files="/path/to/data*.nc")
        df = monetio.load("airnow", files=["2023-01-01", "2023-01-02"])

    Available sources:
        Models: cmaq, camx, chimere, hysplit, hytraj, icap_mme, ncep_grib, pardump, raqms, ufs, wrfchem, grib2, gfs, gefs, gdas, rrfs
        Obs: airnow, aeronet, aqs, cems, crn, eprofile, improve, ish, ish_lite, nadp, ndacc, ndbc, openaq, openaq_v2, openaq_aws, pams, pandora, skynet, solrad, surfrad
        Profile: actris, earlinet, geoms, gml_ozonesonde, iagos, icartt, igra2, mplnet, tolnet, umbc_aerosol
        Sat: goes, merra2, modis_l2, modis_ornl, mopitt, nasa_modis, nesdis_edr_viirs, nesdis_eps_viirs, nesdis_frp, nesdis_viirs_jrr, omps, omps_nadir, tempo, tropomi, viirs_jrr
    """
    from .readers.base import READER_REGISTRY

    if source not in READER_REGISTRY:
        if source in _READER_MODULES:
            # Lazy import
            importlib.import_module(_READER_MODULES[source], package="monetio")
        else:
            raise ValueError(
                f"Unknown source '{source}'. Available: {list(_READER_MODULES.keys())}"
            )

    if source not in READER_REGISTRY:
        # Should be registered by now if module was valid
        raise RuntimeError(f"Source '{source}' found in lazy index but failed to register itself.")

    # Instantiate the reader class and open data
    reader_cls = READER_REGISTRY[source]
    reader = reader_cls()

    return reader.open_dataset(files=files, **kwargs)

rename_latlon(ds)

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

Parameters:

Name	Type	Description	Default
ds	Dataset		required

Returns:

Type	Description
Dataset	Dataset with possibly renamed latitude/longitude.

Source code in monetio/__init__.py

def rename_latlon(ds):
    """Rename latitude/longitude to ``'lat'``/``'lon'``.

    Parameters
    ----------
    ds : xarray.Dataset

    Returns
    -------
    xarray.Dataset
        Dataset with possibly renamed latitude/longitude.
    """
    if "latitude" in ds.coords:
        return ds.rename({"latitude": "lat", "longitude": "lon"})
    elif "Latitude" in ds.coords:
        return ds.rename({"Latitude": "lat", "Longitude": "lon"})
    elif "Lat" in ds.coords:
        return ds.rename({"Lat": "lat", "Lon": "lon"})
    else:
        return ds

rename_to_monet_latlon(ds)

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

Parameters:

Name	Type	Description	Default
ds	Dataset		required

Returns:

Type	Description
Dataset	Dataset with possibly renamed latitude/longitude.

See Also

rename_latlon : renames to 'lat'/'lon' instead

Source code in monetio/__init__.py

def rename_to_monet_latlon(ds):
    """Rename latitude/longitude to ``'latitude'``/``'longitude'``.

    Parameters
    ----------
    ds : xarray.Dataset

    Returns
    -------
    xarray.Dataset
        Dataset with possibly renamed latitude/longitude.

    See Also
    --------
    rename_latlon : renames to ``'lat'``/``'lon'`` instead
    """
    if "lat" in ds.coords:
        return ds.rename({"lat": "latitude", "lon": "longitude"})
    elif "Latitude" in ds.coords:
        return ds.rename({"Latitude": "latitude", "Longitude": "longitude"})
    elif "Lat" in ds.coords:
        return ds.rename({"Lat": "latitude", "Lon": "longitude"})
    elif "grid_lat" in ds.coords:
        return ds.rename({"grid_lat": "latitude", "grid_lon": "longitude"})
    else:
        return ds

virtualize(source, files=None, output=None, backend='kerchunk', **kwargs)

Pre-process files into a virtual reference (e.g., Kerchunk JSON or Icechunk repo).

Usage: monetio.virtualize("merra2", files="data/*.nc4", output="merra2_ref.json")

Parameters:

Name	Type	Description	Default
source	str	The reader source ID (e.g., "merra2", "gfs").	required
files	str or list of str	File path(s) or glob pattern(s).	None
output	str	Path to save the output reference (required for 'kerchunk' backend).	None
backend	str	The virtualization backend. Must be "kerchunk" (default) or "icechunk".	'kerchunk'
**kwargs	dict	Additional arguments passed to the reader and driver.	{}

Source code in monetio/__init__.py

def virtualize(source: str, files=None, output: str = None, backend: str = "kerchunk", **kwargs):
    """
    Pre-process files into a virtual reference (e.g., Kerchunk JSON or Icechunk repo).

    Usage:
        monetio.virtualize("merra2", files="data/*.nc4", output="merra2_ref.json")

    Parameters
    ----------
    source : str
        The reader source ID (e.g., "merra2", "gfs").
    files : str or list of str, optional
        File path(s) or glob pattern(s).
    output : str, optional
        Path to save the output reference (required for 'kerchunk' backend).
    backend : str, optional
        The virtualization backend. Must be "kerchunk" (default) or "icechunk".
    **kwargs : dict
        Additional arguments passed to the reader and driver.
    """
    if backend == "kerchunk" and output is None:
        raise ValueError("The 'output' parameter is required for the 'kerchunk' backend.")

    return load(
        source,
        files=files,
        use_virtualizarr=True,
        virtualizarr_file=output,
        virtualizarr_backend=backend,
        **kwargs,
    )