hazard_chart module

Summary

Compute and plot hazard charts from xsnowDataset

This extension module serves as a template for demonstrating how to develop an extension to xsnow that implements completely new functionality and adds a new dimension to the xsnowDataset class. This coincides with application scenario 2 from the xsnow extension framework.

As demonstrated in this module, the class definition of such an extension uses the xsnow DatasetDecorator class, which entirely handles the class configuration. A user can simply create their own extension class by subclassing the DatasetDecorator and implementing class methods or module-level helper functions.

Warning

This extension is still work-in-progress. While the status quo is sufficient for demonstrating how to create an extension to satisfy application scenario 2, it is not entirely useful yet in terms of its snow and avalanche related content.

It will be updated to be generic and user-friendly, and to document the class and functions meaningfully.

class xsnow.extensions.hazard_chart.HCVariantInfo(idx, stability_index, groupby, depth_var)

Bases: object

Metadata describing one hazard-chart variant stored in the dataset. Note: time is not part of the variant. Variants represent configuration (stability index, grouping keys, chosen depth var).

idx: int

stability_index: str

groupby: Tuple[str, ...]

depth_var: str

class xsnow.extensions.hazard_chart.HazardChart(base, *, data=None)

Bases: DatasetDecorator

Hazard chart decorator that can accumulate multiple computed variants along a new hc_variant dimension. It never mutates the base dataset; instead, each method returns a new wrapped instance via _rewrap().

name/priority:

• name helps introspection/registries.

• priority can be used by your pipeline to order decorators if needed.

Initialize a decorator instance.

Parameters:

• base (xsnowDataset) –

  The wrapped dataset object (either a plain xsnowDataset or another DatasetDecorator). base is required so that:

  • attribute access can delegate to the already-configured wrapper chain (including previously applied extensions), and

  • _rewrap() can rebuild that chain around a new xarray.Dataset when an xarray operation returns a new dataset.

• data (Union[Dataset, xsnowDataset, None]) –

  The concrete xarray.Dataset to expose as self.data for this wrapper instance. When omitted, the decorator uses base.data.

  This is primarily an internal hook used by _rewrap(): when an operation produces a new dataset, the decorator chain is rebuilt with base updated to wrap the new dataset, and data is passed explicitly so that the newly returned object consistently points at that same dataset.

  For convenience, data may also be an xsnowDataset (including another decorator instance). In that case its underlying .data is used.

name = 'hazard_chart'

priority = 20

compute_hazard_chart_data(*, stability_index='sk38', groupby=None, layer_dim='layer', depth_var='z', at_time=None)

Compute hazard-chart summary variables across time (or at a specific time if at_time is provided) and append them as a new entry on the hc_variant dimension.

Return type:

HazardChart

Notes

Depth selection is dynamic per point:

• depth @ weakest layer (min/max of stability index), and

• deepest depth with qualitative class ∈ poor-or-worse

are both computed; the deeper is chosen. Provenance for the chosen depth’s driver layer is stored in hc_depthDrivenBy.

The output variables have dims (hc_variant, <points dims incl. time>).

list_hc_variants()

Return metadata for all stored hazard-chart variants.

Return type:

List[HCVariantInfo]

subset_hazard_points(*, hc_variant, group=None, time=None)

Return per-point hazard variables for a single variant, optionally restricted to one group (by id or label) and/or time (scalar value).

Return type:

Dataset

plot_hazard_chart(*, hc_variant, group=None, time=None, ax=None, s=18.0, alpha=0.7)

Scatter-plot for one variant, optionally for a single group and/or time. X = hc_depth, Y = hc_instability.