Skip to content

Measurement Residual Plots

Visualize pre-fit and post-fit measurement residuals as summary overlays, per-component grids, or RMS time series.

Solver API

plot_measurement_residual 

plot_measurement_residual(solver, iteration=-1, residual_type='postfit', model_name=None, labels=None, colors=None, time_units='seconds', orbital_period=None, backend='matplotlib', backend_config=None, **kwargs) -> object

Plot measurement residuals from a solved estimator.

Extracts residuals from the solver and delegates to :func:plot_measurement_residual_from_arrays. When residual_type="both", prefit and postfit residuals are overlaid on the same axes using different markers and alpha levels.

Parameters:

Name Type Description Default
solver object

A solved BatchLeastSquares, ExtendedKalmanFilter, or UnscentedKalmanFilter instance.

 required
iteration int

Iteration index for BLS (default -1, last). Ignored for sequential filters.

 -1
residual_type str

"prefit", "postfit", or "both". Default: "postfit".

 'postfit'
model_name str or None

Filter residuals by measurement model name. None means include all models. Default: None.

 None
labels list[str] or None

Label per residual component. Default: generated labels.

 None
colors list[str] or None

Colour per component. Default: colour cycle.

 None
time_units str or callable

Time axis units. Default: "seconds".

 'seconds'
orbital_period float or None

Orbital period in seconds. Required when time_units="orbits". Default: None.

 None
backend str

"matplotlib" or "plotly". Default: "matplotlib".

 'matplotlib'
backend_config dict or None

Backend-specific configuration.

 None
**kwargs dict

Forwarded to the array-API function.

 {}

Returns:

Type Description
object

Generated matplotlib or plotly figure object.

plot_measurement_residual_grid 

plot_measurement_residual_grid(solver, iteration=-1, residual_type='postfit', model_name=None, labels=None, ncols=3, time_units='seconds', orbital_period=None, backend='matplotlib', backend_config=None, **kwargs) -> object

Plot measurement residuals in a subplot grid from a solved estimator.

Extracts residuals from the solver and delegates to :func:plot_measurement_residual_grid_from_arrays.

Parameters:

Name Type Description Default
solver object

A solved BatchLeastSquares, ExtendedKalmanFilter, or UnscentedKalmanFilter instance.

 required
iteration int

Iteration index for BLS (default -1, last). Ignored for sequential filters.

 -1
residual_type str

"prefit" or "postfit". Default: "postfit".

 'postfit'
model_name str or None

Filter residuals by measurement model name. None means include all. Default: None.

 None
labels list[str] or None

Label per component. Default: generated.

 None
ncols int

Number of subplot columns. Default: 3.

 3
time_units str or callable

Time axis units. Default: "seconds".

 'seconds'
orbital_period float or None

Orbital period in seconds. Default: None.

 None
backend str

"matplotlib" or "plotly". Default: "matplotlib".

 'matplotlib'
backend_config dict or None

Backend-specific configuration.

 None
**kwargs dict

Forwarded to the array-API function.

 {}

Returns:

Type Description
object

Generated matplotlib or plotly figure object.

plot_measurement_residual_rms 

plot_measurement_residual_rms(solver, residual_type='postfit', model_name=None, time_units='seconds', orbital_period=None, backend='matplotlib', backend_config=None, **kwargs) -> object

Plot the per-epoch RMS of measurement residuals from a solved estimator.

When residual_type="both", prefit and postfit RMS lines are overlaid on the same axes.

Parameters:

Name Type Description Default
solver object

A solved BatchLeastSquares, ExtendedKalmanFilter, or UnscentedKalmanFilter instance.

 required
residual_type str

"prefit", "postfit", or "both". Default: "postfit".

 'postfit'
model_name str or None

Filter residuals by measurement model name. None means include all. Default: None.

 None
time_units str or callable

Time axis units. Default: "seconds".

 'seconds'
orbital_period float or None

Orbital period in seconds. Default: None.

 None
backend str

"matplotlib" or "plotly". Default: "matplotlib".

 'matplotlib'
backend_config dict or None

Backend-specific configuration.

 None
**kwargs dict

Ignored.

 {}

Returns:

Type Description
object

Generated matplotlib or plotly figure object.

Array API

plot_measurement_residual_from_arrays 

plot_measurement_residual_from_arrays(times, residuals, labels=None, colors=None, time_label='Time [s]', backend='matplotlib', backend_config=None, **kwargs) -> object

Plot measurement residuals as a scatter overlay from raw numpy arrays.

Each column of residuals is one measurement component and is drawn as a separate scatter series with a horizontal zero-reference line.

Parameters:

Name Type Description Default
times ndarray

1-D array of time values, length N.

 required
residuals ndarray

2-D array of shape (N, n_components).

 required
labels list[str] or None

Label per component. Defaults to "Series 0", "Series 1", …

 None
colors list[str] or None

Colour per component. Defaults to the internal colour cycle.

 None
time_label str

X-axis label. Default: "Time [s]".

 'Time [s]'
backend str

"matplotlib" or "plotly". Default: "matplotlib".

 'matplotlib'
backend_config dict or None

Backend-specific configuration. Matplotlib keys: figsize, legend_loc, dark_mode, ylabel_pad. Plotly keys: width, height.

 None
**kwargs dict

Ignored.

 {}

Returns:

Type Description
object

Generated matplotlib or plotly figure object.

plot_measurement_residual_grid_from_arrays 

plot_measurement_residual_grid_from_arrays(times, residuals, labels=None, colors=None, ncols=3, time_label='Time [s]', backend='matplotlib', backend_config=None, **kwargs) -> object

Plot measurement residuals in a subplot grid from raw numpy arrays.

One subplot is created per measurement component. Each subplot contains scatter markers for that component plus a zero-reference line. Unused subplots (when n_components is not a multiple of ncols) are hidden.

Parameters:

Name Type Description Default
times ndarray

1-D array of time values, length N.

 required
residuals ndarray

2-D array of shape (N, n_components).

 required
labels list[str] or None

Title/label per component. Defaults to "Series 0", "Series 1", …

 None
colors list[str] or None

Colour per component. Defaults to the internal colour cycle.

 None
ncols int

Number of subplot columns. Default: 3.

 3
time_label str

X-axis label. Default: "Time [s]".

 'Time [s]'
backend str

"matplotlib" or "plotly". Default: "matplotlib".

 'matplotlib'
backend_config dict or None

Backend-specific configuration. Matplotlib keys: figsize, legend_loc, dark_mode, ylabel_pad. Plotly keys: width, height.

 None
**kwargs dict

Ignored.

 {}

Returns:

Type Description
object

Generated matplotlib or plotly figure object.

plot_measurement_residual_rms_from_arrays 

plot_measurement_residual_rms_from_arrays(times, residuals, time_label='Time [s]', backend='matplotlib', backend_config=None, **kwargs) -> object

Plot the per-epoch RMS of measurement residuals from raw numpy arrays.

Computes rms[i] = sqrt(mean(residuals[i, :]**2)) and draws a single line plot.

Parameters:

Name Type Description Default
times ndarray

1-D array of time values, length N.

 required
residuals ndarray

2-D array of shape (N, n_components).

 required
time_label str

X-axis label. Default: "Time [s]".

 'Time [s]'
backend str

"matplotlib" or "plotly". Default: "matplotlib".

 'matplotlib'
backend_config dict or None

Backend-specific configuration. Matplotlib keys: figsize, legend_loc, dark_mode, ylabel_pad. Plotly keys: width, height.

 None
**kwargs dict

Ignored.

 {}

Returns:

Type Description
object

Generated matplotlib or plotly figure object.

See Also