sample_data module

sample_data module#

Sample data utilities for xsnow testing and tutorials.

This module uses pooch to manage a registry of small SNOWPACK test datasets hosted on GitLab. These datasets are downloaded on first access, cached locally in a project-specific directory, and then reused in future runs.

The provided helper functions are intended to support unit tests, tutorials, and development:

  • single_profile(): A single, simple profile wrapped into an xsnowDataset.

  • single_profile_timeseries(): An xsnowDataset from a single location containing many timestamps.

  • snp_gridded_ds(): A sample xsnowDataset of gridded SNOWPACK simulations

For more complex tutorials or integration tests:

  • snp_gridded_dir(): A locally cached directory tree containing gridded simulations

  • snp_snowobs_dir(): A locally cached directory tree of manual & modeled profiles

Notes

  • All files are verified by SHA256 hash on download to avoid corrupt files.

  • Cached files are never automatically deleted; users can clear the cache manually by removing the relevant cache directories (~/.cache/xsnow-*)

xsnow.sample_data.snp_gridded_dir()#

Get the local directory containing all SNOWPACK files from a sample gridded simulation.

The function ensures that all registered SNOWPACK files (input .smet drivers and output .pro & .smet profiles) are downloaded, and return the absolute cache directory path.

Return type:

str

Returns:#

:
A path to a locally cached directory, where:

  • dir/smets/gridded/[nowcast|forecast]/: contains the .smet files used to drive SNOWPACK

  • dir/pros/gridded/: contains the SNOWPACK output files (.pro and .smet)

Examples:#

>>> import os
>>> from xsnow.sample_data import snp_gridded_dir
>>> gridded_dir = snp_gridded_dir()
>>> os.listdir(f"{gridded_dir}/pros/gridded")
xsnow.sample_data.snp_gridded_ds()#

Get a sample dataset representing a gridded SNOWPACK simulation

Return type:

xsnowDataset

Returns:#

:

A sample xsnowDataset

Examples:#

>>> from xsnow.sample_data import snp_gridded_ds
>>> ds = snp_gridded_ds()
>>> ds
xsnow.sample_data.snp_snowobs_dir(minimal=False)#

Get the local directory containing all SNOWPACK files from a sample simulation that was started off of manual snow profiles.

Return type:

str

Parameters:#

minimal (bool): Fetch all files related to this experiment, or only one specific file pattern?

Returns:#

:
A path to a locally cached directory, where:

  • dir/pits/: contains the manual profiles

  • dir/smets/snowobs/[nowcast|forecast]/: contains the .smet files used to drive SNOWPACK

  • dir/pros/snowobs/: contains the SNOWPACK output files (.pro and .smet)

See Also:#

single_profile : Get a single profile dataset single_profile_timeseries : Get a single profile timeseries dataset

Notes:#

  • This sample dataset is well suited to test the realization capability of xsnow (manual and modeled profiles)

  • Until we have a .caaml parser, we can use the converted .pro files of the manuals. The .caaml versions contain a temperature profile on a different vertical spacing than the layers. The .pro versions are missing this offset-temperature profile.

  • LawisProfile20908.caaml contains at least one weak layer that is getting loaded by a storm

  • LawisProfile20915.caaml develops a wetting front over complex stratigraphy

xsnow.sample_data.single_profile()#

Get a single, simple xsnowDataset containing one (manual) profile from one location & time.

Return type:

xsnowDataset

Examples:#

>>> import xsnow
>>> ds = xsnow.single_profile()
>>> ds
xsnow.sample_data.single_profile_timeseries()#

Get an xsnowDataset from one location with many timestamps.

In fact, this is a SNOWPACK simulation that was started off of the (manual) single_profile().

Return type:

xsnowDataset

Examples:#

>>> import xsnow
>>> ds = xsnow.single_profile_timeseries()
>>> ds
Contents