**********************
Least-Squares Fitting
**********************

One of the two fitting methods available in :meth:`CRModel.fit() <mgrowthctrl.models.crm.model.CRModel.fit>` is least-squares estimation (LSE). For Markov Chain Monte Carlo (MCMC), see :doc:`mcmc`.

Background
==========

To obtain point estimates of the model parameters, we simulate the model and interpolate the resulting species and (optionally) metabolite trajectories to the experimental measurement times using `scipy.interpolate.PchipInterpolator`. We then compute scaled residuals between model predictions and observations.

The objective function is the sum of squared scaled errors (SSE) across all observed species and, optionally, metabolites,

.. math::

   \mathrm{SSE}(\theta)
   = \sum_i \sum_k
   \left(\frac{\hat{X}_i(t_k;\theta) - X_i(t_k)}{s_{X,i}}\right)^2
   + \sum_j \sum_k
   \left(\frac{\hat{S}_j(t_k;\theta) - S_j(t_k)}{s_{S,j}}\right)^2\,,

where :math:`\theta` denotes the vector of model parameters, :math:`t_k` are the experimental measurement times, :math:`X_i(t_k)` and :math:`S_j(t_k)` are the observed concentrations of species :math:`i` and resource :math:`j`, :math:`\hat{X}_i(t_k;\theta)` and :math:`\hat{S}_j(t_k;\theta)` are the corresponding model predictions, and :math:`s_{X,i}` and :math:`s_{S,j}` are scaling factors for species and metabolite residuals. Missing observations are ignored in the construction of the residuals.

We minimize this objective using the Trust Region Reflective (TRF) algorithm implemented in `scipy.optimize.least_squares`, with parameter bounds to enforce biologically meaningful values.

Example
=======

We load experimental time-series data from the `BT_WC_export.csv <https://gitlab.com/ComputationalScience/mgrowthctrl/-/raw/main/examples/datasets/BT_WC_export.csv>`_ file and fit a consumer-resource model (CRM) to the data.

.. code-block:: python

    from mgrowthctrl.utils.data import Dataloader
    from mgrowthctrl.models.crm.model import CRModel

    # Load dataset
    data = Dataloader()
    data.load_local_data(
        "examples/datasets/BT_WC_export.csv",
        x_selector=r"BT counts",
    )

    # Initialize model from data
    model = CRModel.from_single_species_data(
        df=data.df,
        time_col=data.time_col,
        x_col=data.X_names[0],
        s_cols=data.S_names,
    )

    # Fit model parameters
    model.fit(
        df=data.df,
        time_col=data.time_col,
        x_cols=data.X_names,
        s_cols=data.S_names,
    )

The function :meth:`CRModel.from_single_species_data() <mgrowthctrl.models.crm.model.CRModel.from_single_species_data>` provides a mechanistic initialization of a single-species CRM. It is not recommended using it for multi-species settings.

For a more detailed walkthrough, see :doc:`../intro/get_started`.

Backend API
===========

.. autofunction:: mgrowthctrl.models.crm.fit.crm_fit_mechanistic