cajal 1.0.0__tar.gz

cajal-1.0.0/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 CAJAL authors
+
+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.

cajal-1.0.0/PKG-INFO

@@ -0,0 +1,112 @@
+Metadata-Version: 2.1
+Name: cajal
+Version: 1.0.0
+Summary: A library for multi-modal cell morphology analyses using Gromov-Wasserstein (GW) distance.
+Author-email: Pablo Cámara <pcamara@pennmedicine.upenn.edu>
+License: MIT License
+        
+        Copyright (c) 2022 CAJAL authors
+        
+        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.
+        
+Project-URL: git-repo, https://github.com/CamaraLab/CAJAL
+Project-URL: readthedocs, https://cajal.readthedocs.io/en/latest/
+Project-URL: biorxiv, https://www.biorxiv.org/content/10.1101/2022.05.19.492525v2
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Framework :: Jupyter
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE.md
+Requires-Dist: igraph
+Requires-Dist: leidenalg
+Requires-Dist: networkx>=2.8.8
+Requires-Dist: numpy
+Requires-Dist: cython>=3
+Requires-Dist: pathos
+Requires-Dist: tqdm>=4.64.1
+Requires-Dist: potpourri3d
+Requires-Dist: pynndescent>=0.5.13
+Requires-Dist: python-louvain
+Requires-Dist: scipy>=1.10
+Requires-Dist: scikit-image
+Requires-Dist: tifffile
+Requires-Dist: trimesh
+Requires-Dist: umap-learn>=0.5.3
+Requires-Dist: mpltern>=1.0.0
+Requires-Dist: scikit-dimension
+Provides-Extra: dev
+Requires-Dist: mypy>=0.991; extra == "dev"
+Requires-Dist: pytest>=7.2.1; extra == "dev"
+Requires-Dist: pre-commit>=2.20.0; extra == "dev"
+Provides-Extra: vis
+Requires-Dist: matplotlib>=3.7.0; extra == "vis"
+Requires-Dist: networkx; extra == "vis"
+Requires-Dist: navis; extra == "vis"
+Requires-Dist: mpltern; extra == "vis"
+
+# CAJAL <a href='https://github.com/CamaraLab/CAJAL'><img src="docs/images/logo.png" align="right" width="24%"/></a>
+[![Build and Test](https://github.com/CamaraLab/CAJAL/actions/workflows/python-package.yml/badge.svg?branch=main)](https://github.com/CamaraLab/CAJAL/actions/workflows/python-package.yml)
+[![codecov](https://codecov.io/github/CamaraLab/CAJAL/branch/main/graph/badge.svg?token=RU5ZR1SE8Z)](https://codecov.io/github/CamaraLab/CAJAL)
+![GitHub release (latest by date including pre-releases)](https://img.shields.io/github/v/release/CamaraLab/CAJAL?include_prereleases&color=green)
+
+CAJAL is a Python library for multi-modal cell morphology analyses using Gromov-Wasserstein (GW) distance. Detailed information about the methods implemented in CAJAL can be found in:
+
+K. W. Govek, P. Nicodemus, Y. Lin, J. Crawford, A. B. Saturnino, H. Cui, K. Zoga, M. P. Hart, P. G. Camara, _CAJAL enables analysis and integration of single-cell morphological data using metric geometry_. **Nature Communications** 14 (2023) 3672. [DOI:10.1038/s41467-023-39424-2](https://doi.org/10.1038/s41467-023-39424-2)
+
+## Installation
+Until we upload the package to PyPI, the pip installation works from GitHub:
+```commandline
+pip install git+https://github.com/CamaraLab/CAJAL.git
+```
+Installation on a standard desktop computer should take a few minutes.
+
+----
+
+A C++ compiler is required for the Gromov-Wasserstein computation and may be required for the potpourri3d library if the precompiled binaries are not compatible with your system.
+On Windows, we recommend Microsoft Visual C++ 14.0 or greater, which can be installed via the [Microsoft C++ Build Tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/). On Ubuntu, it requires g++ and may require the package python3.x-dev, which registers the Python header files with g++.
+
+----
+
+The easiest way to run CAJAL is via [Jupyter](https://jupyter.org/). Install Jupyter with
+```commandline
+pip install notebook
+```
+Then start up Jupyter from terminal / Powershell using
+```commandline
+jupyter notebook
+```
+
+## Docker image
+We provide two Docker images which contain CAJAL and its dependencies, ```cajal:minimal``` and ```cajal:maximal```. ```cajal:minimal``` is built on top of the Jupyter notebook Docker image ```base-notebook``` and contains only CAJAL and its dependencies, ```cajal:maximal``` is built on top of the Docker image ```tensorflow-notebook``` and contains numerous data science tools for further analysis of the output of CAJAL. Running the following command will launch a Jupyter notebook server on localhost with CAJAL and its dependencies installed:
+```commandline
+docker run -it -p 8888:8888 -v C:\Users\myusername\Documents\myfolder:/home/jovyan/work camaralab/cajal:maximal
+```
+The ```-p``` flag controls the port number on local host. For example, writing ```-p 4264:8888``` will let you access the Jupyter server from 127.0.0.1:4264. The ```-v``` "bind mount" flag allows one to mount a local directory on the host machine to a folder inside the container so that you can read and write files on the host machine from within the Docker image. Here one must mount the folder on the host machine as /home/jovyan/work or /home/jovyan/some_other_folder as the primary user "jovyan" in the Docker image only has access to that directory and to the /opt/conda folder. See the [Jupyter docker image documentation](https://jupyter-docker-stacks.readthedocs.io/en/latest/using/selecting.html) for more information.
+
+## Documentation
+Extensive documentation, including several tutorials, can be found in [CAJAL's readthedocs.io website](https://cajal.readthedocs.io/en/latest/index.html). This website is under development and will continue to be substantially updated during the coming months.
+
+## New in this release (v1.0.0, 6/18/2024)
+- Improved performance
+- New functionality for intgerating multi-modal spaces using the WNN algorithm
+- New functionality for visualizing consistency between morphological, electrophysiological, and transcriptomic cellular variation using ternary plots
+- New functionality for visualizing local discrepancies between the morphologies of neurons
+- Fixed several small bugs

cajal-1.0.0/README.md

@@ -0,0 +1,48 @@
+# CAJAL <a href='https://github.com/CamaraLab/CAJAL'><img src="docs/images/logo.png" align="right" width="24%"/></a>
+[![Build and Test](https://github.com/CamaraLab/CAJAL/actions/workflows/python-package.yml/badge.svg?branch=main)](https://github.com/CamaraLab/CAJAL/actions/workflows/python-package.yml)
+[![codecov](https://codecov.io/github/CamaraLab/CAJAL/branch/main/graph/badge.svg?token=RU5ZR1SE8Z)](https://codecov.io/github/CamaraLab/CAJAL)
+![GitHub release (latest by date including pre-releases)](https://img.shields.io/github/v/release/CamaraLab/CAJAL?include_prereleases&color=green)
+
+CAJAL is a Python library for multi-modal cell morphology analyses using Gromov-Wasserstein (GW) distance. Detailed information about the methods implemented in CAJAL can be found in:
+
+K. W. Govek, P. Nicodemus, Y. Lin, J. Crawford, A. B. Saturnino, H. Cui, K. Zoga, M. P. Hart, P. G. Camara, _CAJAL enables analysis and integration of single-cell morphological data using metric geometry_. **Nature Communications** 14 (2023) 3672. [DOI:10.1038/s41467-023-39424-2](https://doi.org/10.1038/s41467-023-39424-2)
+
+## Installation
+Until we upload the package to PyPI, the pip installation works from GitHub:
+```commandline
+pip install git+https://github.com/CamaraLab/CAJAL.git
+```
+Installation on a standard desktop computer should take a few minutes.
+
+----
+
+A C++ compiler is required for the Gromov-Wasserstein computation and may be required for the potpourri3d library if the precompiled binaries are not compatible with your system.
+On Windows, we recommend Microsoft Visual C++ 14.0 or greater, which can be installed via the [Microsoft C++ Build Tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/). On Ubuntu, it requires g++ and may require the package python3.x-dev, which registers the Python header files with g++.
+
+----
+
+The easiest way to run CAJAL is via [Jupyter](https://jupyter.org/). Install Jupyter with
+```commandline
+pip install notebook
+```
+Then start up Jupyter from terminal / Powershell using
+```commandline
+jupyter notebook
+```
+
+## Docker image
+We provide two Docker images which contain CAJAL and its dependencies, ```cajal:minimal``` and ```cajal:maximal```. ```cajal:minimal``` is built on top of the Jupyter notebook Docker image ```base-notebook``` and contains only CAJAL and its dependencies, ```cajal:maximal``` is built on top of the Docker image ```tensorflow-notebook``` and contains numerous data science tools for further analysis of the output of CAJAL. Running the following command will launch a Jupyter notebook server on localhost with CAJAL and its dependencies installed:
+```commandline
+docker run -it -p 8888:8888 -v C:\Users\myusername\Documents\myfolder:/home/jovyan/work camaralab/cajal:maximal
+```
+The ```-p``` flag controls the port number on local host. For example, writing ```-p 4264:8888``` will let you access the Jupyter server from 127.0.0.1:4264. The ```-v``` "bind mount" flag allows one to mount a local directory on the host machine to a folder inside the container so that you can read and write files on the host machine from within the Docker image. Here one must mount the folder on the host machine as /home/jovyan/work or /home/jovyan/some_other_folder as the primary user "jovyan" in the Docker image only has access to that directory and to the /opt/conda folder. See the [Jupyter docker image documentation](https://jupyter-docker-stacks.readthedocs.io/en/latest/using/selecting.html) for more information.
+
+## Documentation
+Extensive documentation, including several tutorials, can be found in [CAJAL's readthedocs.io website](https://cajal.readthedocs.io/en/latest/index.html). This website is under development and will continue to be substantially updated during the coming months.
+
+## New in this release (v1.0.0, 6/18/2024)
+- Improved performance
+- New functionality for intgerating multi-modal spaces using the WNN algorithm
+- New functionality for visualizing consistency between morphological, electrophysiological, and transcriptomic cellular variation using ternary plots
+- New functionality for visualizing local discrepancies between the morphologies of neurons
+- Fixed several small bugs

cajal-1.0.0/pyproject.toml

@@ -0,0 +1,91 @@
+[build-system]
+# Minimum requirements for the build system to execute
+requires = [
+	 "setuptools >= 70",
+	 "pip>=24",
+	 "wheel",
+	 "Cython>=3",
+	 "numpy"
+	 ]
+# What should the build-backend be?
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "cajal"
+version = "1.0.0"
+description="A library for multi-modal cell morphology analyses using Gromov-Wasserstein (GW) distance."
+readme="./README.md"
+requires-python=">=3.9"
+
+
+authors= [ { name="Pablo Cámara", email='pcamara@pennmedicine.upenn.edu' } ]
+classifiers=[
+	'License :: OSI Approved :: MIT License',
+        'Programming Language :: Python :: 3',
+        'Framework :: Jupyter',
+        'Topic :: Scientific/Engineering :: Bio-Informatics'
+    ]
+
+dependencies = [
+	"igraph",
+        "leidenalg",
+        "networkx>=2.8.8",
+        "numpy",
+	"cython >= 3",
+        "pathos",
+	"tqdm>=4.64.1",	
+        "potpourri3d",
+	"pynndescent>=0.5.13",
+        "python-louvain",
+        "scipy>=1.10",
+        "scikit-image",
+        "tifffile",
+        "trimesh",
+        "umap-learn>=0.5.3",
+	"mpltern>=1.0.0",
+	"scikit-dimension"
+	]
+
+[project.optional-dependencies]
+dev = [
+    "mypy>=0.991",
+    "pytest >= 7.2.1",
+    "pre-commit >= 2.20.0"
+]
+
+vis = [
+    "matplotlib >= 3.7.0",
+    "networkx",
+    "navis",
+    "mpltern"
+]
+
+[project.license]
+file="./LICENSE.md"
+
+[project.urls]
+git-repo="https://github.com/CamaraLab/CAJAL"
+readthedocs="https://cajal.readthedocs.io/en/latest/"
+biorxiv="https://www.biorxiv.org/content/10.1101/2022.05.19.492525v2"
+
+[tool.black]
+force-exclude = '''
+/(
+   \.git
+ | \.mypy_cache
+ | _build
+ | build
+ | dist
+ | stubs
+ | pyproject.toml
+ | \.pre-commit-config.yaml
+)/
+'''
+
+[tool.codespell]
+# Ref: https://github.com/codespell-project/codespell#using-a-config-file
+skip = '.git*,*.css,pyproject.toml,data,swc,*.swc,obj,*.obj,*.pyi'
+check-hidden = true
+# embedded images into jupyter notebooks, acronyms and names starting with capital letter
+ignore-regex = '(^\s*"image/\S+": ".*|\b([A-Z][a-zA-Z]+|scl/fo/|ser: Series|ot\.lp|networkx\.algorithms\.mis)\b)'
+ignore-words-list = 'coo'

cajal-1.0.0/setup.cfg

@@ -0,0 +1,8 @@
+[flake8]
+max-line-length = 100
+ignore = E203,W503
+
+[egg_info]
+tag_build = 
+tag_date = 0
+

cajal-1.0.0/setup.py

@@ -0,0 +1,14 @@
+from setuptools import setup
+from Cython.Build import cythonize
+import numpy
+import os
+
+
+ROOT = os.path.abspath(os.path.dirname(__file__))
+include_path = [numpy.get_include()]
+
+setup(
+    ext_modules=cythonize(["src/cajal/*.pyx"]),
+    compiler_directives={"language_level": "3"},
+    include_dirs=include_path,
+)

cajal-1.0.0/src/cajal/EMD.h

@@ -0,0 +1,38 @@
+/* This file is a c++ wrapper function for computing the transportation cost
+ * between two vectors given a cost matrix.
+ *
+ * It was written by Antoine Rolet (2014) and mainly consists of a wrapper
+ * of the code written by Nicolas Bonneel available on this page
+ *          http://people.seas.harvard.edu/~nbonneel/FastTransport/
+ *
+ * It was then modified to make it more amenable to python inline calling
+ *
+ * Please give relevant credit to the original author (Nicolas Bonneel) if
+ * you use this code for a publication.
+ *
+ */
+
+
+#ifndef EMD_H
+#define EMD_H
+
+#include <iostream>
+#include <vector>
+#include <cstdint>
+
+typedef unsigned int node_id_type;
+
+enum ProblemType {
+    INFEASIBLE,
+    OPTIMAL,
+    UNBOUNDED,
+    MAX_ITER_REACHED
+};
+
+int myCMessage(int a,int b);
+int EMD_wrap(int n1,int n2, double *X, double *Y,double *D, double *G, double* alpha, double* beta, double *cost, uint64_t maxIter);
+int EMD_wrap_omp(int n1,int n2, double *X, double *Y,double *D, double *G, double* alpha, double* beta, double *cost, uint64_t maxIter, int numThreads);
+
+
+
+#endif

cajal-1.0.0/src/cajal/EMD_wrapper.cpp

@@ -0,0 +1,220 @@
+/* This file is a c++ wrapper function for computing the transportation cost
+ * between two vectors given a cost matrix.
+ *
+ * It was written by Antoine Rolet (2014) and mainly consists of a wrapper
+ * of the code written by Nicolas Bonneel available on this page
+ *          http://people.seas.harvard.edu/~nbonneel/FastTransport/
+ *
+ * It was then modified to make it more amenable to python inline calling
+ *
+ * Please give relevant credit to the original author (Nicolas Bonneel) if
+ * you use this code for a publication.
+ *
+ */
+
+
+#include "network_simplex_simple.h"
+#include "network_simplex_simple_omp.h"
+#include "EMD.h"
+#include <cstdint>
+#include <stdio.h>
+
+int myCMessage(int a, int b) { return a+b; }
+
+int EMD_wrap(int n1, int n2, double *X, double *Y, double *D, double *G,
+                double* alpha, double* beta, double *cost, uint64_t maxIter)  {
+    // beware M and C are stored in row major C style!!!
+
+    using namespace lemon;
+    uint64_t n, m, cur;
+
+    typedef FullBipartiteDigraph Digraph;
+    DIGRAPH_TYPEDEFS(Digraph);
+
+    // Get the number of non zero coordinates for r and c
+    n=0;
+    for (int i=0; i<n1; i++) {
+        double val=*(X+i);
+        if (val>0) {
+            n++;
+        }else if(val<0){
+			return INFEASIBLE;
+		}
+    }
+    m=0;
+    for (int i=0; i<n2; i++) {
+        double val=*(Y+i);
+        if (val>0) {
+            m++;
+        }else if(val<0){
+			return INFEASIBLE;
+		}
+    }
+
+    // Define the graph
+
+    std::vector<uint64_t> indI(n), indJ(m);
+    std::vector<double> weights1(n), weights2(m);
+    Digraph di(n, m);
+    NetworkSimplexSimple<Digraph,double,double, node_id_type> net(di, true, (int) (n + m), n * m, maxIter);
+
+    // Set supply and demand, don't account for 0 values (faster)
+
+    cur=0;
+    for (uint64_t i=0; i<n1; i++) {
+        double val=*(X+i);
+        if (val>0) {
+            weights1[ cur ] = val;
+            indI[cur++]=i;
+        }
+    }
+
+    // Demand is actually negative supply...
+
+    cur=0;
+    for (uint64_t i=0; i<n2; i++) {
+        double val=*(Y+i);
+        if (val>0) {
+            weights2[ cur ] = -val;
+            indJ[cur++]=i;
+        }
+    }
+
+
+    net.supplyMap(&weights1[0], (int) n, &weights2[0], (int) m);
+
+    // Set the cost of each edge
+    int64_t idarc = 0;
+    for (uint64_t i=0; i<n; i++) {
+        for (uint64_t j=0; j<m; j++) {
+            double val=*(D+indI[i]*n2+indJ[j]);
+            net.setCost(di.arcFromId(idarc), val);
+            ++idarc;
+        }
+    }
+
+
+    // Solve the problem with the network simplex algorithm
+
+    int ret=net.run();
+    uint64_t i, j;
+    if (ret==(int)net.OPTIMAL || ret==(int)net.MAX_ITER_REACHED) {
+        *cost = 0;
+        Arc a; di.first(a);
+        for (; a != INVALID; di.next(a)) {
+            i = di.source(a);
+            j = di.target(a);
+            double flow = net.flow(a);
+            *cost += flow * (*(D+indI[i]*n2+indJ[j-n]));
+            *(G+indI[i]*n2+indJ[j-n]) = flow;
+            *(alpha + indI[i]) = -net.potential(i);
+            *(beta + indJ[j-n]) = net.potential(j);
+        }
+
+    }
+
+
+    return ret;
+}
+
+
+
+
+
+
+
+int EMD_wrap_omp(int n1, int n2, double *X, double *Y, double *D, double *G,
+             double* alpha, double* beta, double *cost, uint64_t maxIter, int numThreads)  {
+    // beware M and C are stored in row major C style!!!
+
+    using namespace lemon_omp;
+    uint64_t n, m, cur;
+
+    typedef FullBipartiteDigraph Digraph;
+    DIGRAPH_TYPEDEFS(Digraph);
+
+    // Get the number of non zero coordinates for r and c
+    n=0;
+    for (int i=0; i<n1; i++) {
+        double val=*(X+i);
+        if (val>0) {
+            n++;
+        }else if(val<0){
+            return INFEASIBLE;
+        }
+    }
+    m=0;
+    for (int i=0; i<n2; i++) {
+        double val=*(Y+i);
+        if (val>0) {
+            m++;
+        }else if(val<0){
+            return INFEASIBLE;
+        }
+    }
+
+    // Define the graph
+
+    std::vector<uint64_t> indI(n), indJ(m);
+    std::vector<double> weights1(n), weights2(m);
+    Digraph di(n, m);
+    NetworkSimplexSimple<Digraph,double,double, node_id_type> net(di, true, (int) (n + m), n * m, maxIter, numThreads);
+
+    // Set supply and demand, don't account for 0 values (faster)
+
+    cur=0;
+    for (uint64_t i=0; i<n1; i++) {
+        double val=*(X+i);
+        if (val>0) {
+            weights1[ cur ] = val;
+            indI[cur++]=i;
+        }
+    }
+
+    // Demand is actually negative supply...
+
+    cur=0;
+    for (uint64_t i=0; i<n2; i++) {
+        double val=*(Y+i);
+        if (val>0) {
+            weights2[ cur ] = -val;
+            indJ[cur++]=i;
+        }
+    }
+
+
+    net.supplyMap(&weights1[0], (int) n, &weights2[0], (int) m);
+
+    // Set the cost of each edge
+    int64_t idarc = 0;
+    for (uint64_t i=0; i<n; i++) {
+        for (uint64_t j=0; j<m; j++) {
+            double val=*(D+indI[i]*n2+indJ[j]);
+            net.setCost(di.arcFromId(idarc), val);
+            ++idarc;
+        }
+    }
+
+
+    // Solve the problem with the network simplex algorithm
+
+    int ret=net.run();
+    uint64_t i, j;
+    if (ret==(int)net.OPTIMAL || ret==(int)net.MAX_ITER_REACHED) {
+        *cost = 0;
+        Arc a; di.first(a);
+        for (; a != INVALID; di.next(a)) {
+            i = di.source(a);
+            j = di.target(a);
+            double flow = net.flow(a);
+            *cost += flow * (*(D+indI[i]*n2+indJ[j-n]));
+            *(G+indI[i]*n2+indJ[j-n]) = flow;
+            *(alpha + indI[i]) = -net.potential(i);
+            *(beta + indJ[j-n]) = net.potential(j);
+        }
+
+    }
+
+
+    return ret;
+}