API Reference

This page contains the detailed API reference for CryoGrid-pyTools.

Excel Config file

cryogrid_pytools.CryoGridConfigExcel

A class to read CryoGrid Excel configuration files and extract file paths and maybe in the future do some checks etc

get_class

Return DataFrame blocks representing the specified class from the Excel data.

Parameters:

Name	Type	Description	Default
class_name	str	The class name to look up (e.g., 'DEM', 'READ_DATASET').	required

Returns:

Type	Description
DataFrame	The concatenated DataFrame of class blocks.

get_classes

Useful to find all the classes available in the Excel file. Returns a dictionary of class names and their corresponding row indices from the Excel file. To use as a reference for get_class().

Returns:

Type	Description
dict of int: str	A dictionary mapping class names to row indices

get_coord_path

Get the path to the coordinates file from the Excel configuration.

Returns:

Type	Description
Path	The file path for coordinates.

get_dem_path

Get the path for the DEM file from the Excel configuration.

Returns:

Type	Description
Path	The DEM file path.

get_output_max_depth

Get the maximum depth of the output file from the Excel configuration.

Parameters:

Name	Type	Description	Default
output_class	str	The class name to search for in the configuration, by default 'OUT_regridded'.	'OUT_regridded'

Returns:

Type	Description
float	The maximum depth value.

Reading profile outputs

cryogrid_pytools.read_OUT_regridded_file

Read a CryoGrid OUT_regridded[_FCI2] file and return it as an xarray dataset.

Parameters:

Name	Type	Description	Default
fname	str	Path to the .mat file	required
deepest_point	float	Represents the deepest depth of the profile relative to the surfface. If not provided, then elevation is returned. Negative values represent depths below the surface.	None

Returns:

Name	Type	Description
ds	Dataset	Dataset with dimensions 'time' and 'level'. The elevation coordinate represents the elevation above sea level based on the DEM. If deepest_point is provided, then an additional coordinate, depth, represents depth above surface.

Notes

For plotting, use `ds['variable'].plot(y='depth'/'elevation').

cryogrid_pytools.read_OUT_regridded_files

Reads multiple files that are put out by the OUT_regridded class (and _FCI2)

Parameters:

Name	Type	Description	Default
fname_glob	str	Path of the files that you want to read in. Use same notation as for glob(). Note that it expects name to follow the format some_project_name_GRIDCELL_ID_date.mat where GRIDCELL_ID will be extracted to assign the gridcell dimension. These GRIDCELL_IDs correspond with the index of the data in the flattened array.	required
deepest_point	Union[float, None]	The depth below the surface that each profile is saved. If None, then depth is not returned as a coordinate.	None
joblib_kwargs		Uses the joblib library to do parallel reading of the files. Defaults are: n_jobs=-1, backend='threading', verbose=1	{}

Returns:

Type	Description
Dataset	An array with dimensions gridcell, depth, time. Variables depend on how the class was configured, but elevation will also be a variable.

cryogrid_pytools.read_mat_struct_flat_as_dict

Read a MATLAB struct from a .mat file and return it as a dictionary.

Assumes that the struct is flat, i.e. it does not contain any nested structs.

Parameters:

Name	Type	Description	Default
fname	str	Path to the .mat file	required
key	str	The name of the matlab key in the .mat file. If None is passed [default], then the first key that does not start with an underscore is used. If a string is passed, then the corresponding key is used.	None

Returns:

Name	Type	Description
data	dict	Dictionary with the struct fields as keys and the corresponding data as values.

cryogrid_pytools.read_mat_struct_as_dataset

Read a MATLAB struct from a .mat file and return it as an xarray dataset.

Parameters:

Name	Type	Description	Default
fname	str	Path to the .mat file. All variables in the struct are assumed to have the same dimensions and shape (except for the index columns).	required
drop_keys	list	List of keys to drop from the struct. If None is passed [default], then no keys are dropped. This can be used when one of the struct fields is not the same shape as the others. Any dropped variables will be added back as DataArrays with their own dim.	[]
index	(str, tuple)	Name of the index column. If None is passed [default], then no index is set. If a tuple is passed, then the corresponding columns are used as a multiindex.	None
index_is_datenum	bool	If True, then the index is converted from MATLAB datenum to a pandas.Timestamp.	False

Returns:

Name	Type	Description
ds	Dataset	Dataset with the struct fields as variables and the corresponding data as values.

Reading clustering outputs

cryogrid_pytools.spatial_clusters.read_spatial_data

Opens run_spatial_info.mat that contains the spatial information for the run.

Note

You have to manually save this data since Python cannot read in the run_parameters.mat file. It needs to be a flat struct. Below is the MATLAB code to save the spatial data:

skip_fields = {'key'};
for field = fieldnames(run_info.SPATIAL.STATVAR)'
    field_item_spatial = field{1}; % Extract string
    if ~ismember(field_item_spatial, skip_fields)
        data.(field_item_spatial) = run_info.SPATIAL.STATVAR.(field_item_spatial);
    end
end

for field = fieldnames(run_info.CLUSTER.STATVAR)'
    field_item_cluster = field{1}; % Same fix here
    data.(field_item_cluster) = run_info.CLUSTER.STATVAR.(field_item_cluster);
end

sname = strcat(provider.PARA.result_path, provider.PARA.run_name, '/run_spatial_info.mat');
save(sname, 'data');

Parameters:

Name	Type	Description	Default
fname_spatial_mat	str	Path to the run_spatial_info.mat file	required
crs	str	Coordinate reference system of the spatial data (e.g., EPSG:32633) Get this from the DEM used in your run. If None, no CRS is added, by default None	None

Returns:

Name	Type	Description
ds	Dataset	Dataset with the spatial information. Contains the variables: 1D variables [cluster_num as dim]: - cluster_centroid_index: the index of the cluster centroid of each cluster with the cluster_num as the dimension 2D variables [y, x as dims]: - longitude / latitude - mask: mask of the indexs - all variables in run_info.SPATIAL.STATVAR - from run_info.CLUSTER.STATVAR - cluster_number: the cluster number that each index belongs to - cluster_number_mapped: a 2d representation of the cluster_number - cluster_centroid_index: the index of the cluster centroid with cluster_number as the dim - cluster_centroid_index_mapped: the index of the cluster centroid of each cluster

cryogrid_pytools.spatial_clusters.map_gridcells_to_clusters

Maps the single depth selection of the profiles to the 2D clusters

Parameters:

Name	Type	Description	Default
da	DataArray	Single depth selection of the profiles with index dimension only. Note that index must start at 1 (0 is reserved for masked data).	required
cluster_centroid_index_mapped	DataArray	2D array with the index of the cluster centroid of each cluster Must have dtype uint32. Can have 0 to represent masked data.	required

Returns:

Name	Type	Description
da_2d_mapped	DataArray	The 2D array of the profiles mapped to the clusters with the same shape as cluster_centroid_index_mapped. The 2D gridcells will also be given as a coordinate

Raises:

Type	Description
ValueError	If da (variable to be mapped) does not have index dimension only

ERA5 Forcing

cryogrid_pytools.forcing.read_mat_ear5

Read the ERA5.mat forcing file for CryoGrid and return a xarray Dataset.

Parameters:

Name	Type	Description	Default
filename	str	Path to the ERA5.mat file	required

Returns:

Type	Description
Dataset	Dataset with the variables from the ERA5.mat file

cryogrid_pytools.forcing.era5_to_matlab

Convert a merged netCDF file from the Copernicus CDS to a dictionary that matches the expected format of the CryoGrid.POST_PROC.read_mat_ERA class (in MATLAB).

Parameters:

Name	Type	Description	Default
ds	Dataset	Dataset from the ERA5 Copernicus CDS with variables required for the CryoGrid.POST_PROC.read_mat_ERA class single_levels = [u10, v10, sp, d2m, t2m, ssrd, strd, tisr, tp, Zs] pressure_levels = [t, z, q, u, v] Note that Zs in the single levels is a special case since it is only downloaded for a single date at the surface (doesn't change over time)	required
save_path	str	Path to save the dictionary as a .mat file, by default None, meaning no file is saved and only the dictionary is returned	None

Returns:

Type	Description
dict	Dictionary with the variables mapped to names that are expected by CryoGrid.POST_PROC.read_mat_ERA

Elevation, land cover, snow melt

cryogrid_pytools.data.get_dem_copernicus30

Download DEM data from the STAC catalog (default is COP DEM Global 30m).

Parameters:

Name	Type	Description	Default
bbox_WSEN	list	The bounding box of the area of interest in WSEN format.	required
res	int	The resolution of the DEM data in EPSG units.	30
epsg	int	The EPSG code of the projection of the DEM data. Default is EPSG:32643 (UTM 43N) for the Pamir region.	32643
smoothing_iters	int	The number of iterations to apply the smoothing filter. Default is 2. Set to 0 to disable smoothing.	2
smoothing_size	int	The size of the kernel (num pixels) for the smoothing filter. Default is 3.	3

Returns:

Type	Description
DataArray	The DEM data as an xarray DataArray with attributes.

cryogrid_pytools.data.get_esa_land_cover

Get the ESA World Cover dataset on the target grid and resolution.

Parameters:

Name	Type	Description	Default
bbox_WSEN	tuple	Bounding box in the format (West, South, East, North).	required
res	int	Resolution in EPSG units. Defaults to 30 (meters for UTM).	30
epsg	int	EPSG code for the coordinate reference system. Defaults to 32643.	32643

Returns:

Type	Description
DataArray	A DataArray with the land cover data on the target grid. Contains attributes 'class_values', 'class_descriptions', 'class_colors' for plotting.

cryogrid_pytools.data.get_snow_melt_doy

Calculate the snow melt day of year (DOY) from Sentinel-2 SCL data for a given bounding box and years.

Parameters:

Name	Type	Description	Default
bbox_WSEN	tuple	Bounding box coordinates in the format (West, South, East, North).	required
years	range	Range of years to consider. Defaults to range(2018, 2025).	range(2018, 2025)
res	int	Spatial resolution in meters. Defaults to 30.	30
epsg	int	EPSG code for the coordinate reference system. Defaults to 32643.	32643

Returns:

Type	Description
DataArray	DataArray containing the snow melt DOY for each year.

cryogrid_pytools.data.get_randolph_glacier_inventory

Fetches the Randolph Glacier Inventory (RGI) data and returns it as a GeoDataFrame or raster dataset.

Parameters:

Name	Type	Description	Default
target_dem	optional	A digital elevation model (DEM) object. If provided, the function will return the RGI data clipped to the bounding box of the DEM and reprojected to the DEM's CRS.	None
dest_dir	str	The directory where the downloaded RGI data will be stored. If None, the data will be stored in the pooch cache directory (~/.cache/pooch/).	None

Returns:

Type	Description
GeoDataFrame or raster dataset	If target_dem is None, returns a GeoDataFrame containing the RGI data. If target_dem is provided, returns a raster dataset clipped and reprojected to the DEM.