{"id":22663914,"url":"https://github.com/zsteve/stationaryot","last_synced_at":"2025-04-12T08:08:32.389Z","repository":{"id":54438933,"uuid":"322714910","full_name":"zsteve/StationaryOT","owner":"zsteve","description":"Dynamic inference from single-cell snapshots by optimal transport","archived":false,"fork":false,"pushed_at":"2024-03-14T20:57:50.000Z","size":8677,"stargazers_count":15,"open_issues_count":2,"forks_count":3,"subscribers_count":3,"default_branch":"main","last_synced_at":"2024-11-04T21:11:54.298Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zsteve.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-12-18T22:06:35.000Z","updated_at":"2024-10-12T08:51:05.000Z","dependencies_parsed_at":"2022-08-13T15:40:46.314Z","dependency_job_id":null,"html_url":"https://github.com/zsteve/StationaryOT","commit_stats":null,"previous_names":["zsteve/statot"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zsteve%2FStationaryOT","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zsteve%2FStationaryOT/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zsteve%2FStationaryOT/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zsteve%2FStationaryOT/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zsteve","download_url":"https://codeload.github.com/zsteve/StationaryOT/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":228894698,"owners_count":17988169,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-12-09T12:45:31.118Z","updated_at":"2024-12-09T12:45:31.833Z","avatar_url":"https://github.com/zsteve.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# StationaryOT: Dynamic inference from single-cell snapshots by optimal transport\n\n\n[![PyPI version](https://badge.fury.io/py/statot.svg)](https://badge.fury.io/py/statot) [![Downloads](https://pepy.tech/badge/statot)](https://pepy.tech/project/statot) [![Documentation Status](https://readthedocs.org/projects/statot/badge/?version=latest)](https://statot.readthedocs.io/en/latest/?badge=latest) \n\n![Schematic](https://github.com/zsteve/statOT/blob/main/aux_files/statot_illustration.png)\n\n## Introduction and overview\nEntropy-regularized optimal transport has been used to infer cellular trajectories in time-course data [1]. Stationary optimal transport (OT) extends this approach to snapshots of biological systems in equilibrium. A system is in equilibrium if you would expect the same proportions of populations in each snapshot, though individual cells progress along trajectories. \n\nWe model biological processes with a diffusion-drift process subject to branching due to cell birth and death. To maintain equlibrium, we define source and sink regions, where cells are created in the source regions and are absorbed in the sinks subject to birth and death rates. At a population level, the effects of growth, entry, and exit can be captured by a spatially dependent flux, R(x), and population dynamics can be described by a population balance partial differential equation:\n\n![Population Balance PDE](https://github.com/zsteve/statOT/blob/main/aux_files/pop-balance-pde.png)\n\nwhere ![equilibrium equation](https://github.com/zsteve/statOT/blob/main/aux_files/equilibrium-eqn.png) by our equilibirum assumption.\n\nThis problem has previously been explored by Weinreb et al. [2] who approach the problem by solving a system of linear equations to recover the potential. In contrast, stationary OT solves a convex optimization problem for the transition probabilities. This approach has the flexibility to allow additional information such as RNA velocity, which may allow recovery of non-conservative dynamics such as oscillations. Combined with earlier OT approaches, stationary OT provides a framework for approaching both time-series and snapshot data.\n\nThis package provides the ability to run stationary OT on single-cell expression data to recover transition and fate probabilities. This package also provides a wrapper for use with [CellRank](https://cellrank.readthedocs.io/en/latest/).\n\n## Installation\n\nRun `pip install statot` in your working environment. Alternatively, clone this repository and run `pip install .` in the top level directory. \n\n## Usage\n\nRead the full documentation [here](https://statot.readthedocs.io/en/latest/).\n\n### Inputs\n1. **Projected Expression Matrix**: An *n x m* matrix of cells by expression data. We recommend using a lower-dimensional embedding such as PCA.\n2. **Sinks**: An *n x 1* boolean vector indicating cells that leave the system.\n3. **Sources**: An *n x 1* boolean vector indicating cells that are where mass is entering the system. Typically, this will be the complement of the sink vector.\n4. **Sink Weights**: An *n x 1* vector indicating the weight of each sink, where sinks with higher weight will absorb more mass.\n5. **Cost Matrix**: An *n x n* matrix specifiying the cost for each cell transporting to each other cell in the coupling, such as the Euclidean distance between cells in PCA coordinates.\n6. **Growth Rates**: An *n x 1* vector specifying the expected number of decendents of each cell in *dt = 1*.\n7. **dt**: The timestep between snapshots.\n\n### Quick Start\n\nCompute first the vector `g` of growth rates. \nThen use the `statot.statot` function to calculate transition probabilities for cells in a single timestep:\n\n```python\nstatot(x, C = None, eps = None, method = \"ent\", g = None,\n           flow_rate = None,\n           dt = None, \n           maxiter = 5000, tol = 1e-9)\n```\n\nTo compute fate probabilities by sink, use `compute_fate_probs`:\n```python\ncompute_fate_probs(P, sink_idx)\n```\n\nFinally, to compute the fate probabilities by lineage, use \n`compute_fate_probs_lineages`:\n```python\ncompute_fate_probs_lineages(P, sink_idx, labels)\n```\nwhere `labels` should be a `np.array` of strings corresponding to the lineage annotation for each cell.\n\n### Example application to Arabidopsis root tip\n\n[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/zsteve/statOT/blob/main/examples/arabidopsis_analysis.ipynb)\n\nAn example application to Arabidopsis root tip data is available as a Jupyter notebook in the `examples/` directory. \n\n### Citing\n\nRead the [preprint](https://www.biorxiv.org/content/10.1101/2021.03.02.433630v1). \n\nOptimal transport analysis reveals trajectories in steady-state systems\n\nStephen Zhang, Anton Afanassiev, Laura Greenstreet, Tetsuya Matsumoto, Geoffrey Schiebinger\n\nbioRxiv 2021.03.02.433630; doi: https://doi.org/10.1101/2021.03.02.433630\n\n### References\n[1] Schiebinger, G et al. Optimal-transport analysis of single-cell gene expression identifies developmentaltrajectories in reprogramming. Cell. 2019; 176(4): 928–943. https://doi.org/10.1016/j.cell.2019.02.026.\n\n[2] Weinreb et al. Fundamental limits ondynamic inference from single-cell snapshots. Proceedings of the NationalAcademy of Sciences. 2018; 115(10):E2467–E2476. https://doi.org/10.1073/pnas.1714723115.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzsteve%2Fstationaryot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzsteve%2Fstationaryot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzsteve%2Fstationaryot/lists"}