1543 harmonize description of time series infection states etc in documentation

docs/source/cpp/data_types.rst

@@ -21,7 +21,7 @@ The following list explains the nonstandard data types that are used throughout
      - A contiguous array whose values can be accessed by a multi-index, e.g. a :code:`mio::Index` with one or more categories. This datatype is, for example, used in the parameter :code:`mio::abm::TimeExposedToNoSymptoms` making it dependent on :code:`mio::abm::VirusVariant` and :code:`mio::AgeGroup`. Its values can then be set for a specific :code:`virus_variant` and :code:`age_group` using :code:`model.parameters.template get<mio::abm::TimeInfectedSevereToCritical>()[{virus_variant, age_group}]`.
    * - :code:`Populations`
      - Is a :code:`mio::CustomIndexArray` with :code:`mio::UncertainValue<FP>` as values. Adds some convenient functions like :code:`get_group_total`.
-   * - :code:`TimeSeries`
+   * - ``TimeSeries``
      - Stores vectors of values at time points. Each time point has a vector of values of the same size with operations like adding time points, retrieving values, exporting to CSV, etc. It's also used for storing and analyzing simulation results over time.
    * - :code:`Graph`
      - A generic graph structure that represents a network of nodes connected by edges. Each node and edge can have associated properties. The graph is used to model geographical regions connected by mobility patterns (e.g., commuting), where each node is represented by its own epidemiological model.
@@ -41,9 +41,9 @@ The following list explains the nonstandard data types that are used throughout
      - Parameters that influence mobility between nodes, including coefficients and dynamic nonpharmaceutical interventions (NPIs).
    * - :code:`MobilityEdge`
      - Represents mobility between two nodes in a graph. Handles the movement of populations between nodes, tracks mobile populations, and applies mobility returns according to epidemiological models.
-   * - :code:`ContactMatrix`
+   * - ``ContactMatrix``
      - Time-dependent contact frequencies between groups, derived from ``DampingMatrixExpression``. Models how the contact rates between different age groups change over time due to interventions.
-   * - :code:`ContactMatrixGroup`
+   * - ``ContactMatrixGroup``
      - A collection of contact matrices that represent different contexts (e.g., home, school, work) whose sum is the total number of contacts, derived from ``DampingMatrixExpressionGroup``.
    * - :code:`DampingMatrixExpression`
      - Represents a coefficient-wise matrix expression :math:`B - D \odot (B - M)`, where :math:`B` is a baseline matrix, :math:`M` is a minimum matrix, :math:`D` is a time-dependent complex damping factor, and :math:`\odot` is element wise multiplication. Used as the base for time-dependent contact matrices.

docs/source/cpp/diffusive_abm.rst

@@ -10,7 +10,7 @@ The features of an agent are its position and its infection state. The evolution
 
 with :math:`X` the vector of all agents' positions and :math:`Z` the vector of all agents' infection states. The operator :math:`G` defines the infection state adoptions and only acts on :math:`Z`, while :math:`L` defines movement, i.e. location changes, only acting on :math:`X`. Infection state adoptions are modeled with independent Poisson processes given by adoption rate functions. Movement is modeled with independent diffusion processes. A temporal Gillespie algorithm (a direct method without rejection sampling) is used for simulation. Therefore, :math:`G` and :math:`L` are not implemented explicitly, instead their effects are sampled via the `move` and `adoption_rate` functions, respectively.
 
-The Model class needs an Implementation class as template argument which provides the domain agents move and interact in. A quadwell potential and a singlewell potential given in the classes **QuadWell** and **SingleWell** respectively are implemented, but any other suitable potential can be used as implementation. 
+The Model class needs an Implementation class as template argument which provides the domain agents move and interact in. A quadwell potential and a singlewell potential given in the classes ``QuadWell`` and ``SingleWell`` respectively are implemented, but any other suitable potential can be used as implementation. 
 
 In the following, we present more details of the diffusive agent-based model, including code examples. 
 An overview of nonstandard but often used data types can be found under :doc:`data_types`.
@@ -40,7 +40,7 @@ Using the infection states Susceptible (S), Exposed (E), Carrier (C), Infected (
 Infection state transitions
 ---------------------------
 
-The infection state transitions are explicitly given by the adoption rates and are therefore subject to user input. Adoption rates always depend on their source infection state. If an adoption event requires interaction of agents (e.g. disease transmission), the corresponding rate depends not only on the source infection state, but also on other infection states, the **Influence**\s. An adoption rate that only depends on the source infection state, e.g. recovery or worsening of disease symptoms, is called `first-order` adoption rate and an adoption rate that has influences is called `second-order` adoption rate. Adoption rates are region-dependent; therefore it is possible to have different rates in two regions for the same state transition which can be useful when having e.g. region-dependent interventions or contact behavior.
+The infection state transitions are explicitly given by the adoption rates and are therefore subject to user input. Adoption rates always depend on their source infection state. If an adoption event requires interaction of agents (e.g. disease transmission), the corresponding rate depends not only on the source infection state, but also on other infection states, the ``Influence``\s. An adoption rate that only depends on the source infection state, e.g. recovery or worsening of disease symptoms, is called `first-order` adoption rate and an adoption rate that has influences is called `second-order` adoption rate. Adoption rates are region-dependent; therefore it is possible to have different rates in two regions for the same state transition which can be useful when having e.g. region-dependent interventions or contact behavior.
 
 Using the infection states from above and only one region, there are five first-order and one second-order adoption rate that can be set via: 
 
@@ -134,7 +134,7 @@ Simulation
 
 The simulation runs in discrete time steps. In every step the model is advanced until the next infection state adoption event. Then the corresponding agent's infection state is adopted and a new waiting time until the next adoption event is drawn. If the waiting time until the next adoption event is bigger than the remaining time in the time step, we advance the model until the end of the time step.
 
-To simulate the model from `t0` to `tmax` with given step size `dt`, a **Simulation** has to be created and advanced until `tmax`, which is done as follows:
+To simulate the model from `t0` to `tmax` with given step size `dt`, a ``Simulation`` has to be created and advanced until `tmax`, which is done as follows:
 
 .. code-block:: cpp
 
@@ -161,7 +161,7 @@ The model holds a vector containing all agents that can be accessed via
 
     sim.get_model().populations
 
-Additionally, the agents are automatically aggregated by region and infection state in a ``mio::TimeSeries`` object which can be accessed and printed as follows:
+Additionally, the agents are automatically aggregated by region and infection state in a ``TimeSeries`` object which can be accessed and printed as follows:
 
 .. code-block:: cpp
 
@@ -171,7 +171,7 @@ Additionally, the agents are automatically aggregated by region and infection st
     //Print result object to console. Infection state "Xi" with i=0,...,3 is the number of agents having infection state X in region i
     result.print_table({"S0", "E0", "C0", "I0", "R0", "D0", "S1", "E1", "C1", "I1", "R1", "D1", "S2", "E2", "C2", "I2", "R2", "D2", "S3", "E3", "C3", "I3", "R3", "D3"})
 
-If one wants to interpolate the aggregated results to a ``mio::TimeSeries`` containing only full days, this can be done by
+If one wants to interpolate the aggregated results to a ``TimeSeries`` containing only full days, this can be done by
 
 .. code-block:: cpp
 

docs/source/cpp/glct.rst

@@ -11,23 +11,23 @@ An overview of nonstandard but often used data types can be found under :doc:`da
 Infection states
 ----------------
 
-The model contains a list of **InfectionState**\s that define particular features of the subpopulations in the particular state.
+The model contains a list of ``InfectionState``\s that define particular features of the subpopulations in the particular state.
 
 .. code-block:: RST
 
     `State1`
     `State2`
     `...`
 
-To make use of the GLCT, we additionally need to define the numbers of subcompartments for each **InfectionState**.
-This is done by creating an **LctInfectionState** object for each group. These objects are then passed as template 
+To make use of the GLCT, we additionally need to define the numbers of subcompartments for each ``InfectionState``.
+This is done by creating an ``LctInfectionState`` object for each group. These objects are then passed as template 
 parameter to the model. 
 
 .. code-block:: cpp
 
     using LctStateGroup1 = mio::LctInfectionState<ScalarType, ListofInfectionStates, NumberofsubcompartmentsofState1, NumberofsubcompartmentsofState2, ...>;
 
-The model is implemented as **CompartmentalModel**.
+The model is implemented as ``CompartmentalModel``.
 
 
 Parameters
@@ -38,10 +38,10 @@ We use different types of parameters to represent epidemiological parameters suc
 compartment or the contact rates between different age groups. Most model parameters are constants that describe 
 pathogen-specific characteristics (possibly resolved by sociodemographic groups) and are represented by a vector with 
 a value for each sociodemographic group. To model different contact rates between different sociodemographic groups, 
-we use a parameter denoted **ContactPatterns** of type **UncertainContactMatrix**. The **UncertainContactMatrix** contains an
+we use a parameter denoted ``ContactPatterns`` of type ``UncertainContactMatrix``. The ``UncertainContactMatrix`` contains an
 arbitrary large set of contact matrices which can e.g. represent the different contact locations in the model 
 like schools, workplaces, or homes. The matrices can be loaded or stored in the particular example.
-In the **ContactPatterns**, each matrix element stores baseline contact rates :math:`c_{i,j}` between sociodemographic 
+In the ``ContactPatterns``, each matrix element stores baseline contact rates :math:`c_{i,j}` between sociodemographic 
 group :math:`i` to group :math:`j`. The dimension of the matrix is automatically defined by the model initialization 
 and it is reduced to one value if no stratification is used. The values can be adjusted during the simulation, e.g., 
 through implementing nonpharmaceutical interventions, see the section on :ref:`Nonpharmaceutical Interventions GLCT`.
@@ -52,14 +52,14 @@ Parameters can be accessed via ``model.parameters.get<Param<double>>()`` and set
 Initial conditions
 ------------------
 
-The initial conditions of the model are represented by a class **LctPopulations** that gives the number of individuals in each sociodemographic group and each subcompartment of each **InfectionState**. For more details, see :doc:`Model Creation <lct_creation>`. Before the simulation, the initial conditions for each **InfectionState** and sociodemographic group must be set.
+The initial conditions of the model are represented by a class ``LctPopulations`` that gives the number of individuals in each sociodemographic group and each subcompartment of each ``InfectionState``. For more details, see :doc:`Model Creation <lct_creation>`. Before the simulation, the initial conditions for each ``InfectionState`` and sociodemographic group must be set.
 
 
 .. _Nonpharmaceutical Interventions GLCT:
 Nonpharmaceutical interventions
 -------------------------------
 
-Contact rates can be adjusted during the simulation to model nonpharmaceutical interventions (NPIs) such as lockdowns, school closures, or social distancing. This is done by adding **Damping**\s to the **ContactPatterns** of the model. A **Damping** is defined by a time point at which the intervention starts and a matrix of the same size as the **ContactMatrix**. While in many cases, the reduction matrix is given by a constant matrix with factor :math:`r`, also group-specific reductions are possible through setting particular rows or columns differently. With a constant reduction factor :math:`r`, the reduced contact rate is :math:`(1-r) * c_{i,j}`.
+Contact rates can be adjusted during the simulation to model nonpharmaceutical interventions (NPIs) such as lockdowns, school closures, or social distancing. This is done by adding ``Damping``\s to the ``ContactPatterns`` of the model. A ``Damping`` is defined by a time point at which the intervention starts and a matrix of the same size as the ``ContactMatrix``. While in many cases, the reduction matrix is given by a constant matrix with factor :math:`r`, also group-specific reductions are possible through setting particular rows or columns differently. With a constant reduction factor :math:`r`, the reduced contact rate is :math:`(1-r) * c_{i,j}`.
 
 .. dropdown:: :fa:`gears` Expert's settings
 
@@ -78,17 +78,17 @@ Contact rates can be adjusted during the simulation to model nonpharmaceutical i
 Simulation
 ----------
 
-Once the model is setup, one can run a simple simulation from time ``t0`` to ``tmax`` with initial step size ``dt`` using the ``mio::simulate()`` function. This will run a simulation of type **Simulation** that saves the sizes of each subcompartment over time. 
+Once the model is setup, one can run a simple simulation from time ``t0`` to ``tmax`` with initial step size ``dt`` using the ``mio::simulate()`` function. This will run a simulation of type ``Simulation`` that saves the sizes of each subcompartment over time. 
 You can run a simulation using either fixed or adaptive integration schemes with an absolute or relative tolerance. By default, the simulation uses an adaptive solution scheme of the boost library with an absolute tolerance of 1e-10 and a relative tolerance of 1e-5. For more details on the possible integration schemes, see <numerical integrator stuff>.
 
 
 Output
 ------
 
-The output of the **Simulation** is a ``mio::TimeSeries`` containing the sizes of each subcompartment at each time point. 
+The output of the ``Simulation`` is a ``TimeSeries`` containing the sizes of each subcompartment at each time point. 
 To obtain a result with respect to the compartments, the subcompartments can be accumulated via the function 
 ``calculate_compartments()``. A simple table can be printed using the ``print_table()`` function of the 
-``mio::TimeSeries`` class. The compartment sizes can be printed with ``model.calculate_compartments(result).print_table()``. 
+``TimeSeries`` class. The compartment sizes can be printed with ``model.calculate_compartments(result).print_table()``. 
 As adaptive step size methods are used by default, the output will not be available on equidistant time points like `dt` or days. To obtain outputs on days or user-defined time points, you can interpolate the results to days or any other series of times points with ``mio::interpolate_simulation_result()``.