FilterDataManager#

class FilterDataManager(datasets=None, editing_method=None, editing_datasets=None, editing_kwargs=None, save_path=None, save_name=None, save_format: Literal['json', 'pickle'] = 'json')#

Bases: object

Manages, edits, and organizes measurement datasets for orbit determination filters.

The class provides utilities to combine multiple MeasurementDataSet objects into a unified time-indexed structure keyed by spacecraft time t2. This enables efficient retrieval and reconstruction of synchronized measurement blocks across heterogeneous datasets, instruments, and measurement types.

In addition, the class supports optional pre-processing and measurement editing operations such as chi-squared filtering, lasso-based selection, and date-range editing before the datasets are indexed and passed to the estimation framework.

The resulting combined structure is designed to support linearized and statistical orbit determination workflows involving multi-instrument, multi-spacecraft, or mixed observable estimation problems.

Parameters:
datasetslist of MeasurementDataSet, optional

Input datasets. Nested lists are flattened one level.

editing_methodstr or None

Editing mode to apply before building indices. One of 'lasso', 'lasso_all', 'chi2', 'chi2_all', 'kurtosis', 'kurtosis_all', 'date_range', 'interactive_date_range', or None.

'lasso', 'chi2' and 'kurtosis' open one figure per dataset in sequence, each blocking until it is closed. 'lasso_all', 'chi2_all' and 'kurtosis_all' open every dataset’s figure at once, via lasso_editor_all(), chi_squared_filter_all() and kurtosis_filter_all(). Those are the usable options on remote/browser backends, where closing a plot tab does not advance a sequential loop.

editing_datasetsNone or str or list of str

Which datasets to edit. None = all, a string = one by name, a list of strings = a specific subset.

editing_kwargsdict or None

Extra keyword arguments forwarded to the editing method.

save_pathstr or None

Directory path to save combined per-dataset JSON files.

save_namestr or None

Optional name prefix included in saved file names.

Attributes:
dataset_names

Return the names of the datasets.

datasets

Return the list of managed datasets.

indices_by_t2

Return the indices grouped by unique t2 values.

Methods

get_combined()

Build and return the full combined measurement structure for all epochs.

get_combined_for_t2(t2_val)

Build and return the combined measurement block for a single epoch.

get_spacecraft_times()

Return sorted unique spacecraft receive times with at least one valid measurement.

load(file_paths)

Reconstruct a FilterDataManager from saved dataset file(s).

load_dataset(file_path)

Load a dataset previously written by _save_datasets().

See also

scarabaeus.MeasurementEditing

Provides the lasso/chi2/kurtosis/date-range editing methods.

scarabaeus.FilterOD

Base filter that consumes the combined indexed structure.

Notes

Two-way radiometric time-tag convention used throughout this class:

  • t1 — ground station transmit epoch (uplink signal sent).

  • t2 — spacecraft time (signal reflection / turnaround epoch).

  • t3 — ground station receive epoch (downlink signal received).

Datasets are indexed by spacecraft epoch t2; all datasets must use the same time-tag convention. Nested list inputs are flattened one level automatically.

classmethod load(file_paths)#

Reconstruct a FilterDataManager from saved dataset file(s).

Loads one or more files written by _save_datasets() (via load_dataset()) and returns a manager populated with them, so callers get an object directly instead of rebuilding one from the raw dicts.

Parameters:
file_pathsstr, path-like, or iterable of those

A single saved dataset file, or several. JSON and pickle are both auto-detected per file.

Returns:
FilterDataManager

A manager holding the loaded datasets. It is inspection-only: the saved files are result snapshots (no instrument / target), so the datasets cannot regenerate predicted measurements or re-run the filter.

See also

load_dataset

Low-level reader returning one dataset as a plain dict.

classmethod load_dataset(file_path)#

Load a dataset previously written by _save_datasets().

Returns a plain dict with the same fields (arrays restored as numpy arrays). The format (JSON or pickle) is auto-detected from the file extension. Symmetric counterpart to the save path.

get_combined() → dict#

Build and return the full combined measurement structure for all epochs.

Iterates over every unique t2 value and assembles numeric arrays, stacked partial-derivative matrices, and list-type metadata fields. Measurements flagged as outliers are dropped before returning.

Returns:
dict

Keys are unique t2 float values sorted ascending. Each value is a dict with the fields documented in create_combined_from_indices(): t1, t2, t3, observed, computed, residuals, sigma, outlier_flag, partials, instruments, measurement_types, dataset_names, dataset_refs.

Raises:
RuntimeError

If build_indices() has not been called yet.

get_combined_for_t2(t2_val: float) → dict#

Build and return the combined measurement block for a single epoch.

Parameters:
t2_valfloat

Spacecraft receive time for which measurements are requested.

Returns:
dict

Single-key dict {t2_val: block}, where block has the same field structure as described in get_combined().

Raises:
RuntimeError

If indices have not been built yet.

KeyError

If t2_val is not present in the index.

get_spacecraft_times() → ndarray#

Return sorted unique spacecraft receive times with at least one valid measurement.

A t2 value is included only when at least one of its measurements has outlier_flag == False. Fully rejected epochs are silently omitted; that gating happens when the indices are built, in _combine_indices_by_t2(), so this just returns their keys.

Returns:
np.ndarray

1-D array of float64 spacecraft receive times sorted ascending.

Raises:
RuntimeError

If indices have not been built yet.

T2_MERGE_TOL = 0.001#
property dataset_names: list#

Return the names of the datasets.

property datasets: list#

Return the list of managed datasets.

property indices_by_t2: dict#

Return the indices grouped by unique t2 values.