lenapy.readers.gravi_reader

The gravi_reader module provides functions to load time-variable gravity field data from different products and format the data with unified definitions for variables and coordinates.

Standardized coordinates names:

l, m, time

Standardized variables names:

clm, slm, begin_time, end_time, exact_time (and eclm, eslm if available)

Supported Formats:

GRACE Level-2 products from SDS centers (use engine=’lenapyGraceL2’ in
xr.open_dataset() or xr.mfopen_dataset())
Gravity field products organized as .gfc files (use ‘lenapyGfc’` in
xr.open_dataset() or xr.mfopen_dataset())

Dask is implicitly used when using these interface methods.

Examples

>>> import os
>>> import xarray as xr
# Load GRACE Level-2 data
>>> files_csr = [os.path.join(csr_data_dir, f) for f in os.listdir(csr_data_dir)]
>>> ds_csr = xr.open_mfdataset(files_csr, engine='lenapyGraceL2', combine_attrs="drop_conflicts")
# Load gravity field data from .gfc files
>>> files_graz = [os.path.join(graz_data_dir, f) for f in os.listdir(graz_data_dir)]
>>> ds_graz = xr.open_mfdataset(files_graz, engine='lenapyGfc', combine_attrs="drop_conflicts")

lenapy.readers.gravi_reader.read_tn14(filename: str | PathLike, rmmean: bool = False) → Dataset[source]

Read TN14 data to produce a dataset with C20 and C30 information. Handles dates in the same way as others GRACE products. TN14 data can be downloaded from https://podaac.jpl.nasa.gov/gravity/grace-documentation.

Parameters:

filename (str | os.PathLike[Any]) – Path to the TN14 file.
rmmean (bool, optional) – If True, use data without mean values. Default is False (use data with mean values).

Returns:

ds – Dataset with C20 and C30 information.

Return type:

xr.Dataset

lenapy.readers.gravi_reader.read_tn13(filename: str | PathLike) → Dataset[source]

Read TN13 data to produce a dataset with C10, C11 and S11 information. Handles dates in the same way as other GRACE products. TN13 data can be downloaded from https://podaac.jpl.nasa.gov/gravity/grace-documentation.

Parameters:: filename (str | os.PathLike[Any]) – Path to the TN13 file.
Returns:: ds – Dataset with C10, C11, and S11 information.
Return type:: xr.Dataset

class lenapy.readers.gravi_reader.ReadGFC[source]

Bases: BackendEntrypoint

open_dataset_parameters: ClassVar[tuple | None] = ['filename_or_obj', 'drop_variables', 'no_date', 'date_regex', 'date_format']

open_dataset(filename: str | PathLike, drop_variables: None = None, no_date: bool = False, date_regex: str | None = None, date_format: str | None = None) → Dataset[source]

Read a .gfc ASCII file (or compressed) and format it as a xr.Dataset. The file needs to follow the ICGEM format: https://icgem.gfz-potsdam.de/docs/ICGEM-Format-2023.pdf

The header information are stored in ds.attrs. The dataset contains clm and slm arrays with error information in eclm and eslm if available. For monthly files, time variables are stored as ‘begin_time’, ‘end_time’, ‘exact_time’ and ‘mid_month’. ‘mid_month’ is used as the time coordinate.

The time information of the file is read in the mandatory header information ‘modelname’. The function search by default a date of format ‘YYYY-MM’ or ‘_YYYYDOY-YYYYDOY’. The format of the date can be specified with the arguments date_regex and date_format. If the file not associated with a date information, use no_date=True.

Parameters:

filename (str | os.PathLike[Any]) – Name/path of the file to open.
drop_variables (None) – Not used; included for compatibility with BackendEntrypoint pattern.
no_date (bool, optional) – True if the data file contains no date information. Default is False.
date_regex (str | None, optional) – A regular expression pattern used to search for the date in the modelname header information. It should contain at least one capturing group for the begin_time, and optionally a second group for the end_time.
date_format (str | None, optional) – A format string compatible with datetime.strptime to parse the extracted date strings. Must be provided if date_regex is specified.

Returns:

ds – Information from the file stored in xr.Dataset format.

Return type:

xr.Dataset

Examples

Default usage with automatic date extraction: >>> ds = xr.open_mfdataset(‘path/to/file.gfc’, engine=’lenapyGfc’)

Specify custom date pattern and format: >>> s = xr.open_mfdataset(‘path/to/file.gfc’, engine=’lenapyGfc’, … date_regex=r’_(d{8})-(d{8})’, date_format=’%Y%m%d’)

No date information in the file: >>> ds = xr.open_mfdataset(‘path/to/file.gfc’, engine=’lenapyGfc’, no_date=True)

guess_can_open(filename: str | PathLike) → bool[source]

Test the readability of a file with ReadGFC. Test if it is a .gfc file.

Parameters:: filename (str | os.PathLike[Any]) – Path to the file to test.
Returns:: can_open – True if the file can be opened with ReadGFC, False otherwise.
Return type:: bool

description: ClassVar[str] = 'Use .gfc files in xarray'

class lenapy.readers.gravi_reader.ReadGRACEL2[source]

Bases: BackendEntrypoint

open_dataset_parameters: ClassVar[tuple | None] = ['filename_or_obj', 'drop_variables']

open_dataset(filename: str | PathLike, drop_variables: None = None) → Dataset[source]

Read a GRACE Level-2 gravity field product ASCII file (or compressed) from processing centers and format it as a xr.Dataset. The header information are stored in ds.attrs. The dataset contains clm and slm array with errors information in eclm and eslm if possible. For monthly files, time variables are stored as ‘begin_time’, ‘end_time’, ‘exact_time’ and ‘mid_month’. ‘mid_month’ is used as the time coordinate.

Parameters:

filename (str | os.PathLike[Any]) – Name/path of the file to open.
drop_variables (None) – Not used; included for compatibility with BackendEntrypoint pattern.

Returns:

ds – Information from the file stored in xr.Dataset format.

Return type:

xr.Dataset

description: ClassVar[str] = 'Use GRACEL2 product files in xarray'

class lenapy.readers.gravi_reader.ReadShLoading[source]

Bases: BackendEntrypoint

open_dataset_parameters: ClassVar[tuple | None] = ['filename_or_obj', 'drop_variables']

open_dataset(filename: str | PathLike, drop_variables=None) → Dataset[source]

Read Loading models in ASCII file (or compressed) from http://loading.u-strasbg.fr and format it as a xr.Dataset. The header information are stored in ds.attrs. The dataset contains clm and slm array. ‘mid_month’ is used as the time coordinate.

Parameters:

filename (str | os.PathLike[Any]) – Name/path of the file to open.
drop_variables (None) – Not used; included for compatibility with BackendEntrypoint pattern.

Returns:

ds – Information from the file stored in xr.Dataset format.

Return type:

xr.Dataset

description: ClassVar[str] = 'Use loading models files from http://loading.u-strasbg.fr in xarray'