Merge pull request #271 from DavAug/doc-updateds-joss

Doc updateds joss

README.md

@@ -43,11 +43,11 @@ pip install chi-drm
  ```python
 import chi
  ```
- 
+
  ### Tutorials
 
  Tutorials and more detailed explanations on how to use chi can be found in the [documentation's getting started](https://chi.readthedocs.io/en/latest/getting_started/index.html) section.
- 
+
 ## Citation
 
 If you use this software in your work, please cite it using the following metadata:
@@ -70,9 +70,11 @@ year = {2021}
 ```
 
 ## Contributing
-Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.
+There are lots of ways how you can contribute to Chi's development, and you are welcome to join in!
+For example, you can report problems or make feature requests on the [issues](https://github.com/DavAug/chi/issues) pages.
 
-Please make sure to update tests as appropriate.
+Similarly, if you would like to contribute documentation or code you can create and issue, and then provide a pull request for review.
+To facilitate contributions, we have written extensive [contribution guidelines](https://github.com/DavAug/chi/blob/main/CONTRIBUTING.md) to help you navigate the code.
 
 ## License
 [BSD-3-Clause](https://opensource.org/licenses/BSD-3-Clause)

chi/_log_pdfs.py

@@ -25,14 +25,14 @@ class HierarchicalLogLikelihood(object):
 
     .. math::
         \log p(\mathcal{D}, \Psi | \theta ) =
-            \sum _{ij} \log p(y_{ij} | \psi _{i} , t_{ij})
+            \sum _{i} \log p(\mathcal{D}_i | \psi _{i})
             + \sum _{i} \log p(\psi _{i}| \theta),
 
     where the first term is the sum over the log-likelihoods and the second
     term is the log-likelihood of the population model parameters.
-    :math:`\mathcal{D}=\{ (y_{ij}, t_{ij})\}` is the
-    data, where :math:`(y_{ij}, t_{ij})` is the :math:`j^{\mathrm{th}}`
-    measurement of log-likelihood :math:`i`. :math:`\Psi = \{ \psi_i\}`
+    :math:`\mathcal{D}=\{ \mathcal{D}_i\}` is the
+    data, where :math:`\mathcal{D}_i) = \{(y_{ij}, t_{ij})\}` denotes the
+    measurement from log-likelihood :math:`i`. :math:`\Psi = \{ \psi_i\}`
     denotes the parameters across the individual log-likelihoods.
 
     :param log_likelihoods: A list of log-likelihoods which are
@@ -645,7 +645,7 @@ class LogLikelihood(pints.LogPDF):
     defined by ``observations`` and ``times``
 
     .. math::
-        p(\psi | \mathcal{D}) = \sum _{j=1}
+        p(\mathcal{D} | \psi) = \sum _{j=1}
         \log p(y_j | \psi, t_j),
 
     where :math:`\mathcal{D} = \{(y_j , t_j)\}` denotes the measurements.
@@ -1157,17 +1157,17 @@ class LogPosterior(pints.LogPDF):
     an instance of a :class:`pints.LogPrior` of the same dimensionality
     as parameters in the log-likelihood.
 
-    Formally the log-posterior is given by the sum of the input log-likelihood
-    :math:`L(\psi | x^{\text{obs}})` and the input log-prior
-    :math:`\log p(\psi )` up to an additive constant
+    Formally the log-posterior is given by the sum of the log-likelihood,
+    :math:`\log p(\mathcal{D} | \psi)`, and the log-prior,
+    :math:`\log p(\psi )`, up to an additive constant
 
     .. math::
         \log p(\psi | \mathcal{D}) =
             \log p(\mathcal{D} | \psi) + \log p(\psi ) + \mathrm{constant},
 
     where :math:`\psi` are the parameters of the log-likelihood and
     :math:`\mathcal{D}` are the observed data. The additive constant
-    is the normalisation of the log-posterior and is in general not known.
+    is the normalisation of the log-posterior and is in general unknown.
 
     Extends :class:`pints.LogPDF`.
 

chi/_mechanistic_models.py

@@ -504,8 +504,9 @@ def simulate(self, parameters, times):
             values are returned.
         :type times: list, numpy.ndarray
 
-        :rtype: np.ndarray of shape (n_outputs, n_times) or
-            (n_times, n_outputs, n_parameters)
+        :rtype: np.ndarray of shape (n_outputs, n_times) or a Tuple of two
+            np.ndarray, the first of shape (n_outputs, n_times) and the second
+            of shape (n_times, n_outputs, n_parameters)
         """
         # Reset simulation
         self._simulator.reset()
@@ -622,7 +623,8 @@ def _add_dose_rate(self, compartment, drug_amount):
         # Set initial value to 0 and unit to unit of drug amount over unit of
         # time
         dose_rate.set_rhs(0)
-        dose_rate.set_unit(drug_amount.unit() / self.time_unit())
+        if drug_amount.unit():
+            dose_rate.set_unit(drug_amount.unit() / self.time_unit())
 
         # Add the dose rate to the rhs of the drug amount variable
         rhs = drug_amount.rhs()

chi/_predictive_models.py

@@ -263,7 +263,14 @@ def sample(
             individual = None
         # Check individual for individual predictive model
         else:
-            ids = self._posterior.individual
+            try:
+                ids = self._posterior.individual
+            except AttributeError:  # pragma: no cover
+                # Posterior only contains information about one individual.
+                # Hack to make this work
+                individual = 'some value'
+                ids = ['some value']
+
             # Get default individual
             if individual is None:
                 individual = str(ids.data[0])

docs/source/api/covariate_models.rst

@@ -14,8 +14,8 @@ from
 are used to describe the variability within a subpopulation, while covariate
 models are used to describe the cross-subpopulation variability.
 
-Functional classes
-------------------
+Classes
+-------
 
 - :class:`LinearCovariateModel`
 

docs/source/api/error_models.rst

@@ -9,8 +9,8 @@ Error Models
 Error models in chi_ model the deviations between experimental
 observations and the :class:`MechanisticModel` predictions.
 
-Functional classes
-------------------
+Classes
+-------
 
 - :class:`ConstantAndMultiplicativeGaussianErrorModel`
 - :class:`GaussianErrorModel`

docs/source/api/inference.rst

@@ -15,8 +15,8 @@ to easily explore different optimisation or sampling settings, e.g. using differ
 methods, fixing some parameters, or applying different transformations to the
 search space.
 
-Functional classes
-------------------
+Classes
+-------
 
 - :class:`OptimisationController`
 - :class:`SamplingController`

docs/source/api/log_pdfs.rst

@@ -10,8 +10,8 @@ Log-PDFs
 Log-PDFs in chi_ extend the log-pdfs provided in pints_ for the purpose of
 PKPD modelling.
 
-Functional classes
-------------------
+Classes
+-------
 
 - :class:`HierarchicalLogLikelihood`
 - :class:`HierarchicalLogPosterior`

docs/source/api/population_filters.rst

@@ -8,8 +8,8 @@ Population Filters
 
 Population filters in chi_ can be used for population filter inference.
 
-Functional classes
-------------------
+Classes
+-------
 
 - :class:`ComposedPopulationFilter`
 - :class:`GaussianFilter`

docs/source/api/population_models.rst

@@ -9,8 +9,8 @@ Population Models
 Population models in chi_ can be used to model the variation
 of mechanistic model parameters or error model parameters across individuals.
 
-Functional classes
-------------------
+Classes
+-------
 
 - :class:`ComposedPopulationModel`
 - :class:`CovariatePopulationModel`

docs/source/api/predictive_models.rst

@@ -12,8 +12,8 @@ generate synthetic measurements.
 Each predictive model consists of a :class:`MechanisticModel` and an
 :class:`ErrorModel`.
 
-Functional classes
-------------------
+Classes
+-------
 
 - :class:`PAMPredictiveModel`
 - :class:`PopulationPredictiveModel`

docs/source/api/problems.rst

@@ -13,8 +13,8 @@ individuals
 separately or as a population, the :class:`ProblemModellingController`
 has been implemented.
 
-Functional classes
-------------------
+Classes
+-------
 
 - :class:`ProblemModellingController`
 

docs/source/conf.py

@@ -37,6 +37,7 @@
     'sphinx.ext.mathjax',
     'sphinx.ext.napoleon',
     'sphinx.ext.viewcode',
+    'sphinx_copybutton'
 ]
 
 # Autodoc defaults
@@ -66,7 +67,7 @@
 
 # General information about the project.
 project = u'Chi'
-copyright = u'2022, David Augustin'
+copyright = u'2023, David Augustin'
 author = u'David Augustin'
 
 # The version info for the project you're documenting, acts as replacement for

docs/source/getting_started/code/2_mechanistic_model_1.py

@@ -0,0 +1,166 @@
+import argparse
+
+
+# Set up argument parsing, so plotting and exports can be disabled for
+# testing.
+parser = argparse.ArgumentParser(
+    description='Run example scripts for chi docs.',
+)
+parser.add_argument(
+    '--test',
+    action='store_true',
+    help='Run testing version of script which ignores plotting.',)
+
+# Parse!
+args = parser.parse_args()
+
+# Run testing verion of script
+if args.test:
+    #1
+    import chi
+    import numpy as np
+
+
+    class OneCompPKModel(chi.MechanisticModel):
+        def __init__(self):
+            super().__init__()
+
+        def simulate(self, parameters, times):
+            a0, ke, v = parameters
+            times = np.array(times)
+
+            c = a0 / v * np.exp(-ke * times)
+
+            output = np.empty(shape=(self.n_outputs(), len(times)))
+            output[0] = c
+
+            return output
+
+        def has_sensitivities(self):
+            # We will not implement sensitivities in this part of the tutorial, so
+            # the output of this method is always False
+            return False
+
+        def n_outputs(self):
+            return 1
+
+        def outputs(self):
+            return ['Drug concentration']
+
+        def n_parameters(self):
+            return 3
+
+        def parameters(self):
+            return ['Initial amount', 'Elimination rate', 'Volume of distribution']
+
+
+    import os
+    # 2
+    import plotly.graph_objects as go
+
+
+    # Define model
+    model = OneCompPKModel()
+
+    # Run simulation
+    times = np.linspace(start=0, stop=10, num=200)
+    parameters = [
+        10,        # Initial drug amount
+        1,         # Elimination rate
+        2,         # Volume of distribution
+    ]
+    simulation = model.simulate(parameters=parameters, times=times)[0]
+
+    # Plot drug concentration
+    fig = go.Figure()
+    fig.add_trace(go.Scatter(
+        x=times,
+        y=simulation,
+        mode='lines',
+    ))
+    fig.update_layout(
+        xaxis_title='Time',
+        yaxis_title='Drug concentration',
+        template='plotly_white'
+    )
+    # fig.show()
+
+
+    # directory = os.path.dirname(os.path.dirname(__file__))
+    # fig.write_html(directory + '/images/2_mechanistic_model_1.html')
+
+    # Exit script
+    exit()
+
+#1
+import chi
+import numpy as np
+
+
+class OneCompPKModel(chi.MechanisticModel):
+    def __init__(self):
+        super().__init__()
+
+    def simulate(self, parameters, times):
+        a0, ke, v = parameters
+        times = np.array(times)
+
+        c = a0 / v * np.exp(-ke * times)
+
+        output = np.empty(shape=(self.n_outputs(), len(times)))
+        output[0] = c
+
+        return output
+
+    def has_sensitivities(self):
+        # We will not implement sensitivities in this part of the tutorial, so
+        # the output of this method is always False
+        return False
+
+    def n_outputs(self):
+        return 1
+
+    def outputs(self):
+        return ['Drug concentration']
+
+    def n_parameters(self):
+        return 3
+
+    def parameters(self):
+        return ['Initial amount', 'Elimination rate', 'Volume of distribution']
+
+
+import os
+# 2
+import plotly.graph_objects as go
+
+
+# Define model
+model = OneCompPKModel()
+
+# Run simulation
+times = np.linspace(start=0, stop=10, num=200)
+parameters = [
+    10,        # Initial drug amount
+    1,         # Elimination rate
+    2,         # Volume of distribution
+]
+simulation = model.simulate(parameters=parameters, times=times)[0]
+
+# Plot drug concentration
+fig = go.Figure()
+fig.add_trace(go.Scatter(
+    x=times,
+    y=simulation,
+    mode='lines',
+))
+fig.update_layout(
+    xaxis_title='Time',
+    yaxis_title='Drug concentration',
+    template='plotly_white'
+)
+fig.show()
+
+
+directory = os.path.dirname(os.path.dirname(__file__))
+fig.write_html(directory + '/images/2_mechanistic_model_1.html')