***********
Get Started
***********

This guide walks you through the basic workflow of loading data, fitting a consumer–resource model (CRM), and visualizing the results. For installation instructions, see the :doc:`installation` section.

Loading Data
============

Load experimental time-series data from a CSV file:

.. code-block:: python

    from mgrowthctrl.utils.data import Dataloader

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

This example uses the dataset `BT_WC_export.csv <https://gitlab.com/ComputationalScience/mgrowthctrl/-/raw/main/examples/datasets/BT_WC_export.csv>`_. For further details on the data loader, see the :doc:`../utilities/data_loader` section.


Initializing and Fitting a Model
================================

We can create a CRM with default parameters and fit it by using :doc:`least-squares fitting <../fitting/lsq>`:

.. code-block:: python

    from mgrowthctrl.models import CRModel, CRModelParams

    # Initialize parameters
    params = CRModelParams.from_shapes(n=len(data.X_names), m=len(data.S_names))

    # Create model
    model = CRModel(names=data.names, params=params)
    print(model.n, model.m)

    # Fit model with the defaults (updates internal parameters)
    model.fit(
        df=data.df,
        time_col=data.time_col,
        x_cols=data.X_names,
        s_cols=data.S_names,
    )

If we use this model, it's likely that the fit won't be very good, because we don't have reasonable default parameters. In this particular example, since we only have data for a single species, we can extract a good guess for them from the data:

.. code-block:: python

    from mgrowthctrl.models import CRModel, CRModelParams

    # Initialize model with parameters from the data
    model = CRModel.from_single_species_data(
        df=data.df,
        time_col=data.time_col,
        x_col=data.X_names[0],  # Note: expects a single species string here
        s_cols=data.S_names,
    )

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

We'll use this second example for the next sections, since it will provide better predictions. Note that the :meth:`CRModel.from_single_species_data() <mgrowthctrl.models.crm.model.CRModel.from_single_species_data>` method is only usable here because we have a monoculture.

If you have a culture with multiple species, you should go through the :doc:`../models/consumer_resource_model` tutorial, where you can find a discussion of the parameters along with the full reference documentation of the :class:`CRModelParams <mgrowthctrl.models.crm.model.CRModelParams>` class.

Simulating Trajectories
=======================

Generate model predictions:

.. code-block:: python

    import numpy as np

    # Time points
    t_sim = np.linspace(data.start_time, data.end_time, num=200)

    # Simulate
    sim = model.simulate(data.y0, t_sim)

    print(sim.t.shape)
    print(sim.X.shape)
    print(sim.S.shape)

Visualization
=============

Plot data with model overlay using :func:`~mgrowthctrl.utils.plot.plot_data_with_overlay`:

.. code-block:: python

    from mgrowthctrl.utils.plot import plot_data_with_overlay

    plot_data_with_overlay(
        data.df,
        sim=sim,
        overlay="model",

        # Column names:
        time_col=data.time_col,
        x_cols=data.X_names,
        s_cols=data.S_names,

        # If save prefix is provided, saves plots to files:
        # - example_plot_species.png
        # - example_plot_metabolites.png
        save_prefix="example_plot",
    )

Here's what those predictions look like:

.. image:: ../_static/example_plot.png
   :alt: Example predictions
   :align: center

Further visualization options are described in the :doc:`../utilities/visualization` section.

If you'd like to save the simulation data in a CSV file for later plotting or analysis, you can use the utility function :func:`~mgrowthctrl.utils.save.save_simulation_results`:

.. code-block:: python

   from mgrowthctrl.utils.save import save_simulation_results

   save_simulation_results(sim, data.names, 'saved_data.csv')