fitting

class los_estimator.fitting.Distribution(name: str, init_values: list[float], boundaries: list[tuple], pdf: ~typing.Callable, to_string: ~typing.Callable = <function Distribution.<lambda>>)

Bases: object

Data class for distribution function information.

Contains all necessary information to define and use a probability distribution for length of stay modeling.

name

Name identifier for the distribution.

Type:: str

init_values

Initial parameter values for optimization.

Type:: list

boundaries

Parameter bounds for constrained optimization.

Type:: list

pdf

Probability density function.

Type:: Callable

class los_estimator.fitting.DistributionTypes

Bases: object

Enum for available distribution types.

Defines constants for all supported distribution types that can be used as length of stay kernels in the modeling process.

class los_estimator.fitting.ErrorType

Bases: object

Enum for available error function types.

Defines constants for all supported error metrics that can be used for model fitting and evaluation.

class los_estimator.fitting.MultiSeriesFitResults(distros=None, *args, **kwargs)

Bases: OrderedDict[str, SeriesFitResult]

Aggregate results for multiple distributions and build summaries.

This container maps distribution names to their SeriesFitResult instances, and offers helpers to compute cross-distro arrays (e.g., error matrices) and a comparison summary DataFrame.

results

List of SeriesFitResult instances for each distribution.

Type:: list[SeriesFitResult]

distros

List of distribution names corresponding to the results.

Type:: list[str]

n_windows

Number of fitting windows across all distributions.

Type:: int

train_errors_by_distro

2D array of training errors with shape (n_windows, n_distros).

Type:: NDArray

test_errors_by_distro

2D array of test errors with shape (n_windows, n_distros).

Type:: NDArray

transition_rates_by_distro

2D array of transition rates with shape (n_windows, n_distros).

Type:: NDArray

transition_delays_by_distro

2D array of transition delays with shape (n_windows, n_distros).

Type:: NDArray

summary

Comparison DataFrame with error statistics and robustness metrics per distribution.

Type:: pd.DataFrame

bake()

Finalize all series and compute cross-distribution arrays.

Processes all distribution results and creates comparison matrices:

Calls bake() on each SeriesFitResult
Builds train/test error matrices (windows × distributions)
Computes transition rate and delay matrices
Generates summary DataFrame with statistics and robustness metrics

Returns:: Self, for method chaining.
Return type:: MultiSeriesFitResults

class los_estimator.fitting.MultiSeriesFitter(series_data: SeriesData, model_config: ModelConfig, distributions: list[str], init_parameters: dict[str, list[float]])

Bases: object

Main class for fitting LOS models across multiple time series.

Orchestrates the fitting process across multiple time windows and distribution types, managing the optimization process and collecting results for analysis.

all_fit_results

Container for all fit results.

Type:: MultiSeriesFitResults

series_data

Time series data for fitting.

Type:: SeriesData

model_config

Configuration for model parameters.

Type:: ModelConfig

distributions

List of distribution types to fit.

Type:: list[str]

init_parameters

Initial parameters for each distribution.

Type:: defaultdict

debug_config: Configuration for debugging modes.

DEBUG_MODE(debug_config)

Configure debug mode settings.

Sets up debugging options to reduce computation time during development by limiting the number of windows and distributions to test.

Parameters:: debug_config – Debug configuration object with boolean flags.

fit(): Fit models across all distributions and time windows.

fit_distro(distro)

Fit a single distribution across all sliding windows.

Runs the appropriate fitter (convolutional or compartmental) for each window, tracks failures, updates rolling kernels (for convolutional models), and returns an aggregated SeriesFitResult.

Parameters:: distro (str) – Name of the distribution (e.g., “lognorm”, “linear”, “compartmental”).
Returns:: Aggregated results for the given distribution.
Return type:: SeriesFitResult

class los_estimator.fitting.SeriesFitResult(distro)

Bases: object

Aggregate fit results across windows for a single distribution.

A SeriesFitResult collects SingleFitResult objects produced for each sliding window of a specific distribution and computes convenient arrays like train_errors, test_errors, and derived transition metrics.

distro

Distribution name for this series.

Type:: str

window_infos

Metadata for each processed window.

Type:: list[WindowInfo]

fit_results

Per-window fit result objects.

Type:: list[SingleFitResult]

train_errors

Array of training errors across windows.

Type:: NDArray

test_errors

Array of test errors across windows.

Type:: NDArray

all_kernels

Rolling kernel matrix (rows = day, cols = kernel width).

Type:: NDArray

transition_rates

Transition rate estimates from model configs.

Type:: NDArray

transition_delays

Transition delay estimates from model configs.

Type:: NDArray

append(window_info, fit_result)

Append a window and its fit result to the series.

Parameters:

window_info (WindowInfo) – Metadata about the processed window.
fit_result (SingleFitResult) – The fit result for the window.

bake()

Finalize the series by computing derived arrays and metrics.

This method aggregates individual window results and computes:

Training and test error arrays across all windows
Success/failure counts for optimizer convergence
Transition rate and delay estimates from model parameters

class los_estimator.fitting.SingleFitResult(distro: str, train_data: object, test_data: object, success: bool, minimization_result: dict, train_error: numpy.typing.NDArray, test_error: numpy.typing.NDArray, kernel: numpy.typing.NDArray, distro_params: numpy.typing.NDArray, train_prediction: numpy.typing.NDArray | None = None, test_prediction: numpy.typing.NDArray | None = None, rel_train_error: numpy.typing.NDArray | None = None, rel_test_error: numpy.typing.NDArray | None = None, curve: numpy.typing.NDArray | None = None)

Bases: object

Result of a single-window fit for one distribution.

Instances capture artifacts produced by the optimizer for a specific window, including errors, predictions, and the fitted kernel. Relative error arrays and fitted curve can be attached if computed downstream.

distro

Distribution name (e.g., “lognorm”, “gaussian”).

Type:: str

train_data

Training data used for the fit.

Type:: object

test_data

Held-out data for evaluation.

Type:: object

success

Whether the optimizer reported success.

Type:: bool

minimization_result

Raw optimizer result object.

Type:: dict

train_error

Scalar training error for the window.

Type:: NDArray

test_error

Scalar test error for the window.

Type:: NDArray

kernel

Fitted kernel array for this window.

Type:: NDArray

model_config

Model configuration snapshot used during fitting.

Type:: ModelConfig

train_prediction

Optional model predictions on the training window.

Type:: NDArray | None

test_prediction

Optional model predictions on the test window.

Type:: NDArray | None

rel_train_error

Optional element-wise relative training error array.

Type:: NDArray | None

rel_test_error

Optional element-wise relative test error array.

Type:: NDArray | None

curve

Optional fitted curve points for visualization.

Type:: NDArray | None

classmethod create_failed(distro, train_data, test_data)

Create a SingleFitResult representing a failed fit.

Parameters:

distro (str) – Distribution name.
train_data (object) – Training data used for the fit.
test_data (object) – Held-out data for evaluation.

Returns:

Instance indicating failure with NaN errors.

Return type:

SingleFitResult

fitting.fit_results

Containers for fit results and cross-distribution summaries.

This module defines lightweight containers used throughout the fitting pipeline:

SingleFitResult: Result of fitting a single window for one distribution.
SeriesFitResult: Aggregates window-wise SingleFitResult for a distribution and computes derived arrays and metrics.
MultiSeriesFitResults: Aggregates multiple SeriesFitResult instances across distributions and produces a comparison-ready summary.

class los_estimator.fitting.fit_results.MultiSeriesFitResults(distros=None, *args, **kwargs)

Bases: OrderedDict[str, SeriesFitResult]

Aggregate results for multiple distributions and build summaries.

This container maps distribution names to their SeriesFitResult instances, and offers helpers to compute cross-distro arrays (e.g., error matrices) and a comparison summary DataFrame.

results

List of SeriesFitResult instances for each distribution.

Type:: list[SeriesFitResult]

distros

List of distribution names corresponding to the results.

Type:: list[str]

n_windows

Number of fitting windows across all distributions.

Type:: int

train_errors_by_distro

2D array of training errors with shape (n_windows, n_distros).

Type:: NDArray

test_errors_by_distro

2D array of test errors with shape (n_windows, n_distros).

Type:: NDArray

transition_rates_by_distro

2D array of transition rates with shape (n_windows, n_distros).

Type:: NDArray

transition_delays_by_distro

2D array of transition delays with shape (n_windows, n_distros).

Type:: NDArray

summary

Comparison DataFrame with error statistics and robustness metrics per distribution.

Type:: pd.DataFrame

bake()

Finalize all series and compute cross-distribution arrays.

Processes all distribution results and creates comparison matrices:

Calls bake() on each SeriesFitResult
Builds train/test error matrices (windows × distributions)
Computes transition rate and delay matrices
Generates summary DataFrame with statistics and robustness metrics

Returns:: Self, for method chaining.
Return type:: MultiSeriesFitResults

class los_estimator.fitting.fit_results.SeriesFitResult(distro)

Bases: object

Aggregate fit results across windows for a single distribution.

A SeriesFitResult collects SingleFitResult objects produced for each sliding window of a specific distribution and computes convenient arrays like train_errors, test_errors, and derived transition metrics.

distro

Distribution name for this series.

Type:: str

window_infos

Metadata for each processed window.

Type:: list[WindowInfo]

fit_results

Per-window fit result objects.

Type:: list[SingleFitResult]

train_errors

Array of training errors across windows.

Type:: NDArray

test_errors

Array of test errors across windows.

Type:: NDArray

all_kernels

Rolling kernel matrix (rows = day, cols = kernel width).

Type:: NDArray

transition_rates

Transition rate estimates from model configs.

Type:: NDArray

transition_delays

Transition delay estimates from model configs.

Type:: NDArray

append(window_info, fit_result)

Append a window and its fit result to the series.

Parameters:

window_info (WindowInfo) – Metadata about the processed window.
fit_result (SingleFitResult) – The fit result for the window.

bake()

Finalize the series by computing derived arrays and metrics.

This method aggregates individual window results and computes:

Training and test error arrays across all windows
Success/failure counts for optimizer convergence
Transition rate and delay estimates from model parameters

class los_estimator.fitting.fit_results.SingleFitResult(distro: str, train_data: object, test_data: object, success: bool, minimization_result: dict, train_error: numpy.typing.NDArray, test_error: numpy.typing.NDArray, kernel: numpy.typing.NDArray, distro_params: numpy.typing.NDArray, train_prediction: numpy.typing.NDArray | None = None, test_prediction: numpy.typing.NDArray | None = None, rel_train_error: numpy.typing.NDArray | None = None, rel_test_error: numpy.typing.NDArray | None = None, curve: numpy.typing.NDArray | None = None)

Bases: object

Result of a single-window fit for one distribution.

Instances capture artifacts produced by the optimizer for a specific window, including errors, predictions, and the fitted kernel. Relative error arrays and fitted curve can be attached if computed downstream.

distro

Distribution name (e.g., “lognorm”, “gaussian”).

Type:: str

train_data

Training data used for the fit.

Type:: object

test_data

Held-out data for evaluation.

Type:: object

success

Whether the optimizer reported success.

Type:: bool

minimization_result

Raw optimizer result object.

Type:: dict

train_error

Scalar training error for the window.

Type:: NDArray

test_error

Scalar test error for the window.

Type:: NDArray

kernel

Fitted kernel array for this window.

Type:: NDArray

model_config

Model configuration snapshot used during fitting.

Type:: ModelConfig

train_prediction

Optional model predictions on the training window.

Type:: NDArray | None

test_prediction

Optional model predictions on the test window.

Type:: NDArray | None

rel_train_error

Optional element-wise relative training error array.

Type:: NDArray | None

rel_test_error

Optional element-wise relative test error array.

Type:: NDArray | None

curve

Optional fitted curve points for visualization.

Type:: NDArray | None

classmethod create_failed(distro, train_data, test_data)

Create a SingleFitResult representing a failed fit.

Parameters:

distro (str) – Distribution name.
train_data (object) – Training data used for the fit.
test_data (object) – Held-out data for evaluation.

Returns:

Instance indicating failure with NaN errors.

Return type:

SingleFitResult

fitting.models

los_estimator.fitting.models.calc_its_comp(inc, discharge_rate, transition_rate, delay, init)

Calculate ICU occupancy using compartmental model.

Computes ICU bed occupancy using a compartmental model with transition rates, discharge rates, and delays between states.

Parameters:

inc (np.ndarray) – Daily incidence/admission data.
discharge_rate (float) – Rate of discharge from ICU.
transition_rate (float) – Rate of transition to ICU.
delay (float) – Delay between admission and ICU entry.
init (float) – Initial ICU occupancy.

Returns:

Predicted ICU occupancy over time.

Return type:

np.ndarray

los_estimator.fitting.models.calc_its_convolution(admissions, los_distro1)

Calculate ICU occupancy using convolution with LOS distribution.

Computes the ICU occupancy time series by convolving admission data with length of stay distributions, accounting for variable kernels over time.

Parameters:

admissions (np.ndarray) – Daily admission counts.
los_distro1 (np.ndarray) – Length of stay distribution(s).

Returns:

Predicted ICU occupancy time series.

Return type:

np.ndarray

los_estimator.fitting.models.objective_function_compartmental(model_config, inc, icu)

Objective function for compartmental model optimization.

Computes the error between predicted and observed ICU occupancy for use in optimization algorithms.

Parameters:

model_config (tuple) – Model parameters (discharge_rate, transition_rate, delay).
inc (np.ndarray) – Incidence/admission data.
icu (np.ndarray) – Observed ICU occupancy data.

Returns:

Mean squared error between predicted and observed values.

Return type:

float

fitting.los_fitter

Length of Stay fitting algorithms and utilities.

This module provides functions for fitting convolution-based models to hospital length of stay data using various distribution types and optimization methods.

los_estimator.fitting.los_fitter.combine_past_kernel(past_kernels: numpy.ndarray, kernel: numpy.ndarray) → numpy.ndarray

Combine past kernels with a new kernel.

Parameters:

past_kernels (np.ndarray) – Previously fitted kernels.
kernel (np.ndarray) – New kernel to add.

Returns:

Combined kernels stacked vertically.

Return type:

np.ndarray

los_estimator.fitting.los_fitter.fit_compartmental(train_data: Tuple[numpy.ndarray, numpy.ndarray], test_data: Tuple[numpy.ndarray, numpy.ndarray], initial_guess_comp: List[float], kernel_width: int, method: str = 'TNC', error_fun: str = 'mse') → SingleFitResult

Fit the compartmental model to a train/test split.

Runs bounded optimization over the compartmental parameters and returns a SingleFitResult with errors, predictions, and the fitted configuration.

Parameters:

train_data (tuple[np.ndarray, np.ndarray]) – (x_train, y_train) arrays.
test_data (tuple[np.ndarray, np.ndarray]) – (x_test, y_test) arrays.
initial_guess_comp (list[float]) – Initial values for the compartmental parameters.
kernel_width (int) – Window width used when slicing evaluation arrays.
method (str, optional) – Optimization method. Defaults to “TNC”.
error_fun (str, optional) – Error function name. Defaults to “mse”.

Returns:

Fit result including errors, predictions, and model config.

Return type:

SingleFitResult

los_estimator.fitting.los_fitter.fit_convolution(distro: str, train_data: Tuple[numpy.ndarray, numpy.ndarray], test_data: Tuple[numpy.ndarray, numpy.ndarray], kernel_width: int, distro_boundaries: List[Tuple[float | None, float | None]] | None = None, distro_init_params: List[float] | None = None, past_kernels: numpy.ndarray | None = None, method: str = 'L-BFGS-B', error_fun: str = 'mse') → SingleFitResult

Fit a convolution-based model to length of stay data.

Performs optimization to find the best parameters for a specified distribution that minimizes the error between predicted and observed ICU occupancy.

Parameters:

distro (str) – Distribution type for the kernel (e.g., ‘gamma’, ‘lognormal’).
train_data (tuple) – (x_train, y_train) training data arrays.
test_data (tuple) – (x_test, y_test) test data arrays.
kernel_width (int) – Width of the distribution kernel in days.
distro_boundaries (list, optional) – Parameter bounds for optimization.
distro_init_params (list, optional) – Initial parameter values.
past_kernels (np.ndarray, optional) – Previously fitted kernels to combine.
method (str, optional) – Optimization method. Defaults to “L-BFGS-B”.
error_fun (str, optional) – Error function name. Defaults to “mse”.

Returns:

Object containing fit results, parameters, and predictions.

Return type:

SingleFitResult

los_estimator.fitting.los_fitter.get_objective_convolution(distro: str, kernel_width: int, error_fun: Callable[[numpy.ndarray, numpy.ndarray], float]) → Callable[[numpy.ndarray, numpy.ndarray, numpy.ndarray, numpy.ndarray | None], float]

Create an objective function for convolution-based fitting.

Parameters:

distro (str) – Distribution type for the kernel.
kernel_width (int) – Width of the kernel in days.
error_fun (callable) – Error function to minimize.

Returns:

Objective function that takes model parameters and data.

Return type:

callable

Initialize distribution parameters and boundaries for optimization.

Sets up default boundaries and initial parameters for a given distribution if not provided by the user.

Parameters:

distro (str) – Distribution type name.
distro_boundaries (list, optional) – Parameter boundaries for optimization.
distro_init_params (list, optional) – Initial parameter values.

Returns:

(distro_boundaries, distro_init_params) with defaults applied.

Return type:

tuple

los_estimator.fitting.los_fitter.objective_compartemental(error_fun: Callable[[numpy.ndarray, numpy.ndarray], float]) → Callable[[numpy.ndarray, numpy.ndarray, numpy.ndarray, int], float]

Create an objective function for compartmental model fitting.

Parameters:: error_fun (callable) – Error function to minimize.
Returns:: Objective function for compartmental model optimization.
Return type:: callable