pyissm.inversion.sensitivity

Sensitivity analysis tools for ISSM inversions.

This module provides functions to systematically vary inversion parameters, execute runs, and compute diagnostics for analyzing sensitivity of inversion results to parameter choices.

Functions

assign_cost_functions(md, coefficients[, ...])

Assign inversion cost function coefficients.

build_parameter_grid(coefficients[, ...])

Build parameter sensitivity combinations.

compute_sensitivity_diagnostics(manifest[, ...])

Compute diagnostics for parameter sensitivity runs from a manifest.

load_parameter_sensitivity_run(manifest_row)

Load a parameter sensitivity run from a manifest row.

normalize_diagnostics(diagnostics[, ...])

Normalize diagnostic columns to [0, 1].

parameter_sensitivity(md, parameter_grid, ...)

Run inversion sensitivity experiments.
pyissm.inversion.sensitivity.assign_cost_functions(md, coefficients, global_mask=None, coeff_masks=None)

Assign inversion cost function coefficients.

Parameters:

  • md (pyissm.Model) – ISSM model object.

  • coefficients (dict) –

    Dictionary mapping cost function IDs to scalar coefficients.

    Example

    {101: 1000, 103: 25, 502: 1e-19}

  • global_mask (numpy.ndarray of bool, optional) –

    Global boolean mask applied to all cost functions.

    • True -> coefficient active

    • False -> coefficient set to zero

  • coeff_masks (dict, optional) –

    Dictionary mapping cost-function IDs to boolean masks. Masks are applied in the same way as the global_mask, but only affect their respective cost functions.

    Example

    {101: vel_mask, 103: grounded_mask}

Returns:

md – Updated ISSM model.

Return type:

pyissm.Model

Example

: code-block:: python

>>> coefficients = {101: 1000,
...                 103: 25,
...                 502: 1e-19}
>>> global_mask = md.inversion.vel_obs > 0
>>> md = pyissm.inversion.sensitivity.assign_cost_functions(md, coefficients, global_mask = global_mask)

>>> coeff_masks = {101: md.inversion.vel_obs > 0,
...                103: md.mask.ice_levelset > 0}
>>> md = pyissm.inversion.sensitivity.assign_cost_functions(md, coefficients, coeff_masks = coeff_masks)
pyissm.inversion.sensitivity.build_parameter_grid(coefficients, initial_run_id=1)

Build parameter sensitivity combinations.

Parameters:

  • coefficients (dict) –

    Dictionary mapping ISSM cost function IDs to coefficient lists.

    Example

    {101: [0.1, 1, 10], 103: [1, 10], 502: [1e-19]}

  • initial_run_id (int, default = 1) – Starting index for run_id assignment. Subsequent runs will have IDs incremented by 1 from this value. Useful for tracking runs across multiple calls to this function without overwriting previous run_ids.

Returns:

Parameter combination table.

Return type:

pandas.DataFrame

Notes

Returned DataFrame contains:

  • run_id

  • cfXXX columns for each cost function

  • run_name

Example

: code-block:: python

>>> coefficients = {101: [1, 10, 100, 1000],
...                 103: [1, 10, 100, 1000]}
>>> param_grid = pyissm.inversion.sensitivity.build_parameter_grid(coefficients)
>>> param_grid = pyissm.inversion.sensitivity.build_parameter_grid(coefficients, initial_run_id = 101)
pyissm.inversion.sensitivity.compute_sensitivity_diagnostics(manifest, output_dir=None, plot_run_summaries=True)

Compute diagnostics for parameter sensitivity runs from a manifest.

Parameters:

  • manifest (pandas.DataFrame) – Output from pyissm.inversion.sensitivity.parameter_sensitivity().

  • output_dir (str or pathlib.Path, optional) – Directory used to store computed diagnostics. If None, diagnostics are not saved to disk.

  • plot_run_summaries (bool, default = True) – Whether to generate summary PDF reports for each run, including diagnostic plots and convergence history. If True, summary PDFs are saved in each run’s directory.

Returns:

Diagnostics table.

Return type:

pandas.DataFrame

Example

: code-block:: python

>>> manifest = pd.read_csv('./sensitivity_runs/manifest.csv')
>>> diagnostics = pyissm.inversion.sensitivity.compute_sensitivity_diagnostics(manifest, output_dir = './sensitivity_runs/diagnostics')
pyissm.inversion.sensitivity.load_parameter_sensitivity_run(manifest_row)

Load a parameter sensitivity run from a manifest row.

Parameters:

manifest_row (pandas.Series)

Returns:

md – Loaded ISSM model for the specified run.

Return type:

pyissm.Model

Example

: code-block:: python

>>> manifest = pd.read_csv('./sensitivity_runs/manifest.csv')
>>> md = pyissm.inversion.sensitivity.load_parameter_sensitivity_run(manifest.iloc[0])
pyissm.inversion.sensitivity.normalize_diagnostics(diagnostics, columns=None, higher_is_better=None, suffix='_norm')

Normalize diagnostic columns to [0, 1].

Parameters:

  • diagnostics (pandas.DataFrame) – DataFrame containing model diagnostics.

  • columns (list of str, optional) – Columns to normalize. Defaults to all numeric columns.

  • higher_is_better (dict, optional) –

    Dictionary mapping column name -> bool. - True = higher values are better - False = lower values are better

    Example

    {“velocity_rmse”: False, “thickness_rmse”: False, “correlation”: True}

    Any unspecified column defaults to False.

  • suffix (str, optional) – Suffix for normalized columns.

Returns:

Copy of dataframe with normalized columns added.

Return type:

pandas.DataFrame

Example

: code-block:: python

>>> manifest = pd.read_csv('./sensitivity_runs/manifest.csv')
>>> diagnostics = pyissm.inversion.sensitivity.compute_sensitivity_diagnostics(manifest, output_dir = './sensitivity_runs/diagnostics')
>>> diagnostics_norm = pyissm.inversion.sensitivity.normalize_diagnostics(diagnostics, columns = ['vel_rmse', 'thickness_rmse'])
pyissm.inversion.sensitivity.parameter_sensitivity(md, parameter_grid, output_dir, run=True, load_only=False, global_mask=None, coeff_masks=None)

Run inversion sensitivity experiments.

Parameters:

  • md (pyissm.Model) – ISSM model object.

  • parameter_grid (pandas.DataFrame) – Output from pyissm.inversion.sensitivity.build_parameter_grid().

  • output_dir (str or pathlib.Path) –

    Directory used to store sensitivity outputs, manifests, and saved models.

    NOTE: This is intentionally separate from: md.cluster.executionpath:

    • md.cluster.executionpath controls where ISSM stages runtime files for execution.

    • output_dir controls where pyISSM stores organized experiment outputs.

  • run (bool, default = True) – Submit inversion runs.

  • load_only (bool, default = False) – Load completed inversion results.

  • global_mask (numpy.ndarray of bool, optional) –

    Global boolean mask applied to all cost functions. Passed to assign_cost_functions().

    • True -> coefficient active

    • False -> coefficient set to zero

  • coeff_masks (dict, optional) –

    Dictionary mapping cost-function IDs to boolean masks. Passed to assign_cost_functions().

    Example

    {101: vel_mask, 103: grounded_mask}

Returns:

Experiment manifest.

Return type:

pandas.DataFrame

Example

: code-block:: python

>>> coefficients = {101: [1, 10, 100, 1000],
...                 103: [1, 10, 100, 1000]}
>>> parameter_grid = pyissm.inversion.sensitivity.build_parameter_grid(coefficients)
>>> manifest = pyissm.inversion.sensitivity.parameter_sensitivity(md, parameter_grid, output_dir = './sensitivity_runs', run = True, load_only = False)