Added 2CXM documentation and example

docs/examples/tissue/plot_two_cxm.py

@@ -0,0 +1,38 @@
+"""
+=============
+The Two Compartment Exchange Model
+=============
+
+Simulating tissue concentrations from two compartment models with different settings.
+"""
+
+import matplotlib.pyplot as plt
+
+# %%
+# Import necessary packages
+import numpy as np
+import osipi
+
+# %%
+# Generate Parker AIF with default settings.
+
+# Define time points in units of seconds - in this case we use a time
+# resolution of 1 sec and a total duration of 6 minutes.
+t = np.arange(0, 6 * 60, 1)
+
+# Create an AIF with default settings
+ca = osipi.aif_parker(t)
+
+# %%
+# Plot the tissue concentrations for an extracellular volume fraction
+# of 0.2, plasma volume fraction of 0.3, extraction fraction of 0.15
+# and flow rate of 0.2 ml/min
+E = 0.15  # Extraction fraction
+Fp = 0.2  # Flow rate in ml/min
+Ve = 0.2  # Extracellular volume fraction
+Vp = 0.3  # Plasma volume fraction
+ct = osipi.two_cxm(t, ca, E=E, Fp=Fp, Ve=Ve, Vp=Vp)
+plt.plot(t, ct, "b-", label=f"E = {E}, Fp = {Fp}, Ve = {Ve}, Vp = {Vp}")
+plt.xlabel("Time (sec)")
+plt.ylabel("Tissue concentration (mM)")
+plt.show()

docs/references/models/tissue_models/2cxm.md

@@ -0,0 +1,16 @@
+# osipi.Two Compartment Exchange Model
+
+::: osipi.two_cxm
+
+## Example using `osipi.two_cxm`
+
+<figure class="mkd-glr-thumbcontainer" tooltip="Simulating tissue concentrations from two compartment exchange model with different settings.">
+    <img alt="The Two Compartment Exchange Model" src="..\..\..\..\generated\gallery\tissue\images\thumb\mkd_glr_plot_two_cxm_thumb.png" />
+    <figcaption class="caption">
+        <span class="caption-text">
+            <a class="reference internal" href="..\..\..\..\generated\gallery\tissue\plot_two_cxm">
+                <span class="std std-ref">The Two Compartment Exchange Model</span>
+            </a>
+        </span>
+    </figcaption>
+</figure>

docs/references/models/tissue_models/index.md

@@ -1,3 +1,4 @@
 
 - [tofts](tofts.md)
 - [extended_tofts](extended_tofts.md)
+- [two_cxm](2cxm.md)

mkdocs.yml

@@ -75,6 +75,7 @@ nav:
               - references/models/tissue_models/index.md
               - osipi.tofts: references/models/tissue_models/tofts.md
               - osipi.extended_tofts: references/models/tissue_models/extended_tofts.md
+              - osipi.two_compartment_exchange: references/models/tissue_models/2cxm.md
 
   - Examples: generated/gallery
 

src/osipi/_tissue.py

@@ -363,6 +363,45 @@ def two_cxm(
         discretization_method (str, optional): Defines the discretization method. Options include
             – 'conv': Numerical convolution (default) [OSIPI code G.DI1.001]
             – 'exp': Exponential convolution [OSIPI code G.DI1.006]
+
+    Returns:
+        np.ndarray: Tissue concentrations in mM for each time point in t.
+
+    See Also:
+        `tofts`, `extended_tofts`
+
+    References:
+        - Lexicon url:
+            https://osipi.github.io/OSIPI_CAPLEX/perfusionModels/#2CXM
+        - Lexicon code: M.IC1.009
+        - OSIPI name: Two Compartment Model
+        - Adapted from contributions by: LEK_UoEdinburgh_UK, ST_USyd_AUS, MJT_UoEdinburgh_UK
+
+    Example:
+
+            Create an array of time points covering 6 min in steps of 1 sec,
+            calculate the Parker AIF at these time points, calculate tissue concentrations
+            using the 2CX model and plot the results.
+
+            Import packages:
+
+            >>> import matplotlib.pyplot as plt
+            >>> import osipi
+
+            Calculate AIF:
+
+            >>> t = np.arange(0, 6 * 60, 1)
+            >>> ca = osipi.aif_parker(t)
+
+            Calculate tissue concentrations and plot:
+
+            >>> E = 0.15  # in units of mL/min/100g
+            >>> Fp = 0.2  # in units of mL/min/100g
+            >>> Ve = 0.2  # takes values from 0 to 1
+            >>> Vp = 0.3  # takes values from 0 to 1
+            >>> ct = osipi.two_cxm(t, ca, E, Fp, Ve, Vp)
+            >>> plt.plot(t, ca, "r", t, ct, "b")
+
     """
 
     if not np.allclose(np.diff(t), np.diff(t)[0]):

tests/test_tissue.py

@@ -148,7 +148,7 @@ def test_tissue_2compartment_model():
     t = np.arange(0, 6 * 60, 1)
     ca = osipi.aif_parker(t)
     ct = osipi.two_cxm(t, ca, E=0.15, Fp=0.2, Ve=0.2, Vp=0.3)
-    assert math.isclose(np.trapz(ct, t)/np.trapz(ca, t), 0.2 + 0.3, abs_tol=1e-1)
+    assert math.isclose(np.trapz(ct, t) / np.trapz(ca, t), 0.2 + 0.3, abs_tol=1e-1)
 
 
 if __name__ == "__main__":