nsidc.iceflow package

Copyright (c) 2025 NSIDC. All rights reserved.

iceflow: Harmonized access to (pre)OIB/IceSAT/IceSAT2 data

Users interact with nsidc-iceflow by:

  • Searching for data that match an area of interest/time (find_iceflow_data)

  • Downloading data (download_iceflow_results)

  • (Optional) Creating a parquet datastore to facilitate reading the data (make_iceflow_parquet)

  • Reading and doing analysis with the data (dask.dataframe.read_parquet, read_iceflow_datafiles)

  • (Optional, if using read_iceflow_datafiles) Transform the lat/lon/elev data into a target International Terrestrial Reference Frame (ITRF) (transform_itrf)

class nsidc.iceflow.BLATM1BDataset(**data)

Bases: ATM1BDataset

Parameters:

data (Any)

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

short_name: ATM1BShortName
version: Literal['1']
class nsidc.iceflow.Dataset(**data)

Bases: BaseModel

Parameters:

data (Any)

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

short_name: DatasetShortName
property subdir_name
version: str
class nsidc.iceflow.GLAH06Dataset(**data)

Bases: Dataset

Parameters:

data (Any)

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

short_name: DatasetShortName
version: Literal['034']
class nsidc.iceflow.ILATM1BDataset(**data)

Bases: ATM1BDataset

Parameters:

data (Any)

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

short_name: ATM1BShortName
version: Literal['1', '2']
class nsidc.iceflow.ILVIS2Dataset(**data)

Bases: Dataset

Parameters:

data (Any)

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

short_name: DatasetShortName
version: Literal['1', '2']
nsidc.iceflow.download_iceflow_results(iceflow_search_results, output_dir)
Parameters:
Return type:

list[Path]

nsidc.iceflow.find_iceflow_data(*, datasets=[ILATM1BDataset(short_name='ILATM1B', version='1'), ILATM1BDataset(short_name='ILATM1B', version='2'), BLATM1BDataset(short_name='BLATM1B', version='1'), ILVIS2Dataset(short_name='ILVIS2', version='1'), ILVIS2Dataset(short_name='ILVIS2', version='2'), GLAH06Dataset(short_name='GLAH06', version='034')], **search_kwargs)

Find iceflow-compatible data using search kwargs.

search_kwargs are passed to earthaccess.search_data, allowing for CMR-supported filters (see https://cmr.earthdata.nasa.gov/search/site/docs/search/api.html)

Parameters:

datasets (list[Dataset])

Return type:

list[IceflowSearchResult]

nsidc.iceflow.make_iceflow_parquet(*, data_dir, target_itrf, overwrite=False, target_epoch=None, ilvis2_coordinate_set='low_mode')

Create a parquet dataset containing the lat/lon/elev data in data_dir.

This function creates a parquet dataset that can be easily used alongside dask, containing lat/lon/elev data. Users who are interested in the full data record with all fields provided by data in the data_dir should use read_iceflow_datafiles.

Note: this function writes a single iceflow.parquet to the output dir. This code does not currently support updates to the parquet after being written. This is intended to help facilitate analysis of a specific area over time. If an existing iceflow.parquet exists and the user wants to create a new iceflow.parquet for a different area or timespan, they will need to move/remove the existing iceflow.parquet first (e.g., with the overwrite=True kwarg).

Parameters:
Return type:

Path

nsidc.iceflow.read_iceflow_datafiles(filepaths, ilvis2_coordinate_set='low_mode')
Parameters:

  • filepaths (list[Path])

  • ilvis2_coordinate_set (Literal['low_mode', 'high_mode', 'centroid', 'highest_signal'])

Return type:

DataFrame[CommonDataColumnsSchema]

nsidc.iceflow.transform_itrf(data, target_itrf, target_epoch=None, plate=None, pmm_use_orb=True)

Transform the data’s latitude/longitude/elevation variables from the source ITRF to the target ITRF.

If a target_epoch is given, coordinate propagation is performed via a plate motion model (PMM) defined for the target_itrf. The target epoch determines the number of years into the future/past the observed points should be propagated. For example, if a point’s observation date (t_observed) is 1993.0 (1993-01-01T00:00:00) and the target_epoch is 2011.0 (2011-01-01T00:00:00), the point will be propagated forward 18 years. Note that not all ITRFs have PMMs defined for them. The PMM used is defined for the target_epoch, so it is likely to be most accurate for points observed near the ITRF’s defined epoch.

If pmm_use_orb is True, then this function will use Origin Rate Bias (ORB) parameters for the selected PMM, if available (e.g., ITRF2020 and ITRF2008 init files have ORB parameters defined; ITRF2014 has no ORB parameter sets), for the horizontal component of each point (longitude and latitude). The vertical component (elevation) will be transformed without ORB parameters applied.

All ITRF and PMM transformations are dependent on the user’s proj installation’s ITRF init files (see https://proj.org/en/9.3/resource_files.html#init-files). For example, ITRF2014 parameters are defined here: https://github.com/OSGeo/PROJ/blob/8b65d5b14e2a8fbb8198335019488a2b2968df5c/data/ITRF2014.

Note that ILVIS2 data contain more than one set of latitude/longitude/elevation variables (e.g., HLAT/HLON/ZH, CLAT/CLON/ZC). This function only transforms the primary latitude/longitude/elevation fields in the provided dataframe. Use the ilvis2_coordinate_set kwarg on read_iceflow_datafile(s) to select an different primary set of latitude/longitude/elevation fields. Alternatively, manually set the fields: ``` # TLAT/TLON/TZ are only available in ILVIS2v2 data: sel_ilvis2v2 = data.dataset == “ILVIS2v2” data.loc[sel_ilvis2v2, [“latitude”, “longitude”, “elevation”]] = data.loc[sel_ilvis2v2, [“TLAT”, “TLON”, “ZT”]]

```

Parameters:
Return type:

DataFrame[CommonDataColumnsSchema]

Subpackages

Submodules

nsidc.iceflow.api module

Module with functions defining the user-facing API for nsidc-iceflow.

nsidc.iceflow.api.make_iceflow_parquet(*, data_dir, target_itrf, overwrite=False, target_epoch=None, ilvis2_coordinate_set='low_mode')

Create a parquet dataset containing the lat/lon/elev data in data_dir.

This function creates a parquet dataset that can be easily used alongside dask, containing lat/lon/elev data. Users who are interested in the full data record with all fields provided by data in the data_dir should use read_iceflow_datafiles.

Note: this function writes a single iceflow.parquet to the output dir. This code does not currently support updates to the parquet after being written. This is intended to help facilitate analysis of a specific area over time. If an existing iceflow.parquet exists and the user wants to create a new iceflow.parquet for a different area or timespan, they will need to move/remove the existing iceflow.parquet first (e.g., with the overwrite=True kwarg).

Parameters:
Return type:

Path