acia.analysis.growth_rate#

Unit-aware exponential growth-rate estimation from extractor tables.

This module fits the exponential growth model Q(t) = Q0 * exp(mu * t) to a property-extractor DataFrame (the output of acia.analysis.ExtractorExecutor). The fit is performed as an ordinary least squares (OLS) regression of log(y) on time t using statsmodels, which yields the growth rate mu together with its fit uncertainty (standard error, confidence interval, p-value) and the coefficient of determination R^2 for free.

All rate-like quantities are returned as pint.Quantity objects built from the shared acia.ureg registry, so the growth rate is independent of the imaging interval and inter-operates with the rest of the unit-aware library.

acia.analysis.growth_rate.AggMode#

aggregation modes accepted by estimate_growth_rate()

alias of Literal[‘sum’, ‘mean’, ‘count’]

acia.analysis.growth_rate.DEFAULT_TIME_UNIT = 'hour'#

default time unit used when none can be inferred from the DataFrame or args

class acia.analysis.growth_rate.GrowthRateResult[source]#

Bases: object

Result of an exponential growth-rate fit.

All rate quantities are pint.Quantity in 1 / time_unit and doubling_time is a pint.Quantity in time_unit, where the time unit is inferred from the source DataFrame (see estimate_growth_rate()).

Variables:

  • growth_rate (pint.registry.Quantity) – The fitted growth rate mu (slope of log(y) vs. t), in 1 / time_unit.

  • growth_rate_std_err (pint.registry.Quantity) – Standard error of the fitted growth rate, in 1 / time_unit. Only meaningful with >= 3 time points.

  • growth_rate_ci (tuple[pint.registry.Quantity, pint.registry.Quantity]) – (low, high) confidence-interval bounds for the growth rate, in 1 / time_unit. Only meaningful with >= 3 time points.

  • doubling_time (pint.registry.Quantity) – The doubling time ln(2) / mu, in time_unit; nan when the growth rate is not positive (a non-growing population never doubles). With fewer than 3 time points the SE/CI/p-value are nan.

  • initial_value (float) – The fitted initial quantity Q0 = exp(intercept) (a plain float in the units of the aggregated quantity).

  • r_squared (float) – Coefficient of determination of the log-linear fit.

  • p_value (float) – Two-sided p-value for the growth-rate (slope) coefficient.

growth_rate: Quantity#
growth_rate_std_err: Quantity#
growth_rate_ci: tuple[Quantity, Quantity]#
doubling_time: Quantity#
initial_value: float#
r_squared: float#
p_value: float#
__init__(growth_rate, growth_rate_std_err, growth_rate_ci, doubling_time, initial_value, r_squared, p_value)#
Parameters:
Return type:

None

acia.analysis.growth_rate.estimate_growth_rate(df, *, time_col='time', value_col='area', agg='sum', time_unit=None, ci_level=0.95, ax=None)[source]#

Estimate the exponential growth rate from an extractor DataFrame.

Groups df by time_col, aggregates the chosen quantity, and fits the exponential model Q(t) = Q0 * exp(mu * t) as an OLS regression of log(y) on t using statsmodels. From the single fit it derives the growth rate mu and its uncertainty.

Parameters:

  • df (pd.DataFrame) – an acia.analysis.ExtractorExecutor output DataFrame, with a time column and (for agg in {"sum", "mean"}) a value column. The time unit is read from df.attrs["units"][time_col] when present.

  • time_col (str) – name of the time column to group by.

  • value_col (str) – name of the value column to aggregate. Ignored when agg="count".

  • agg (AggMode) – how to aggregate the quantity per time point – "sum" (total, default), "mean" or "count" (number of rows per time, i.e. cell-count growth).

  • time_unit (str | None) – explicit time unit, used only when the unit cannot be inferred from df.attrs["units"]. Defaults to "hour" if also absent.

  • ci_level (float) – confidence level for growth_rate_ci (default 0.95).

  • ax (Axes | None) – optional matplotlib Axes to draw into. When None a new figure and axes are created.

Returns:

A (result, figure) tuple – a GrowthRateResult and a matplotlib Figure showing the aggregated quantity vs. time with the fitted exponential curve. The figure is not shown (no plt.show()).

Raises:

ValueError – if there are fewer than two distinct time points, or if any aggregated quantity is not strictly positive (the log requires y > 0).

Return type:

tuple[GrowthRateResult, Figure]

Note

The standard error and confidence interval are only meaningful with at least three time points; with exactly two points the fit is perfect (zero residual degrees of freedom) and the reported SE/CI degenerate.