phenotypic.analysis.abc_#

Provides the base classes for set analysis operations.

This module imports and exposes the SetAnalyzer class from the internal _set_analyzer module. The SetAnalyzer class is designed for performing various analytical operations on sets. This is a utility module intended for use in applications that require set analysis functionality. Only the SetAnalyzer class is explicitly exposed as part of this module’s public API.

class phenotypic.analysis.abc_.ModelFitter(on: str, groupby: List[str], time_label: str = 'Metadata_Time', agg_func: Callable | str | list | dict | None = 'mean', *, num_workers: int = 1, loss: Literal['linear'] = 'linear', verbose: bool = False)[source]#

Bases: SetAnalyzer, ABC

Template base class for grouped least-squares model fitting.

Subclasses provide the mathematical model (model_func), the loss function (_loss_func), an initial parameter guess, parameter bounds, and a small set of hooks that let the base class drive analyze, show, dash, and results without hard-coding parameter names.

Fit-quality metrics (MAE, MSE, RMSE, R²) and optimizer diagnostics (loss, status, sample count) are emitted under the shared MODEL_METRICS category so that every ModelFitter subclass produces a consistent set of diagnostic columns.

Parameters:

  • on (str)

  • groupby (List[str])

  • time_label (str)

  • agg_func (Callable | str | list | dict | None)

  • num_workers (int)

  • loss (Literal['linear'])

  • verbose (bool)

time_label#

Column name representing the independent variable (typically time).

Type:

str

loss#

Loss calculation method passed through to scipy.optimize.least_squares().

Type:

Literal[“linear”]

verbose#

Whether to print detailed optimizer output.

Type:

bool

analyze(data: pandas.DataFrame) → pandas.DataFrame[source]#

Fit the model to every group of data and return the results.

Standard template: copy, float-coerce the time column, aggregate to one sample per timepoint, dispatch per-group fits (serial or parallel via joblib.Parallel), concatenate, and append constant hyperparameter columns from _post_fit_columns.

Parameters:

data (pandas.DataFrame)

Return type:

pandas.DataFrame

dash(tmax: int | float | None = None, criteria: Dict[str, Any | List[Any]] | None = None, figsize=(6, 4), cmap: str | None = 'tab20', legend: bool = True, **kwargs) → go.Figure[source]#

Interactive Plotly version of show().

Hover tooltips are populated from _hover_fields so subclasses can expose whichever fitted parameters and metrics are most meaningful for their model.

Raises:

ImportError – If plotly is not installed.

Parameters:

  • tmax (int | float | None)

  • criteria (Dict[str, Union[Any, List[Any]]] | None)

  • cmap (str | None)

  • legend (bool)

Return type:

go.Figure

abstract static model_func(*args, **kwargs)[source]#

Mathematical model. First positional argument is the independent variable.

results() → pandas.DataFrame[source]#

Return the most recent fit results produced by analyze().

Return type:

pandas.DataFrame

show(tmax: int | float | None = None, criteria: Dict[str, Any | List[Any]] | None = None, figsize=(6, 4), cmap: str | None = 'tab20', legend: bool = True, ax: plt.Axes | None = None, **kwargs) → Tuple[plt.Figure, plt.Axes][source]#

Plot model predictions alongside measurements with optional filtering.

Parameters:

  • tmax (int | float | None) – Upper bound of the prediction curve. If None, uses the maximum observed time.

  • criteria (Dict[str, Union[Any, List[Any]]] | None) – Column/value filter applied to both fitted results and raw measurements before plotting.

  • figsize – Matplotlib figure size. Used only when ax is None.

  • cmap (str | None) – Matplotlib colormap name, a single color string, or None for matplotlib’s default color cycle.

  • legend (bool) – Whether to render a legend (auto-removed if larger than the axes).

  • ax (plt.Axes | None) – Existing axes to draw into. A new figure is created when omitted.

  • **kwargs – Styling overrides — dpi, facecolor, edgecolor, line_width, marker_size, elinewidth, capsize, legend_loc, legend_fontsize, label.

Returns:

A (Figure, Axes) pair.

Return type:

Tuple[plt.Figure, plt.Axes]

class phenotypic.analysis.abc_.SetAnalyzer(on: str, groupby: List[str], agg_func: Callable | str | list | dict | None = 'mean', *, num_workers=1)[source]#

Bases: ABC

Parameters:
abstract analyze(data: pandas.DataFrame) → pandas.DataFrame[source]#
Parameters:

data (pandas.DataFrame)

Return type:

pandas.DataFrame

dash(**kwargs)[source]#

Interactive Plotly visualization of analysis results.

Subclasses may override this method to provide an interactive Plotly figure equivalent to show().

Raises:

NotImplementedError – Unless overridden by a subclass.

abstract results()[source]#
abstract show()[source]#