Merge branch 'master' into worktree-wobbly-riding-origami

Author: aarmey

.gitignore

@@ -13,6 +13,7 @@ nosetests.xml
 
 .venv/
 venv/
+.claude/
 profile
 profile.svg
 .DS_Store

docs/Installation.rst

@@ -17,3 +17,26 @@ You can clone the public repository:
 .. code-block:: console
 
     $ git clone https://github.com/meyer-lab/tHMM.git
+
+tHMM is built and its dependencies are managed with `uv`_. Once you have
+`uv` installed, set up the environment and install all dependencies with:
+
+.. code-block:: console
+
+    $ cd tHMM
+    $ uv sync
+
+You can then run the test suite:
+
+.. code-block:: console
+
+    $ uv run pytest
+
+or use any of the package's modules with:
+
+.. code-block:: console
+
+    $ uv run python -c "from lineage.LineageTree import LineageTree"
+
+.. _Github repo: https://github.com/meyer-lab/tHMM
+.. _uv: https://docs.astral.sh/uv/

docs/conf.py

@@ -22,7 +22,7 @@
 # -- Project information -----------------------------------------------------
 
 project = "tHMM"
-copyright = "2022, Farnaz Mohammadi, JC Lagarde, Aaron S Meyer"
+copyright = "2022-2026, Farnaz Mohammadi, JC Lagarde, Aaron S Meyer"
 author = "Farnaz Mohammadi, JC Lagarde, Aaron S Meyer"
 
 # The full version, including alpha/beta/rc tags
@@ -66,11 +66,6 @@
 #
 html_theme = "sphinx_rtd_theme"
 
-# Add any paths that contain custom static files (such as style sheets) here,
-# relative to this directory. They are copied after the builtin static files,
-# so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ["_static"]
-
 autoapi_root = "technical/api"
 
 autodoc_typehints = "description"

docs/index.rst

@@ -4,49 +4,57 @@ Welcome to tHMM's documentation!
 ================================
 
 tHMM is a Python3 library for clustering data in the form of a binary lineage tree.
-This documentation includes an overview of the package, and how to use the functions and classes, 
+This documentation includes an overview of the package, and how to use the functions and classes,
 and examples of the application of tHMM in identifying cellular phenotypic heterogeneity in cancer cells under treatment.
 
 Features
 --------
 
-* Uses lineage tree data for clustering individuals according to their relationship to each other and measurements. 
+* Uses lineage tree data for clustering individuals according to their relationship to each other and measurements.
 * Outputs the number of clusters, transition probability between the clusters, and distribution corresponding to the emission for each cluster.
 * Can plot the lineage trees with their associated cluster shown as a color.
 
 Outline
 -------
 
-.. toctree:: Overview
+.. toctree::
+   :caption: Overview
    :name: overview
    :maxdepth: 1
 
-   overview.rst
+   overview
 
-.. toctree:: Installation
+.. toctree::
+   :caption: Installation
    :name: install
    :maxdepth: 1
 
-   installation.rst
+   Installation
 
-.. toctree:: System Requirements
+.. toctree::
+   :caption: System Requirements
    :name: syst-req
    :maxdepth: 1
 
-   system-reqs.rst
+   system-reqs
 
-.. toctree:: getting-started
+.. toctree::
+   :caption: Getting Started
    :name: getting-started
    :maxdepth: 1
 
-   tHMM-getting-started.rst
+   tHMM-getting-started
 
-.. toctree:: Emissions
+.. toctree::
+   :caption: Emissions
    :name: stateDistribution
    :maxdepth: 1
 
-   stateDistributions.rst
+   stateDistributions
 
-.. toctree:: API Reference
+.. toctree::
+   :caption: API Reference
    :name: api
    :maxdepth: 1
+
+   technical/api/index

docs/modules.rst

@@ -34,7 +34,8 @@ These are assigned as instances of the class object. One can assert that the giv
 actually make sense for the distribution. For example, a normal
 distribution cannot have a negative or zero standard deviation.
 
-.. code:: ipython3
+.. code:: python
+
     import numpy as np
     import scipy.stats as sp
 
@@ -46,7 +47,8 @@ distribution cannot have a negative or zero standard deviation.
         self.gamma_scale = gamma_scale
         self.params = [self.bern_p, self.gamma_a, self.gamma_scale]
 
-.. code:: ipython3
+.. code:: python
+
     #Normal 
     def __init__(self, norm_loc, norm_scale):
         """ Initialization function should take in just in the parameters for the observations that comprise the multivariate random variable emission they expect their data to have. """
@@ -73,7 +75,7 @@ The variables `gamma_obs_censor` and `norm_obs_censor` are created and set to 1
 We do the censoring later.
 The rvs function returns the observed phenotypes as a tuple of lists.
 
-.. code:: ipython3
+.. code:: python
 
     # Bernoulli/Gamma
     def rvs(self, size: int):
@@ -86,7 +88,8 @@ The rvs function returns the observed phenotypes as a tuple of lists.
         # These tuples of observations will go into the cells in the lineage tree.
         return bern_obs, gamma_obs, gamma_obs_censor
 
-.. code:: ipython3
+.. code:: python
+
     # Normal
     def rvs(self, size):  # user has to identify what the multivariate (or univariate if he or she so chooses) random variable looks like
         """ User-defined way of calculating a random variable given the parameters of the state stored in that observation's object. """
@@ -117,7 +120,8 @@ The fully observed cells are fed to `logpdf` to calculate the likelihood,
 and those cells that have missing information are fed to `logsf`.
 Those cells that died are then removed in the first example that cell's fate matters.
 
-.. code:: ipython3
+.. code:: python
+
     # Bernoulli/Gamma
     def logpdf(self, x: np.ndarray):
         """ User-defined way of calculating the likelihood of the observation stored in a cell.
@@ -138,7 +142,8 @@ Those cells that died are then removed in the first example that cell's fate mat
 
         return ll
 
-.. code:: ipython3
+.. code:: python
+
     # Normal
     def logpdf(self, tuple_of_obs):  # user has to define how to calculate the likelihood
         """ User-defined way of calculating the likelihood of the observation stored in a cell. """
@@ -173,7 +178,7 @@ minimize function of the scipy.optimize to find the parameters and
 the function is located in the lineage/states/stateCommon.py
 
 
-.. code:: ipython3
+.. code:: python
 
     # Bernoulli/Gamma
     def estimator(self, x: list, gammas: np.array):
@@ -201,7 +206,8 @@ the function is located in the lineage/states/stateCommon.py
 
         self.params[1], self.params[2] = gamma_estimator(γ_obs[g_mask], gamma_obs_censor[g_mask], gammas[g_mask], self.params[1:3]) # gamma shape and scale
 
-.. code:: ipython3
+.. code:: python
+
     # Normal
     def estimator(self, x: list, gammas: np.array):
         """ User-defined way of estimating the parameters given a list of the tuples of observations from a group of cells. """
@@ -225,7 +231,7 @@ Now that we have a functioning Gaussian StateDistribution, let's try it
 with the overall model. As in the overview, we first define our initial probability vector and
 the state transition probability matrices.
 
-.. code:: ipython3
+.. code:: python
 
     from lineage.LineageTree import LineageTree
 
@@ -236,7 +242,7 @@ the state transition probability matrices.
 
 Creating the Emissions for two states:
 
-.. code:: ipython3
+.. code:: python
 
     # E: states are defined as StateDistribution objects
     
@@ -255,7 +261,7 @@ Creating the Emissions for two states:
 
 Creating the lineage tree:
 
-.. code:: ipython3
+.. code:: python
 
     lineage1 = LineageTree.rand_init(pi, T, E, desired_num_cells=2**5 - 1)
     # These are the minimal arguments required to instantiate lineages
@@ -266,23 +272,25 @@ Below is the analysis for a single lineage. Note that the state objects
 are merely switched. However, the model fairly accurately predicts the
 transition matrix and state parameters.
 
-.. code:: ipython3
+.. code:: python
+
+    from lineage.Analyze import Analyze_list
 
-    from lineage.Analyze import Analyze
     X = [lineage1] # population just contains one lineage
-    tHMMobj, pred_states_by_lineage, LL = Analyze(X, 2) # find two states
+    tHMMobj_list, LL, gammas = Analyze_list([X], 2, write_states=True) # find two states
+    tHMMobj = tHMMobj_list[0]
 
-.. code:: ipython3
+.. code:: python
 
     print(tHMMobj.estimate.pi)
 
-.. code:: ipython3
+.. code:: python
 
     print(tHMMobj.estimate.T)
 
-.. code:: ipython3
+.. code:: python
 
-    for state in range(lineage1.num_states):
+    for state in range(tHMMobj.num_states):
         print("State {}:".format(state))
         print("                    estimated state:", tHMMobj.estimate.E[state])
         print("original parameters given for state:", E[state])
@@ -304,7 +312,7 @@ latent clocks -- a division clock ``T_D`` and a death clock ``T_X`` -- and what
 observe is ``min(T_D, T_X)`` together with which one fired. The likelihood has the
 three standard competing-risks cases:
 
-.. code:: ipython3
+.. code:: python
 
     # transition seen at t:   f_D(t) * S_X(t)
     # death seen at t:        f_X(t) * S_D(t)

docs/requirements.txt

@@ -22,4 +22,7 @@ OS requirements
 
 Python dependencies
 -------------------
-    `tHMM` requires `virtualenv`. All other required packages can then be installed using `make venv` to establish a virtual environment. The Python packages that will be installed are listed in `requirements.txt`, and can be directly installed using `pip install -r requirements.txt`.
+    `tHMM` requires Python >=3.10 and is built and managed with `uv <https://docs.astral.sh/uv/>`_.
+    Once `uv` is installed, all required packages can be installed into a project-local
+    virtual environment with ``uv sync``, run from the root of the repository.
+    The package's dependencies are listed in ``pyproject.toml``.