rxnfit.expdata_fit module

Estimate unknown rate constants from experimental concentration trajectories.

Minimizers in scipy.optimize drive repeated ODE integrations through rxnfit.solver_backend.solve_ode(); see there for LSODA / numbalsoda behavior and SciPy fallbacks.

class rxnfit.expdata_fit.ExpDataFit(builded_rxnode, df_list, t_range, method='RK45', rtol=1e-06, df_names=None)

Bases: object

High-level façade over pooled least-squares fits and post-fit replay.

Internally drives solve_fit_model_multi() and exposes helpers compatible with RxnODEsolver.

get_fitted_rate_const_dict(result=None)

Map symbolic names to optimized numeric rates.

Parameters:: result – External OptimizeResult or None to reuse cached output.
Returns:: Plain dict mergeable back into builded_rxnode.rate_consts_dict.
Raises:: RuntimeError – Missing prior optimization state.

get_solver_config_args(dataset_index=0)

Build kwargs for SolverConfig post-fit.

Parameters:: dataset_index – Which pooled dataset supplies y0/t0.
Returns:: Mapping with y0, t_span, integrator knobs, plus optional callable rate hooks for time-dependent kinetics.
Raises:: RuntimeError – If run_fit() has not finished and stored state, or (when kinetics are time-dependent) _result is missing before building the evaluator.

Replay best parameters with overlays mirroring plot_time_course_solutions.

Parameters:

expdata_df – Optional replacement overlay tables; defaults to inputs.
plot_datasets – Subset selector against df_names.
species – Restrict plotted columns; None keeps all.
subplot_layout – Manual subplot grid sizing.

Returns:

None

Raises:

RuntimeError – Missing fit artifacts.
ValueError – Unknown dataset labels or dataframe shape mismatches.

run_fit(p0, opt_method='L-BFGS-B', bounds=None, verbose=True, use_log_fit=False, lower_bound=None, error_metric='rss')

Optimize rate constants via scipy.optimize.minimize().

Parameters:

p0 – Sequence aligned with symbolic keys or explicit name→value mapping. Log-space mode rejects non-positive entries.
opt_method – SciPy method string forwarded unchanged.
bounds – Box constraints for linear mode; superseded under log-fit.
verbose – Toggle progress printing.
use_log_fit – Optimize log(k) internally while exposing linear k.
lower_bound – Optional shared positivity floor (mode dependent).
error_metric – Objective for minimization. 'rss' (default) minimizes the residual sum of squares (RSS). 'mae' minimizes the sum of absolute residuals (SAE); reported MAE in fit metrics is SAE / n_datapoints. Only lowercase 'rss' or 'mae' are accepted.

Returns:

(OptimizeResult-like, param_info, metrics_dict) where metrics_dict has keys 'rss', 'tss', 'r2', 'rmse', 'mae', 'n_datapoints'. result.fun is the minimized sum (RSS or SAE), not necessarily MAE.

Raises:

ValueError – Invalid seeds, bounds, incompatible log guesses, or invalid error_metric.

to_dataframe_list(time_column_name='time')

Materialize every replayed trajectory via _ode_result_to_dataframe().

Parameters:: time_column_name – Leading column label for timestamps.
Returns:: Parallel list mixing pandas.DataFrame entries and None holes.
Raises:: RuntimeError – Missing optimized state.

rxnfit.expdata_fit.run_fit_multi(builded_rxnode, df_list, p0, t_range=None, method='RK45', rtol=1e-06, df_names=None, opt_method='L-BFGS-B', bounds=None, verbose=True, use_log_fit=False, lower_bound=None, error_metric='rss')

Stateful-free shortcut constructing ExpDataFit then run_fit().

When t_range is omitted it becomes the min/max of the first dataframe’s time column.

Parameters:

builded_rxnode – Reaction scaffold.
df_list – Experimental bundle.
p0 – Seeds understood by ExpDataFit.run_fit().
t_range – Optional manual span tuple.
method – Forwarded to the constructor.
rtol – Forwarded to the constructor.
df_names – Forwarded to the constructor.
opt_method – Forwarded to run_fit().
bounds – Forwarded to run_fit().
verbose – Forwarded to run_fit().
use_log_fit – Forwarded to run_fit().
lower_bound – Forwarded to run_fit().
error_metric – Forwarded to run_fit().

Returns:

Same triple as ExpDataFit.run_fit().

Raises:

ValueError – Validation errors bubbled up from pooling or SciPy phases.

rxnfit.expdata_fit.solve_fit_model(builded_rxnode, fixed_initial_values, t_span, method='RK45', rtol=1e-06)

Build f(t, *params) that predicts species trajectories during fitting.

Bare symbolic rate constants (Symbol) are optimized via params; every other rate_consts_dict entry (numbers, expressions, etc.) stays in the merged constants dict passed to the RHS. fixed_initial_values are fixed ICs.

Parameters:

builded_rxnode – Configured reaction network.
fixed_initial_values – Species IC vector aligned with function_names.
t_span – Global integration window covering every experimental time.
method – Passed through to solve_ode().
rtol – Relative tolerance for integrations.

Returns:

functools.partial wrapping _eval_ode_fit() plus a param_info dict attached as attribute param_info.

Raises:

ValueError – Wrong IC length versus species count.

rxnfit.expdata_fit.solve_fit_model_multi(builded_rxnode, df_list, t_span, method='RK45', rtol=1e-06, df_names=None, error_metric='rss')

Prepare multi-experiment objective sharing one kinetic parameter vector.

Each DataFrame yields its own (y0, t0); integrations stop at t_span[1].

Parameters:

builded_rxnode – Configured reaction network.
df_list – Homogeneous experimental tables (time + species columns).
t_span – Global window enclosing every observation time.
method – Passed to solve_ode().
rtol – Relative integration tolerance.
df_names – Optional labels; see _resolve_df_names().
error_metric – 'rss' (minimize RSS) or 'mae' (minimize SAE). Only lowercase 'rss' or 'mae' are accepted. For 'mae', the optimizer minimizes the sum of absolute residuals (SAE); reported MAE in fit metrics is SAE / n_datapoints.

Returns:

(objective, param_info, fit_ctx) where objective(params) returns the selected sum (RSS or SAE) and fit_ctx backs plotting helpers.

Raises:

ValueError – Empty df_list, invalid column layout, or bad error_metric.