rsmodel 0.1.0__tar.gz

rsmodel-0.1.0/.gitignore

@@ -0,0 +1,25 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+.venv/
+venv/
+
+# Tooling caches
+.ruff_cache/
+.pytest_cache/
+.mypy_cache/
+.ipynb_checkpoints/
+
+# marimo
+__marimo__/
+
+# Generated output
+figures/
+build/
+
+# OS / editor
+.DS_Store
+.vscode/
+.idea/

rsmodel-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Björn S. Rüffer and Michael Schönlein
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

rsmodel-0.1.0/PKG-INFO

@@ -0,0 +1,115 @@
+Metadata-Version: 2.5
+Name: rsmodel
+Version: 0.1.0
+Summary: A resilience-symptom (RS) dynamical model of depression
+Project-URL: Homepage, https://rsmodel.org
+Project-URL: Playground, https://rsmodel.org
+Project-URL: Repository, https://github.com/bjoseru/rsmodel
+Project-URL: Issues, https://github.com/bjoseru/rsmodel/issues
+Project-URL: Changelog, https://github.com/bjoseru/rsmodel/blob/main/CHANGELOG.md
+Author: Björn S. Rüffer, Michael Schönlein
+Maintainer-email: "Björn S. Rüffer" <bjoern.rueffer@uni-weimar.de>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: depression,dynamical-systems,mathematical-psychology,ordinary-differential-equations,resilience,stability-analysis
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
+Requires-Python: >=3.11
+Requires-Dist: matplotlib>=3.8
+Requires-Dist: numpy>=1.24
+Requires-Dist: scipy>=1.11
+Requires-Dist: sympy>=1.12
+Description-Content-Type: text/markdown
+
+# rsmodel
+
+A qualitative, two-state dynamical model of the interaction between depressive symptoms
+and psychological resilience under external adversity — the **resilience–symptom (RS)
+model**:
+
+```
+dr/dt = (-s + (1-s)*r) * (1-r) * r
+ds/dt = (e*(1+s-r) - s*r) * (1-s) * s
+```
+
+where `r ∈ [0,1]` is the resilience level (0 = depleted, 1 = full), `s ∈ [0,1]` the
+depressive symptom level (0 = healthy, 1 = severe), and `e ∈ [0,1]` an external adverse
+input. The unit square is positively invariant.
+
+This is the reference implementation for
+
+> Björn S. Rüffer & Michael Schönlein, *A mathematical model for depression and
+> resilience*.
+
+**Interactive playground, no installation required: <https://rsmodel.org>**
+
+> **Warning**
+> Neither the model nor its time scale is calibrated against clinical data. This is a
+> qualitative model, not a quantitative one, and it does not represent the effects of
+> medication or of any other intervention. It is not a diagnostic or clinical tool.
+
+## Install
+
+```bash
+uv add rsmodel
+```
+
+## Usage
+
+```python
+from rsmodel import RSModel, Patient
+from rsmodel.utils import get_predefined_scenarios
+
+model = RSModel()
+model.rhs(_r=0.84, _s=0.67, _e=0.3)         # -> (dr/dt, ds/dt)
+model.plot_equilibria()                      # equilibrium manifold over e ∈ [0,1]
+model.plot_streamlines(external_input=0.2)   # phase portrait at constant e
+
+patient = Patient(s0=0.67, r0=0.84)
+patient.get_stimulus_response(get_predefined_scenarios()["multiple adverse events"])
+```
+
+Symbolic analysis (`sympy`):
+
+```python
+from rsmodel.analysis import compute_jacobian, analyze_corner_equilibria
+
+J = compute_jacobian(RSModel())                     # symbolic 2x2 Jacobian
+analyze_corner_equilibria(RSModel(), e_value=0.5)   # stability of the four corners
+```
+
+`RS2Model` is the variant with the `3*s*r` coupling term used for comparison in the paper.
+
+## Interactive notebooks
+
+The repository ships three [marimo](https://marimo.io) notebooks — an interactive
+playground (also published at <https://rsmodel.org>), the full symbolic analysis, and a
+script that regenerates every figure in the manuscript. See
+<https://github.com/bjoseru/rsmodel> for details.
+
+## Citation
+
+Cite the paper and the archived software:
+
+```bibtex
+@misc{rueffer_schoenlein_rsmodel_software,
+  author    = {R{\"u}ffer, Bj{\"o}rn S. and Sch{\"o}nlein, Michael},
+  title     = {{rsmodel}: a resilience--symptom dynamical model of depression},
+  year      = {2026},
+  publisher = {Zenodo},
+  doi       = {10.5281/zenodo.XXXXXXX},
+  url       = {https://rsmodel.org}
+}
+```
+
+## License
+
+MIT

rsmodel-0.1.0/README.md

@@ -0,0 +1,84 @@
+# rsmodel
+
+A qualitative, two-state dynamical model of the interaction between depressive symptoms
+and psychological resilience under external adversity — the **resilience–symptom (RS)
+model**:
+
+```
+dr/dt = (-s + (1-s)*r) * (1-r) * r
+ds/dt = (e*(1+s-r) - s*r) * (1-s) * s
+```
+
+where `r ∈ [0,1]` is the resilience level (0 = depleted, 1 = full), `s ∈ [0,1]` the
+depressive symptom level (0 = healthy, 1 = severe), and `e ∈ [0,1]` an external adverse
+input. The unit square is positively invariant.
+
+This is the reference implementation for
+
+> Björn S. Rüffer & Michael Schönlein, *A mathematical model for depression and
+> resilience*.
+
+**Interactive playground, no installation required: <https://rsmodel.org>**
+
+> **Warning**
+> Neither the model nor its time scale is calibrated against clinical data. This is a
+> qualitative model, not a quantitative one, and it does not represent the effects of
+> medication or of any other intervention. It is not a diagnostic or clinical tool.
+
+## Install
+
+```bash
+uv add rsmodel
+```
+
+## Usage
+
+```python
+from rsmodel import RSModel, Patient
+from rsmodel.utils import get_predefined_scenarios
+
+model = RSModel()
+model.rhs(_r=0.84, _s=0.67, _e=0.3)         # -> (dr/dt, ds/dt)
+model.plot_equilibria()                      # equilibrium manifold over e ∈ [0,1]
+model.plot_streamlines(external_input=0.2)   # phase portrait at constant e
+
+patient = Patient(s0=0.67, r0=0.84)
+patient.get_stimulus_response(get_predefined_scenarios()["multiple adverse events"])
+```
+
+Symbolic analysis (`sympy`):
+
+```python
+from rsmodel.analysis import compute_jacobian, analyze_corner_equilibria
+
+J = compute_jacobian(RSModel())                     # symbolic 2x2 Jacobian
+analyze_corner_equilibria(RSModel(), e_value=0.5)   # stability of the four corners
+```
+
+`RS2Model` is the variant with the `3*s*r` coupling term used for comparison in the paper.
+
+## Interactive notebooks
+
+The repository ships three [marimo](https://marimo.io) notebooks — an interactive
+playground (also published at <https://rsmodel.org>), the full symbolic analysis, and a
+script that regenerates every figure in the manuscript. See
+<https://github.com/bjoseru/rsmodel> for details.
+
+## Citation
+
+Cite the paper and the archived software:
+
+```bibtex
+@misc{rueffer_schoenlein_rsmodel_software,
+  author    = {R{\"u}ffer, Bj{\"o}rn S. and Sch{\"o}nlein, Michael},
+  title     = {{rsmodel}: a resilience--symptom dynamical model of depression},
+  year      = {2026},
+  publisher = {Zenodo},
+  doi       = {10.5281/zenodo.XXXXXXX},
+  url       = {https://rsmodel.org}
+}
+```
+
+## License
+
+MIT

rsmodel-0.1.0/pyproject.toml

@@ -0,0 +1,61 @@
+[project]
+name = "rsmodel"
+description = "A resilience-symptom (RS) dynamical model of depression"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "Björn S. Rüffer" },
+    { name = "Michael Schönlein" },
+]
+maintainers = [
+    { name = "Björn S. Rüffer", email = "bjoern.rueffer@uni-weimar.de" },
+]
+keywords = [
+    "depression",
+    "resilience",
+    "dynamical-systems",
+    "mathematical-psychology",
+    "ordinary-differential-equations",
+    "stability-analysis",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Mathematics",
+    "Topic :: Scientific/Engineering :: Medical Science Apps.",
+]
+dependencies = [
+    "matplotlib>=3.8",
+    "numpy>=1.24",
+    "scipy>=1.11",
+    "sympy>=1.12",
+]
+dynamic = ["version"]
+
+[project.urls]
+Homepage = "https://rsmodel.org"
+Playground = "https://rsmodel.org"
+Repository = "https://github.com/bjoseru/rsmodel"
+Issues = "https://github.com/bjoseru/rsmodel/issues"
+Changelog = "https://github.com/bjoseru/rsmodel/blob/main/CHANGELOG.md"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.version]
+path = "rsmodel/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["rsmodel"]
+
+[tool.hatch.build.targets.sdist]
+include = ["rsmodel", "README.md", "LICENSE"]

rsmodel-0.1.0/rsmodel/__init__.py

@@ -0,0 +1,86 @@
+"""RS Model: A Resilience-Symptom model for depression dynamics.
+
+This package implements the mathematical model described in:
+Rüffer, B. S., & Schönlein, M. (2025). A mathematical model for depression
+and resilience.
+
+The model consists of two coupled first-order differential equations:
+    dr/dt = (-s + (1-s)*r) * (1-r) * r
+    ds/dt = (e*(1+s-r) - s*r) * (1-s) * s
+
+where:
+    r ∈ [0,1]: resilience level
+    s ∈ [0,1]: depression symptom level
+    e ∈ [0,1]: external adverse input
+
+Basic usage:
+    >>> from rsmodel import RSModel, Patient
+    >>> model = RSModel()
+    >>> patient = Patient(s0=0.67, r0=0.84)
+    >>> ax = patient.get_stimulus_response(external_input=0.5, t_final=20)
+
+For predefined scenarios:
+    >>> from rsmodel.utils import get_predefined_scenarios
+    >>> scenarios = get_predefined_scenarios()
+    >>> ax = patient.get_stimulus_response(scenarios["from bad to worse then better"])
+
+For mathematical analysis:
+    >>> from rsmodel.analysis import compute_jacobian, analyze_corner_equilibria
+    >>> J = compute_jacobian(model)
+    >>> corner_analysis = analyze_corner_equilibria(model, e_value=0.5)
+"""
+
+__version__ = "0.1.0"
+__author__ = "Björn S. Rüffer & Michael Schönlein"
+__license__ = "MIT"
+
+# Core classes
+# Analysis functions
+from .analysis import (
+    analyze_corner_equilibria,
+    classify_equilibrium_stability,
+    compute_jacobian,
+    compute_monotonicity_conditions,
+    evaluate_jacobian_at_equilibrium,
+    find_interior_equilibrium_intersection,
+    get_eigenvalues,
+    lyapunov_function_derivative,
+    plot_eigenvalue_evolution,
+    verify_lyapunov_function,
+)
+from .core import Patient, RS2Model, RSModel
+
+# Utility functions
+from .utils import (
+    create_custom_stimulus,
+    from_bad_to_less_bad_to_not_great,
+    from_bad_to_worse_then_better,
+    get_predefined_scenarios,
+    multiple_adverse_events,
+    sample_and_hold,
+)
+
+__all__ = [
+    # Core
+    "RSModel",
+    "RS2Model",
+    "Patient",
+    # Analysis
+    "compute_jacobian",
+    "evaluate_jacobian_at_equilibrium",
+    "get_eigenvalues",
+    "classify_equilibrium_stability",
+    "analyze_corner_equilibria",
+    "lyapunov_function_derivative",
+    "verify_lyapunov_function",
+    "plot_eigenvalue_evolution",
+    "compute_monotonicity_conditions",
+    "find_interior_equilibrium_intersection",
+    # Utils
+    "from_bad_to_worse_then_better",
+    "multiple_adverse_events",
+    "from_bad_to_less_bad_to_not_great",
+    "get_predefined_scenarios",
+    "create_custom_stimulus",
+    "sample_and_hold",
+]

rsmodel-0.1.0/rsmodel/analysis.py

@@ -0,0 +1,306 @@
+"""Mathematical analysis tools for the RS model.
+
+This module provides functions for:
+- Computing and analyzing equilibria
+- Jacobian and stability analysis
+- Lyapunov function verification
+- Eigenvalue analysis
+"""
+
+from typing import Dict, List
+
+import matplotlib.pyplot as plt
+import numpy as np
+import sympy
+
+from .core import RSModel
+
+
+def compute_jacobian(model: RSModel, state_vars=None) -> sympy.Matrix:
+    """Compute the Jacobian matrix of the RS model.
+
+    Args:
+        model: RSModel instance
+        state_vars: State variables (default: [model.r, model.s])
+
+    Returns:
+        Jacobian matrix as sympy.Matrix
+    """
+    if state_vars is None:
+        state_vars = sympy.Matrix([model.r, model.s])
+
+    f = sympy.Matrix([model.dr, model.ds])
+    return f.jacobian(state_vars)
+
+
+def evaluate_jacobian_at_equilibrium(
+    model: RSModel, equilibrium: Dict, e_value: float = None
+) -> sympy.Matrix:
+    """Evaluate Jacobian at a specific equilibrium point.
+
+    Args:
+        model: RSModel instance
+        equilibrium: Dictionary with equilibrium point {r: val, s: val}
+        e_value: Value of e if equilibrium is parameterized
+
+    Returns:
+        Jacobian matrix evaluated at the equilibrium
+    """
+    J = compute_jacobian(model)
+    J_eq = J.subs(equilibrium)
+
+    if e_value is not None:
+        J_eq = J_eq.subs(model.e, e_value)
+
+    return J_eq
+
+
+def get_eigenvalues(matrix: sympy.Matrix) -> List:
+    """Get eigenvalues of a symbolic matrix.
+
+    Args:
+        matrix: Sympy matrix
+
+    Returns:
+        List of eigenvalues (may be symbolic)
+    """
+    return list(matrix.eigenvals().keys())
+
+
+def classify_equilibrium_stability(
+    model: RSModel, equilibrium: Dict, e_value: float = None
+) -> str:
+    """Classify stability of an equilibrium point.
+
+    Args:
+        model: RSModel instance
+        equilibrium: Equilibrium point dictionary
+        e_value: Value of e if needed
+
+    Returns:
+        String classification: 'stable', 'unstable', 'saddle', or 'undetermined'
+    """
+    J = evaluate_jacobian_at_equilibrium(model, equilibrium, e_value)
+    eigenvals = get_eigenvalues(J)
+
+    # Evaluate eigenvalues numerically if possible
+    try:
+        eigenvals_numeric = [complex(ev.evalf()) for ev in eigenvals]
+        real_parts = [ev.real for ev in eigenvals_numeric]
+
+        if all(rp < 0 for rp in real_parts):
+            return "stable"
+        elif all(rp > 0 for rp in real_parts):
+            return "unstable"
+        else:
+            return "saddle"
+    except:
+        return "undetermined"
+
+
+def analyze_corner_equilibria(model: RSModel, e_value: float = 0.5) -> Dict:
+    """Analyze stability of the four corner equilibria.
+
+    The corners are: (r,s) ∈ {(0,0), (1,0), (0,1), (1,1)}
+
+    Args:
+        model: RSModel instance
+        e_value: Value of external input e
+
+    Returns:
+        Dictionary with corner analysis results
+    """
+    corners = [
+        {model.r: 0, model.s: 0},  # p1
+        {model.r: 1, model.s: 0},  # p2
+        {model.r: 1, model.s: 1},  # p3
+        {model.r: 0, model.s: 1},  # p4
+    ]
+
+    results = {}
+    for i, corner in enumerate(corners, 1):
+        J = evaluate_jacobian_at_equilibrium(model, corner, e_value)
+        eigenvals = get_eigenvalues(J)
+        stability = classify_equilibrium_stability(model, corner, e_value)
+
+        results[f"p{i}"] = {
+            "equilibrium": corner,
+            "jacobian": J,
+            "eigenvalues": eigenvals,
+            "stability": stability,
+        }
+
+    return results
+
+
+def lyapunov_function_derivative(model: RSModel, V_expr) -> sympy.Expr:
+    """Compute time derivative of a Lyapunov function candidate.
+
+    Args:
+        model: RSModel instance
+        V_expr: Lyapunov function V(r,s) as sympy expression
+
+    Returns:
+        dV/dt = ∇V · f as sympy expression
+    """
+    state_vars = sympy.Matrix([model.r, model.s])
+    f = sympy.Matrix([model.dr, model.ds])
+
+    grad_V = sympy.Matrix([V_expr]).jacobian(state_vars)
+    dV = (grad_V * f)[0]
+
+    return dV
+
+
+def verify_lyapunov_function(model: RSModel, V_expr, equilibrium: Dict = None) -> Dict:
+    """Verify a Lyapunov function for stability analysis.
+
+    Args:
+        model: RSModel instance
+        V_expr: Lyapunov function V(r,s)
+        equilibrium: Equilibrium point (if None, checks general negativity)
+
+    Returns:
+        Dictionary with verification results
+    """
+    dV = lyapunov_function_derivative(model, V_expr)
+    dV_expanded = dV.expand()
+
+    results = {
+        "V": V_expr,
+        "dV": dV,
+        "dV_expanded": dV_expanded,
+        "dV_collected": dV_expanded.collect(model.s),
+    }
+
+    if equilibrium is not None:
+        dV_at_eq = dV.subs(equilibrium)
+        results["dV_at_equilibrium"] = dV_at_eq
+
+    return results
+
+
+def plot_eigenvalue_evolution(
+    model: RSModel,
+    equilibrium_parameterized: Dict,
+    e_range: np.ndarray = None,
+    title: str = "Eigenvalue evolution",
+):
+    """Plot how eigenvalues change as parameter e varies.
+
+    Args:
+        model: RSModel instance
+        equilibrium_parameterized: Equilibrium point depending on e
+        e_range: Range of e values (default: linspace(0,1,100))
+        title: Plot title
+
+    Returns:
+        Matplotlib axes object
+    """
+    if e_range is None:
+        e_range = np.linspace(0.001, 0.999, 100)
+
+    J = evaluate_jacobian_at_equilibrium(model, equilibrium_parameterized)
+    eigenvals = get_eigenvalues(J)
+
+    # Evaluate eigenvalues over e range
+    eigenval_data = {i: [] for i in range(len(eigenvals))}
+
+    for e_val in e_range:
+        for i, ev in enumerate(eigenvals):
+            try:
+                val = complex(ev.subs(model.e, e_val).evalf())
+                eigenval_data[i].append(val)
+            except:
+                eigenval_data[i].append(np.nan)
+
+    # Plot
+    fig, (ax1, ax2) = plt.subplots(1, 2, figsize=(12, 5))
+
+    # Real parts
+    for i, vals in eigenval_data.items():
+        real_parts = [v.real if not np.isnan(v) else np.nan for v in vals]
+        ax1.plot(e_range, real_parts, label=f"λ{i + 1}")
+
+    ax1.axhline(y=0, color="k", linestyle="--", linewidth=0.5)
+    ax1.set_xlabel("External input $e$")
+    ax1.set_ylabel("Real part")
+    ax1.set_title(f"{title} - Real parts")
+    ax1.legend()
+    ax1.grid(True)
+
+    # Imaginary parts
+    for i, vals in eigenval_data.items():
+        imag_parts = [v.imag if not np.isnan(v) else np.nan for v in vals]
+        ax2.plot(e_range, imag_parts, label=f"λ{i + 1}")
+
+    ax2.axhline(y=0, color="k", linestyle="--", linewidth=0.5)
+    ax2.set_xlabel("External input $e$")
+    ax2.set_ylabel("Imaginary part")
+    ax2.set_title(f"{title} - Imaginary parts")
+    ax2.legend()
+    ax2.grid(True)
+
+    plt.tight_layout()
+    return ax1
+
+
+def compute_monotonicity_conditions(model: RSModel) -> Dict:
+    """Compute monotonicity conditions for the RS model.
+
+    Analyzes:
+    - ∂f₁/∂s (effect of symptoms on resilience dynamics)
+    - ∂f₂/∂r (effect of resilience on symptom dynamics)
+    - ∂f₁/∂e (direct effect of input on resilience)
+    - ∂f₂/∂e (direct effect of input on symptoms)
+
+    Returns:
+        Dictionary with partial derivatives and their analysis
+    """
+    results = {
+        "df1_ds": model.dr.diff(model.s),  # negative: symptoms harm resilience
+        "df2_dr": model.ds.diff(model.r),  # negative: resilience reduces symptoms
+        "df1_de": model.dr.diff(model.e),  # direct input effect on resilience
+        "df2_de": model.ds.diff(model.e),  # direct input effect on symptoms
+    }
+
+    # Simplify
+    for key in results:
+        results[key] = results[key].simplify()
+
+    return results
+
+
+def find_interior_equilibrium_intersection(model: RSModel) -> Dict:
+    """Find the interior equilibrium (intersection of nullclines).
+
+    Solves for the point where both dr/dt = 0 and ds/dt = 0 in the interior
+    of [0,1]², parameterized by e.
+
+    Returns:
+        Dictionary with symbolic solutions
+    """
+    # Nullclines: dr=0 gives r/(1+r), ds=0 gives (1-r)/(r/e-1)
+    # Find intersection
+    r, e = model.r, model.e
+
+    # From dr=0 (non-trivial): s = r/(1+r)
+    # From ds=0 (non-trivial): s = (1-r)/(r/e-1)
+    # Set equal and solve
+
+    s_from_dr = r / (1 + r)
+    s_from_ds = (1 - r) / (r / e - 1)
+
+    # Solve for r
+    eq = s_from_dr - s_from_ds
+    r_solution = sympy.solve(eq, r)
+
+    results = {}
+    for i, r_val in enumerate(r_solution):
+        s_val = s_from_dr.subs(r, r_val)
+        results[f"interior_eq_{i}"] = {
+            "r": r_val,
+            "s": s_val,
+        }
+
+    return results

rsmodel-0.1.0/rsmodel/core.py

@@ -0,0 +1,364 @@
+"""Core classes for the Resilience-Symptom (RS) model of depression.
+
+This module implements the mathematical model described in:
+Rüffer, B. S., & Schönlein, M. (2025). A mathematical model for depression
+and resilience.
+
+The model consists of two coupled first-order differential equations describing:
+- r: Resilience level (0 = depleted, 1 = full resilience)
+- s: Depression symptom level (0 = healthy, 1 = severe depression)
+- e: External adverse input/stressor (0 = no stress; larger values = more severe adversity)
+"""
+
+from typing import Callable, Tuple, Union
+
+import matplotlib.pyplot as plt
+import numpy as np
+import sympy
+from scipy.integrate import solve_ivp
+
+
+class RSModel:
+    """Resilience-Symptom model for depression dynamics.
+
+    The model is defined by the system of differential equations:
+        dr/dt = (-s + (1-s)*r) * (1-r) * r
+        ds/dt = (e*(1+s-r) - s*r) * (1-s) * s
+
+    where:
+        r ∈ [0,1]: resilience level
+        s ∈ [0,1]: depression symptom level
+        e ≥ 0: external adverse input
+
+    The domain [0,1]² is positively invariant.
+
+    Attributes:
+        e, r, s, t: Symbolic variables (sympy.Symbol)
+        dr: Symbolic expression for resilience dynamics
+        ds: Symbolic expression for symptom dynamics
+        model_name: String identifier for this model variant
+    """
+
+    # Symbolic variables (class-level, shared by all instances)
+    e, r, s, t = sympy.symbols("e r s t")
+
+    # Model equations (can be overridden in subclasses)
+    dr = (-s + (1 - s) * r) * (1 - r) * r
+    ds = (e * (1 + s - r) - s * r) * (1 - s) * s
+    model_name = "RS model"
+
+    def __init__(self):
+        """Initialize the RS model.
+
+        Subclasses can override the equations by redefining dr, ds, and model_name
+        in their __init__ method.
+        """
+        pass
+
+    def rhs(self, _r: float, _s: float, _e: float) -> Tuple[float, float]:
+        """Evaluate the right-hand side of the ODE system.
+
+        Args:
+            _r: Current resilience level
+            _s: Current symptom level
+            _e: Current external input
+
+        Returns:
+            Tuple (dr/dt, ds/dt) evaluated at the given state
+        """
+        subs = {self.r: _r, self.s: _s, self.e: _e}
+        return float(self.dr.subs(subs)), float(self.ds.subs(subs))
+
+    def latex_dr(self) -> str:
+        """Return LaTeX representation of the resilience dynamics equation."""
+        return r"\dot r = " + sympy.latex(self.dr)
+
+    def latex_ds(self) -> str:
+        """Return LaTeX representation of the symptom dynamics equation."""
+        return r"\dot s = " + sympy.latex(self.ds)
+
+    def __str__(self) -> str:
+        """String representation showing the model equations."""
+        return f"""`{self.model_name}` defined by
+  $${self.latex_dr()}$$
+and
+  $${self.latex_ds()}.$$"""
+
+    def get_equilibria(self):
+        """Compute equilibrium points of the system.
+
+        Returns:
+            List of equilibria as tuples (r_value, s_value).
+            Values may be symbolic expressions depending on parameter e.
+        """
+        return sympy.solve([self.dr, self.ds], [self.r, self.s])
+
+    def plot_equilibria(self, color: str = "#c00", samples: int = 500):
+        """Plot the equilibrium manifold in (r,s) space.
+
+        Creates a plot showing all equilibrium points as e varies from 0 to 1.
+        Some equilibria are fixed points (corners), others form curves.
+
+        Args:
+            color: Color for the equilibrium curve
+            samples: Number of samples for parameterized curves
+
+        Returns:
+            Matplotlib axes object with the equilibrium plot
+        """
+        pts_to_plot = []
+        e_range = np.linspace(1e-3, 1 - 1e-3, samples)
+
+        for r_val, s_val in self.get_equilibria():
+            params = r_val.free_symbols.union(s_val.free_symbols)
+
+            if len(params) == 0:
+                # Fixed point (independent of e)
+                pts_to_plot.append((float(r_val), float(s_val)))
+
+            elif len(params) == 1:
+                # Curve parameterized by e
+                try:
+                    e = params.pop()
+                    r_range = [r_val.subs({e: float(_)}) for _ in e_range]
+                    s_range = [s_val.subs({e: float(_)}) for _ in e_range]
+                    plt.plot(r_range, s_range, color=color)
+                except RuntimeWarning:
+                    pass  # Ignore issues like complex values, infinity
+
+        # Plot fixed points
+        if pts_to_plot:
+            try:
+                plt.plot(*zip(*pts_to_plot, strict=False), "o", color=color)
+            except RuntimeWarning:
+                pass
+
+        plt.title(
+            rf'Location of equilibria of "{self.model_name}" (with constant $e\in[0,1]$)'
+        )
+        plt.xlabel("Resilience $r$")
+        plt.ylabel("Symptom $s$")
+        plt.grid("both")
+
+        ax = plt.gca()
+        ax.set_xlim(-1e-2, 1 + 1e-2)
+        ax.set_ylim(-1e-2, 1 + 1e-2)
+        ax.spines[["top", "right", "bottom", "left"]].set_visible(False)
+
+        return ax
+
+    def plot_streamlines(self, external_input: float = 0.0, cmap: str = "inferno"):
+        """Create a streamline (phase portrait) plot for constant input.
+
+        Shows the vector field and flow lines in the (r,s) phase space
+        for a fixed value of the external input e.
+
+        Args:
+            external_input: Fixed value of e for the plot
+            cmap: Matplotlib colormap for the streamlines
+
+        Returns:
+            Matplotlib axes object with the streamline plot
+        """
+        R, S = np.mgrid[0:1:30j, 0:1:30j]
+
+        def to_float(tpl):
+            """Cast a vector into floats."""
+            return tuple(map(float, tpl))
+
+        DR, DS = np.vectorize(lambda r, s: to_float(self.rhs(r, s, external_input)))(
+            R, S
+        )
+
+        speed = np.sqrt(DR**2 + DS**2)
+
+        fig, ax = plt.subplots()
+
+        strm = ax.streamplot(
+            R.T,
+            S.T,
+            DR.T,
+            DS.T,
+            color=speed.T,
+            linewidth=2,
+            cmap=cmap,
+        )
+
+        fig.colorbar(strm.lines)
+        plt.xlabel("Resilience $r$")
+        plt.ylabel("Symptom $s$")
+        plt.title(f"Streamlines for {self.model_name} with $e={external_input:4.2f}$")
+
+        plt.grid(True)
+        ax.spines[["top", "right", "left", "bottom"]].set_visible(False)
+        ax.set_xlim([0, 1])
+        ax.set_ylim([0, 1])
+
+        return ax
+
+
+class RS2Model(RSModel):
+    """Modified version of the RS model with altered symptom dynamics.
+
+    This variant changes the coefficient in the s*r term from 1 to 3:
+        ds/dt = (e*(1+s-r) - 3*s*r) * (1-s) * s
+
+    while keeping the resilience dynamics unchanged.
+    """
+
+    def __init__(self):
+        """Initialize the modified RS model."""
+        e, s, r = self.e, self.s, self.r
+        # Modified symptom dynamics with stronger resilience effect
+        self.ds = (e * (1 + s - r) - 3 * s * r) * (1 - s) * s
+        self.dr = (-s + (1 - s) * r) * (1 - r) * r
+        self.model_name = "Modified RS model"
+
+
+class Patient:
+    """Individual patient with initial conditions and trajectory tracking.
+
+    A Patient represents an individual experiencing depression dynamics
+    according to an RS model. The patient has initial symptom and resilience
+    levels and can be simulated under various external input scenarios.
+
+    Attributes:
+        r0: Initial resilience level (default: 0.84)
+        s0: Initial symptom level (default: 0.67)
+        name: Optional patient identifier
+        model: The RSModel instance governing dynamics (default: RSModel())
+        solution: OdeResult from scipy after simulation (set by get_stimulus_response)
+    """
+
+    def __init__(
+        self,
+        r0: float = 0.84,
+        s0: float = 0.67,
+        name: str = None,
+        model: RSModel = None,
+    ):
+        """Initialize a patient with initial conditions.
+
+        Args:
+            r0: Initial resilience level in [0,1]
+            s0: Initial depression symptom level in [0,1]
+            name: Optional name/identifier for this patient
+            model: RSModel instance (defaults to standard RSModel())
+        """
+        self.r0 = r0
+        self.s0 = s0
+        self.name = name
+        self.model = model if model is not None else RSModel()
+        self.solution = None
+
+    def __str__(self) -> str:
+        """String representation of the patient."""
+        if self.name is None:
+            return (
+                f"A patient with initial condition s={self.s0:.2f} & "
+                f"r={self.r0:.2f} based on {self.model}"
+            )
+        else:
+            return (
+                f"{self.name} with initial condition s={self.s0:.2f} & "
+                f"r={self.r0:.2f} based on {self.model}"
+            )
+
+    def get_stimulus_response(
+        self,
+        external_input: Union[float, Callable[[float], float]] = 0,
+        t_0: float = 0,
+        t_final: float = 20,
+        color_s: str = "blue",
+        color_r: str = "green",
+        color_e: str = "red",
+        **kwargs,
+    ):
+        """Simulate patient response to external input and create plot.
+
+        Solves the ODE system with the given external input function
+        and plots the time evolution of all three variables (s, r, e).
+
+        Args:
+            external_input: Either a constant value or a function e(t)
+            t_0: Initial time
+            t_final: Final time
+            color_s: Color for symptom trajectory
+            color_r: Color for resilience trajectory
+            color_e: Color for input signal
+            **kwargs: Additional arguments passed to plt.plot()
+
+        Returns:
+            Matplotlib axes object with the stimulus-response plot
+        """
+        # Convert constant input to function if needed
+        if not callable(external_input):
+            _const = external_input
+            external_input = lambda t: _const
+
+        def rhs(t, x, e):
+            """Wrapper for scipy's ODE solver."""
+            dr, ds = self.model.rhs(x[0], x[1], e(t))
+            return (dr, ds)
+
+        # Solve the ODE
+        self.solution = solve_ivp(
+            rhs,
+            (t_0, t_final),
+            (self.r0, self.s0),
+            t_eval=np.linspace(t_0, t_final, 300),
+            dense_output=True,
+            args=(external_input,),
+        )
+
+        # Extract solution
+        r, s = self.solution.y
+        t = self.solution.t
+        e = [external_input(_) for _ in t]
+
+        # Create plot
+        plt.clf()
+        plt.plot(
+            t,
+            s,
+            label="Depression symptoms",
+            color=color_s,
+            linestyle="-",
+            **kwargs,
+        )
+        plt.xlabel("Time")
+        plt.ylabel("Magnitude")
+
+        plt.plot(
+            t,
+            r,
+            label="Resilience level",
+            color=color_r,
+            linestyle="--",
+            **kwargs,
+        )
+        plt.plot(
+            t,
+            e,
+            label="Adverse input",
+            color=color_e,
+            linestyle=":",
+            **kwargs,
+        )
+        plt.legend()
+
+        plt.title(f"{self.name} w/ $r_0={self.r0:.2f}$, $s_0={self.s0:.2f}$")
+
+        ax = plt.gca()
+        ax.spines[["top", "right"]].set_visible(False)
+        ax.spines[
+            [
+                "left",
+                "bottom",
+            ]
+        ].set_visible(True)
+        # ax.set_xlim([t_0 - 1e-2, t_final + 3e-2])
+        ax.set_xlim(min(t_0, t_final) - 1e-2, max(t_0, t_final) + 1e-2)
+        ax.set_ylim([-1e-2, 1 + 1e-2])
+
+        return ax

rsmodel-0.1.0/rsmodel/utils.py

@@ -0,0 +1,215 @@
+"""Utility functions and predefined scenarios for the RS model.
+
+This module provides:
+- Predefined stimulus scenarios
+- Visualization helpers
+- Download utilities
+"""
+
+import io
+from typing import Callable, Dict
+
+
+def from_bad_to_worse_then_better(t: float) -> float:
+    """Scenario: Initial stress, brief relief, severe stress, then recovery.
+
+    Timeline:
+    - t < 1: Very low stress (e=0.01)
+    - 1 ≤ t < 1.5: High stress (e=0.7)
+    - 1.5 ≤ t < 5: Low stress (e=0.1)
+    - 5 ≤ t < 6.5: Very high stress (e=0.9)
+    - 6.5 ≤ t ≤ 8.5: Low stress (e=0.1)
+    - t > 8.5: Minimal stress (e=0.01)
+
+    Args:
+        t: Time value
+
+    Returns:
+        External input value e(t)
+    """
+    if t < 1:
+        return 0.01
+    elif t < 1.5:
+        return 0.7
+    elif t < 5:
+        return 0.1
+    elif t < 6.5:
+        return 0.9
+    elif t <= 8.5:
+        return 0.1
+    return 0.01
+
+
+def multiple_adverse_events(t: float) -> float:
+    """Scenario: Multiple stress episodes with varying intensity.
+
+    Timeline:
+    - t < 1: Low stress (e=0.1)
+    - 1 ≤ t < 3: High stress (e=0.9)
+    - 3 ≤ t < 6: Low stress (e=0.1)
+    - 6 ≤ t < 6.5: Moderate stress (e=0.3)
+    - 6.5 ≤ t < 15.5: Very low stress (e=0.05)
+    - 15.5 ≤ t < 16: High stress (e=0.9)
+    - 16 ≤ t < 18.5: Very low stress (e=0.05)
+    - 18.5 ≤ t < 19: Moderate stress (e=0.3)
+    - 19 ≤ t ≤ 20: Very low stress (e=0.05)
+    - t > 20: Minimal stress (e=0.01)
+
+    Args:
+        t: Time value
+
+    Returns:
+        External input value e(t)
+    """
+    if t < 1:
+        return 0.1
+    if t < 3:
+        return 0.9
+    if t < 6:
+        return 0.1
+    if t < 6.5:
+        return 0.3
+    if t < 15.5:
+        return 0.05
+    if t < 16:
+        return 0.9
+    if t < 18.5:
+        return 0.05
+    if t < 19:
+        return 0.3
+    if t <= 20:
+        return 0.05
+    return 0.01
+
+
+def from_bad_to_less_bad_to_not_great(t: float) -> float:
+    """Scenario: Fluctuating stress levels without full recovery.
+
+    Timeline:
+    - t < 1: Low stress (e=0.1)
+    - 1 ≤ t < 2: High stress (e=0.9)
+    - 2 ≤ t < 5: Low stress (e=0.1)
+    - 5 ≤ t < 5.5: Moderate stress (e=0.5)
+    - 5.5 ≤ t ≤ 20: Low-moderate stress (e=0.2)
+    - t > 20: Moderate stress (e=0.3)
+
+    Args:
+        t: Time value
+
+    Returns:
+        External input value e(t)
+    """
+    if t < 1:
+        return 0.1
+    if t < 2:
+        return 0.9
+    if t < 5:
+        return 0.1
+    if t < 5.5:
+        return 0.5
+    if t <= 20:
+        return 0.2
+    return 0.3
+
+
+def get_predefined_scenarios() -> Dict[str, Callable[[float], float]]:
+    """Get dictionary of all predefined stimulus scenarios.
+
+    Returns:
+        Dictionary mapping scenario names to stimulus functions
+    """
+    return {
+        "from bad to worse then better": from_bad_to_worse_then_better,
+        "multiple adverse events": multiple_adverse_events,
+        "from bad to less bad to not great": from_bad_to_less_bad_to_not_great,
+    }
+
+
+def create_custom_stimulus(
+    input_data: Dict[float, float], period: float = None
+) -> Callable[[float], float]:
+    """Create a custom stimulus function from data points.
+
+    Creates a piecewise constant (sample-and-hold) function from
+    a dictionary of time points and values.
+
+    Args:
+        input_data: Dictionary mapping time points to input values
+        period: If specified, the stimulus repeats with this period
+
+    Returns:
+        Stimulus function e(t)
+    """
+
+    def stimulus(t: float) -> float:
+        if period is not None:
+            t = t % period
+
+        for _t, _e in sorted(input_data.items(), key=lambda a: a[0]):
+            if t <= _t + 0.5:
+                return _e
+        return 0
+
+    return stimulus
+
+
+def sample_and_hold(*samples) -> Callable[[float], float]:
+    """Create a sample-and-hold signal from jump specifications.
+
+    Args:
+        *samples: Variable number of (time, value) tuples
+
+    Returns:
+        Sample-and-hold function
+
+    Example:
+        >>> signal = sample_and_hold((0, 0.1), (5, 0.9), (10, 0.2))
+        >>> signal(3)  # Returns 0.1
+        >>> signal(7)  # Returns 0.9
+    """
+
+    def signal(t):
+        _samples = sorted((*samples, (-1, 0)), key=lambda _: _[0], reverse=True)
+        for _t, _v in _samples:
+            if _t < t:
+                return _v
+        return 0
+
+    signal.__doc__ = f"Sample-and-hold signal: {sorted(samples)}"
+    return signal
+
+
+def download_figure_data(
+    axisobject, basename: str = "figure", format: str = "pdf"
+) -> io.BytesIO:
+    """Create downloadable figure data.
+
+    Args:
+        axisobject: Matplotlib axes object
+        basename: Base filename (without extension)
+        format: File format ('pdf', 'png', 'svg')
+
+    Returns:
+        BytesIO buffer with figure data
+    """
+    buf = io.BytesIO()
+    axisobject.figure.savefig(buf, format=format, bbox_inches="tight")
+    buf.seek(0)
+    return buf
+
+
+def get_mimetype(format: str) -> str:
+    """Get MIME type for file format.
+
+    Args:
+        format: File format ('pdf', 'png', 'svg')
+
+    Returns:
+        MIME type string
+    """
+    mimetypes = {
+        "pdf": "application/pdf",
+        "png": "image/png",
+        "svg": "image/svg+xml",
+    }
+    return mimetypes.get(format, "application/octet-stream")