Metadata-Version: 2.4
Name: cryogrid_pytools
Version: 0.3.19
Summary: Tools to read in CryoGrid MATLAB data to Python and create forcing data
Project-URL: Homepage, https://github.com/lukegre/CryoGrid-pyTools
Project-URL: CryoGrid, https://github.com/CryoGrid
Project-URL: Documentation, https://lukegre.github.io/CryoGrid-pyTools/
Maintainer-email: Luke Gregor <lukegre@gmail.com>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Education
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Hydrology
Requires-Python: >=3.9
Requires-Dist: dask[array,diagnostics]>=2024
Requires-Dist: joblib
Requires-Dist: loguru
Requires-Dist: matplotlib
Requires-Dist: munch
Requires-Dist: numpy>=2.0
Requires-Dist: openpyxl
Requires-Dist: pandas>=2
Requires-Dist: pip>=24
Requires-Dist: scipy>=1.13.1
Requires-Dist: xarray>=2024
Provides-Extra: data
Requires-Dist: bottleneck>=1.4.2; extra == 'data'
Requires-Dist: earthaccess>=0.11.0; extra == 'data'
Requires-Dist: earthengine-api>=1.5.9; extra == 'data'
Requires-Dist: era5-downloader>=0.1.4; extra == 'data'
Requires-Dist: geopandas>=1.0.1; extra == 'data'
Requires-Dist: ipywidgets>=8.1.5; extra == 'data'
Requires-Dist: memoization>=0.4.0; extra == 'data'
Requires-Dist: planetary-computer>=1.0.0; extra == 'data'
Requires-Dist: pooch>=1.8.2; extra == 'data'
Requires-Dist: pyarrow>=19.0.1; extra == 'data'
Requires-Dist: pystac-client>=0.8.3; extra == 'data'
Requires-Dist: pyzenodo3>=1.0.2; extra == 'data'
Requires-Dist: rioxarray>=0.15.0; extra == 'data'
Requires-Dist: scikit-image>=0.24.0; extra == 'data'
Requires-Dist: setuptools>=78.1.0; extra == 'data'
Requires-Dist: stackstac>=0.5.1; extra == 'data'
Requires-Dist: wxee>=0.4.2; extra == 'data'
Requires-Dist: zarr<3; extra == 'data'
Provides-Extra: dev
Requires-Dist: ipykernel>=6.29.5; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-material>=8.2.10; extra == 'docs'
Requires-Dist: mkdocs-rtd-dropdown>=1.0.2; extra == 'docs'
Requires-Dist: mkdocs>=1.5.0; extra == 'docs'
Requires-Dist: mkdocstrings-python>=1.7.0; extra == 'docs'
Requires-Dist: mkdocstrings>=0.24.0; extra == 'docs'
Requires-Dist: pymdown-extensions>=10.14.1; extra == 'docs'
Provides-Extra: viz
Requires-Dist: folium>=0.19.5; extra == 'viz'
Requires-Dist: geopandas>=1.0.1; extra == 'viz'
Requires-Dist: mapclassify>=2.8.1; extra == 'viz'
Requires-Dist: matplotlib>=3.9.4; extra == 'viz'
Requires-Dist: rioxarray>=0.15.0; extra == 'viz'
Requires-Dist: scikit-image>=0.24.0; extra == 'viz'
Description-Content-Type: text/markdown

# CryoGrid-pyTools
Tools to read in CryoGrid MATLAB data to Python, includes forcing, outputs, DEMs, etc.

Feel free to use, modify, and distribute as you see fit.

## Installation

```bash
pip install cryogrid_pytools

# OR for the very latest bleeeeding edge version
pip install "cryogrid-pytools[data,viz] @ git+https://github.com/lukegre/CryoGrid-pyTools.git"
```

However, I recommend using `uv` to manage your Python environments. This would be
```bash
uv add cryogrid-pytools[data,viz]

# OR
uv add "cryogrid-pytools[data,viz] @ git+https://github.com/lukegre/CryoGrid-pyTools.git"
```

## Usage
This package can read in
- CryoGrid output (from `OUT_regridded_FCI2`)
- simple MATLAB struct files (not `run_info.mat`)
- ERA5 forcing
- excel run configuration files (experimental)

Basic examples are shown below for the first two items, but see `demo.ipynb` for more comprehensive examples.

### Reading single CryoGrid output files

Currently, only output files from the calss `OUT_regridded_FCI2` are supported.
However, the majority of files you'll use follow this format.
```python
import cryogrid_pytools as cgt

# a single file that should look something like this
fname = "results_from_RUN_SIMPLE/<project_name>_<YYYYMMDD>.mat"

# currently the only output from OUT_regridded_FCI2 is supported
dataset = cgt.read_OUT_regridded_FCI2_file(fname)
```

### Reading multiple CryoGrid output files

If you're working with RUN_SPATIAL_SPINUP_CLUSTERING, you can read in multiple files at once. The data are returned as an `xarray.Dataset` with the dimensions: [`gridcell`, `depth`, `time`]
```python
# path contains wildcards where cluster ID and date are respectively
fname = "results_from_RUN_SPATIAL_SPINUP_CLUSTERING/project_name_*_*.mat"

# deepest_point is the deepest point in the saved files
dataset = cgt.read_OUT_regridded_FCI2_clusters(fname, deepest_point=-5)
```

### Reading struct files from MATLAB
<div style="border: 1px solid; border-radius: 5px; padding: 10px; margin: 10px 0; width: 97.5%; border-color: #0096C7; background-color: rgba(0, 150, 199, 0.1); "><b>TIP</b>: In <code>MATLAB</code>, You need to add the `CryoGrid/source` directory to the MATLAB path before the file can be loaded properly. </div>

Note that `run_info.mat` cannot be read as it contains special classes that are not supported by `scipy.io.loadmat`.  To save parts of `run_info`, use the following code in MATLAB:

```matlab
run_info_spatial = run_info.SPATIAL.STATVAR
save "run_info_spatial.mat" run_info_spatial
```

Then, in Python:

```python
fname = 'path_to_file/run_spatial_statvar.mat'
spatial = cgt.read_mat_struct_as_dataset(fname, index=['Y', 'X'])
```
