Matrix inversion

Matrix inversion#

class echopop.inversion.InvParameters(parameters: dict[str, Any])#

Primary class for managing acoustic scattering model parameters used in matrix inversion.

This class manages parameter sets used in acoustic inversion analysis, providing scaling/unscaling functionality, bounds management, and integration with the lmfit optimization package. It serves as the primary interface for parameter handling in Echopop inversion workflows.

Parameters:
parametersDict[str, Any]

Dictionary of parameter specifications compatible with lmfit.Parameters():

  • 'value': Current parameter value

  • 'min': Lower bound (optional, default=-inf)

  • 'max': Upper bound (optional, default=+inf)

  • 'vary': Whether parameter should be optimized (optional, default=False)

Attributes:
parametersDict[str, Dict[str, Any]]

Validated parameter dictionary

values Dict[str, float]

Property to get current parameter values as dictionary

boundsDict[str, Dict[str, float]]

Get dictionary of parameter bounds (min/max values).

is_scaledbool

Check whether parameters are currently in scaled [0,1] form.

Methods

scale()

Scale parameters to [0,1] range and return new scaled instance

unscale()

Unscale parameters to original range and return new unscaled instance

to_lmfit()

Convert to lmfit.Parameters object for optimization

inverse_transform(scaled_dict)

Convert scaled parameter dictionary back to original scale

update_bounds(bounds)

Update the boundaries (min/max) for stored parameters

from_series(series)

Class method to create instance from pandas Series

Notes

The scaling transformation uses min-max normalization:

\[\begin{split}\\hat{x} = \\frac{x - x_\\text{min}}{x_\\text{max} - x_\\text{min}}\end{split}\]

This improves optimization convergence by normalizing parameter ranges and reducing numerical conditioning issues in multi-parameter problems.

Examples

>>> params = {
...     'length_mean': {'value': 25.0, 'min': 10.0, 'max': 40.0, 'vary': True},
...     'g': {'value': 1.02, 'min': 0.95, 'max': 1.05, 'vary': True}
... }
>>> inv_params = InvParameters(params)
>>> inv_params.scale()  # Scale to [0,1]
>>> lmfit_params = inv_params.to_lmfit()
class echopop.inversion.InversionMatrix(data: DataFrame, simulation_settings: dict[str, Any], verbose: bool = True)#

Matrix-based acoustic scattering parameter inversion for marine organisms.

This class performs acoustic inversion to estimate biological parameters (size, density, abundance) from multi-frequency volume backscattering strength measurements. It uses physics-based scattering models and nonlinear optimization with optional Monte Carlo initialization for robust parameter estimation.

Parameters:
datapd.DataFrame

MultiIndex DataFrame containing acoustic measurements with columns: - ‘sv_mean’: Volume backscattering strength (dB re 1 m^-1) - ‘nasc’: Nautical Area Scattering Coefficient (m²/nmi²) - ‘thickness_mean’: Mean layer thickness (m) Frequency must be specified as a column index level.

simulation_settingsDict[str, Any]

Configuration dictionary containing: - ‘monte_carlo’: bool, whether to use MC initialization - ‘mc_realizations’: int, number of MC samples - ‘scale_parameters’: bool, whether to scale parameters to [0,1] - ‘environment’: dict with ‘sound_speed_sw’ and ‘density_sw’ - ‘minimum_frequency_count’: int, minimum frequencies required

verbosebool, default=True

Whether to print progress and diagnostic information

Attributes:
measurementspd.DataFrame

Validated acoustic measurement data with added processing columns

simulation_settingsdict

Validated and processed simulation configuration

inversion_methodstr

Method identifier, set to “scattering_model”

model_paramsInvParameters

Container for biological model parameters with bounds and vary flags

model_settingsdict

Scattering model configuration including type and numerical settings

parameter_boundsdict

Original parameter bounds for unscaling operations

Methods

build_scattering_model(model_parameters, model_settings)

Configure and validate scattering model parameters and settings

invert(optimization_kwargs)

Perform parameter inversion using nonlinear optimization
Raises:
ValidationError

If data or simulation_settings fail validation requirements

Notes

The inversion process involves several steps:

  1. Data Validation: Ensures acoustic data has required structure

  2. Model Configuration: Sets up forward scattering model and parameters

  3. Initialization: Optionally uses Monte Carlo warm-start strategy

  4. Optimization: Minimizes misfit between predicted and measured Sv

  5. Parameter Recovery: Converts optimized values back to physical units

Monte Carlo initialization can significantly improve convergence for nonlinear problems by evaluating multiple starting points and selecting the most promising realization.

Parameter scaling normalizes all parameters to [0,1] range, which improves numerical conditioning when parameters have very different scales (e.g., length in mm vs density in kg/m³).

The class supports various scattering models through a plugin architecture defined in SCATTERING_MODEL_PARAMETERS. Currently implemented models include PCDWBA for elongated organisms.

Examples

>>> # Initialize inversion matrix
>>> inv_matrix = InversionMatrix(sv_data, simulation_settings)
>>>
>>> # Configure scattering model
>>> params = InvParameters(parameter_dict)
>>> model_config = {'type': 'pcdwba', 'taper_order': 10.0}
>>> inv_matrix.build_scattering_model(params, model_config)
>>>
>>> # Run inversion
>>> opt_kwargs = {'max_nfev': 1000, 'method': 'least_squares'}
>>> results = inv_matrix.invert(opt_kwargs)
>>>
>>> # Extract population estimates
>>> pop_estimates = estimate_population(results, nasc_data,
...                                   density_sw=1026.,
...                                   reference_frequency=120e3,
...                                   aggregate_method="transect")