celldega 0.12.0 → 0.13.0-alpha.10

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +133 -44
  2. package/package.json +98 -36
  3. package/src/celldega/static/widget.js +105 -131
package/README.md CHANGED
@@ -1,68 +1,157 @@
1
- # celldega
1
+ ![Celldega banner](public/assets/banner.svg)
2
2
 
3
- ## Documentation
4
- https://broadinstitute.github.io/celldega/
3
+ [![PyPI version](https://badge.fury.io/py/celldega.svg)](https://badge.fury.io/py/celldega)
4
+ [![Python](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
5
+ [![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
6
+ [![Documentation](https://img.shields.io/badge/docs-latest-brightgreen.svg)](https://broadinstitute.github.io/celldega/)
5
7
 
6
- ## Installation
8
+ > **Interactive spatial‑omics analysis & visualisation toolkit for single‑cell and spatial transcriptomics data**
7
9
 
8
- ```sh
10
+ **Celldega** combines scalable computational pipelines with GPU‑accelerated, web‑native visualisations so you can explore **millions of cells and transcripts** directly inside Jupyter Lab, VS Code, or any modern browser. Built for researchers working with Xenium, Visium HD, MERFISH, and other spatial omics technologies.
11
+
12
+ ## 🚀 Quick Start (30 min)
13
+
14
+ ### Installation
15
+
16
+ ```bash
9
17
  pip install celldega
10
18
  ```
11
19
 
12
- ### Note on VIPS Installation
13
- If running on a new Terra.bio workspace you will need to install vips in a startup script (e.g., startup_script.sh) with the following
20
+ ### For Terra.bio Users
14
21
 
15
- ```
16
- #!/bin/bash
17
- apt update
18
- apt install -y libvips
19
- apt install -y libvips-tools
20
- apt install -y libvips-dev
22
+ Add this to your startup script for image processing features ([more info](https://support.terra.bio/hc/en-us/articles/360058193872-Preconfigure-a-Cloud-Environment-with-a-startup-script)):
23
+
24
+ ```bash
25
+ apt update && apt install -y libvips libvips-tools libvips-dev
21
26
  ```
22
27
 
23
- Please see Terra.bio [documentation](https://support.terra.bio/hc/en-us/articles/360058193872-Preconfigure-a-Cloud-Environment-with-a-startup-script) for more information.
28
+ ### Example Usage
24
29
 
25
- ## Development installation
30
+ ```python
31
+ base_url = 'https://raw.githubusercontent.com/broadinstitute/celldega_Xenium_Prime_Human_Skin_FFPE_outs/main/Xenium_Prime_Human_Skin_FFPE_outs'
26
32
 
27
- Create a virtual environment and and install celldega in *editable* mode with the
28
- optional development dependencies:
33
+ landscape_ist = dega.viz.Landscape(
34
+ technology="Xenium",
35
+ ini_zoom=-4.5,
36
+ ini_x=6000,
37
+ ini_y=8000,
38
+ base_url=base_url,
39
+ height=700,
40
+ width=600,
41
+ )
29
42
 
30
- ```sh
31
- python -m venv .venv
32
- source .venv/bin/activate
33
- pip install -e ".[dev]"
43
+ # Alternatively pass an AnnData object to auto-populate cell metadata
44
+ # including "leiden" clusters, colors and UMAP coordinates.
45
+ landscape_from_adata = dega.viz.Landscape(
46
+ base_url=base_url,
47
+ AnnData=adata,
48
+ )
49
+
50
+ file_path = 'https://raw.githubusercontent.com/broadinstitute/celldega_Xenium_Prime_Human_Skin_FFPE_outs/main/Xenium_Prime_Human_Skin_FFPE_outs/df_sig.parquet'
51
+ df = pd.read_parquet(file_path)
52
+
53
+ mat = dega.clust.Matrix(df)
54
+ mat.cluster()
55
+ cgm = dega.viz.Clustergram(matrix=mat)
56
+
57
+ dega.viz.landscape_clustergram(landscape_ist, cgm)
34
58
  ```
35
59
 
36
- You then need to install the JavaScript dependencies and run the development server.
60
+ ![Celldega Demo](public/assets/celldega-demo.png)
61
+
62
+ ## 📖 Documentation & Examples
63
+
64
+ - **[📚 Documentation](https://broadinstitute.github.io/celldega/)** - Complete guides and API reference
65
+ - **[🖼️ Gallery](https://broadinstitute.github.io/celldega/gallery/)** - Interactive visualization demos
66
+ - **[📓 Examples](https://github.com/broadinstitute/celldega/tree/refactor-v0/notebooks)** - Jupyter notebooks you can run locally
67
+ - **[🐍 Python API](https://broadinstitute.github.io/celldega/python/)** - Complete Python API
68
+ - **[🌐 JavaScript API](https://broadinstitute.github.io/celldega/javascript/api/)** - Complete JavaScript API
37
69
 
38
- ```sh
39
- npm install
70
+ ## 🛠️ Development Setup (for Contributors)
71
+
72
+ **Get started contributing in 2 minutes:**
73
+
74
+ ```bash
75
+ git clone https://github.com/broadinstitute/celldega.git
76
+ cd celldega
77
+
78
+ bash ./scripts/setup.sh
79
+
80
+ source dega/bin/activate
40
81
  npm run dev
41
82
  ```
42
83
 
43
- Open `example.ipynb` in JupyterLab, VS Code, or your favorite editor
44
- to start developing. Changes made in `js/` will be reflected
45
- in the notebook.
84
+ See our [Contributing Guide](CONTRIBUTING.md) for detailed instructions.
46
85
 
47
- ### PyPI
48
- Increment version in `project.toml` and
86
+ ## 🏗️ Repository Structure
49
87
 
50
- ```
51
- $ hatch build
52
- $ hatch publish
53
- ```
88
+ | Directory/File | Purpose |
89
+ | --------------- | -------------------------------------- |
90
+ | `src/celldega/` | 🐍 Core Python package |
91
+ | `js/` | 🌐 JavaScript widgets & visualizations |
92
+ | `examples/` | 📓 Jupyter notebook examples |
93
+ | `docs/` | 📚 Documentation source |
94
+ | `js/__tests__/` | 🧪 JS/TS Test suites |
95
+ | `tests/` | 🧪 Python Test suites |
96
+ | `scripts/` | 🔧 Development utilities |
54
97
 
55
- #### Hatch Development
56
- ```
57
- $ hatch env prune # Remove old environments
58
- $ hatch env create # Create a new environment based on pyproject.toml
59
- $ hatch shell # Activate the new environment
60
- ```
98
+ ## 🤝 Contributing
61
99
 
62
- ### NPM
63
- Increment version in `package.json` and
100
+ We welcome contributions from the bio community! Whether you're a:
64
101
 
102
+ - 🧬 **Researcher** - Share datasets, create tutorials, improve documentation
103
+ - 👩‍💻 **Developer** - Add features, fix bugs, optimize performance
104
+ - 📚 **Educator** - Create educational content, examples, workshops
105
+ - 🎨 **Designer** - Improve visualizations, user experience, documentation
106
+
107
+ **Getting started:**
108
+
109
+ 1. Read our [Contributing Guide](CONTRIBUTING.md)
110
+ 2. Check [open issues](https://github.com/broadinstitute/celldega/issues) for ideas
111
+ 3. Join [discussions](https://github.com/broadinstitute/celldega/discussions) to ask questions
112
+
113
+ ## 🆘 Getting Help
114
+
115
+ **Questions about using Celldega?**
116
+
117
+ - 💬 [Discussions](https://github.com/broadinstitute/celldega/discussions) - Ask the community
118
+ - 📖 [Documentation](https://broadinstitute.github.io/celldega/) - Comprehensive guides
119
+ - 📓 [Examples](examples/) - Working code you can adapt
120
+
121
+ **Found a bug or want a feature?**
122
+
123
+ - 🐛 [Report bugs](https://github.com/broadinstitute/celldega/issues/new?template=bug_report.md)
124
+ - ✨ [Request features](https://github.com/broadinstitute/celldega/issues/new?template=feature_request.md)
125
+
126
+ ## 📊 Citation
127
+
128
+ If Celldega helps your research, please cite us:
129
+
130
+ ```bibtex
131
+ @software{celldega,
132
+ title = {Celldega: Interactive spatial‑omics analysis & visualisation toolkit},
133
+ author = {{Broad Institute}},
134
+ url = {https://github.com/broadinstitute/celldega},
135
+ version = {0.12.0},
136
+ year = {2025}
137
+ }
65
138
  ```
66
- $ npm run build
67
- $ npm publish
68
- ```
139
+
140
+ ## 🏛️ About
141
+
142
+ **Celldega** is developed at the [Broad Institute](https://broadinstitute.org/) together with the biology research community. Our mission is to make spatial transcriptomics analysis accessible, interactive, and beautiful.
143
+
144
+ Built on amazing open source tools:
145
+
146
+ - **[deck.gl](https://deck.gl/)** - GPU-accelerated visualizations
147
+ - **[PyArrow](https://arrow.apache.org/docs/python/)** - Fast columnar data processing
148
+ - **[AnnData](https://anndata.readthedocs.io/)** - Annotated data matrices
149
+ - **[SpatialData](https://spatialdata.scverse.org/)** - Spatial omics data structures
150
+
151
+ ---
152
+
153
+ <div align="center" style="padding: 20px;">
154
+
155
+ Made with 🧬 by the [Spatial Technology Platform](https://www.broadinstitute.org/spatial-technology-platform) at the [Broad Institute](https://broadinstitute.org/)
156
+
157
+ </div>
package/package.json CHANGED
@@ -1,38 +1,100 @@
1
1
  {
2
- "name": "celldega",
3
- "version": "0.12.0",
4
- "type": "module",
5
- "scripts": {
6
- "dev": "npm run build -- --sourcemap=inline --watch",
7
- "build": "node build.js",
8
- "watch": "node build.js --watch",
9
- "lint": "eslint js/ --ignore-pattern js/vendor/"
10
- },
11
- "dependencies": {
12
- "@loaders.gl/core": "^4.2.0",
13
- "@luma.gl/core": "^9.0.12",
14
- "@luma.gl/engine": "^9.0.12",
15
- "@luma.gl/shadertools": "^9.0.12",
16
- "@luma.gl/webgl": "^9.0.12",
17
- "apache-arrow": "15.0.2",
18
- "d3": "^7.9.0",
19
- "deck.gl": "^9.0.12",
20
- "@deck.gl-community/editable-layers": "^9.0.3",
21
- "math.gl": "2.3.3"
22
- },
23
- "devDependencies": {
24
- "@eslint/js": "^9.0.0",
25
- "esbuild": "^0.20.0",
26
- "esbuild-plugin-wasm": "^1.1.0",
27
- "eslint": "^9.0.0",
28
- "globals": "^15.0.0"
29
- },
30
- "repository": {
31
- "type": "git",
32
- "url": "https://github.com/broadinstitute/celldega.git"
33
- },
34
- "files": [
35
- "src/celldega/static/*"
36
- ],
37
- "main": "src/celldega/static/widget.js"
2
+ "name": "celldega",
3
+ "version": "0.13.0-alpha.10",
4
+ "type": "module",
5
+ "engines": {
6
+ "node": ">=16",
7
+ "npm": ">=8.0.0"
8
+ },
9
+ "scripts": {
10
+ "dev": "npm run build -- --sourcemap=inline --watch",
11
+ "build": "node build.js",
12
+ "watch": "node build.js --watch",
13
+ "test": "npm run test:js && npm run test:py",
14
+ "test:js": "jest --coverage",
15
+ "test:js:watch": "jest --watch",
16
+ "test:py": "pytest --cov=src/celldega --cov-report=term-missing",
17
+ "test:fast": "npm run test:js:fast && npm run test:py:fast",
18
+ "test:js:fast": "jest",
19
+ "test:py:fast": "pytest",
20
+ "lint": "npm run lint:js && npm run lint:py",
21
+ "lint:js": "eslint js/ --ignore-pattern js/vendor/",
22
+ "lint:js:fix": "eslint js/ --ignore-pattern js/vendor/ --fix",
23
+ "lint:py": "ruff check src/",
24
+ "format": "npm run format:js && npm run format:py",
25
+ "format:js": "prettier --write js/ --ignore-path .prettierignore",
26
+ "format:js:check": "prettier --check js/ --ignore-path .prettierignore",
27
+ "format:py": "ruff format src/",
28
+ "check:js": "npm run lint:js && npm run format:js:check",
29
+ "fix:js": "npm run lint:js:fix && npm run format:js"
30
+ },
31
+ "dependencies": {
32
+ "@deck.gl-community/editable-layers": "^9.0.3",
33
+ "@loaders.gl/core": "^4.2.0",
34
+ "@luma.gl/core": "^9.0.12",
35
+ "@luma.gl/engine": "^9.0.12",
36
+ "@luma.gl/shadertools": "^9.0.12",
37
+ "@luma.gl/webgl": "^9.0.12",
38
+ "apache-arrow": "15.0.2",
39
+ "aws4fetch": "^1.0.20",
40
+ "d3": "^7.9.0",
41
+ "deck.gl": "^9.0.12",
42
+ "math.gl": "2.3.3"
43
+ },
44
+ "devDependencies": {
45
+ "@eslint/js": "^9.0.0",
46
+ "@testing-library/jest-dom": "^6.6.3",
47
+ "esbuild": "^0.20.0",
48
+ "esbuild-plugin-wasm": "^1.1.0",
49
+ "eslint": "^9.27.0",
50
+ "eslint-config-prettier": "^10.1.5",
51
+ "eslint-plugin-import": "^2.31.0",
52
+ "eslint-plugin-prettier": "^5.4.0",
53
+ "globals": "^15.0.0",
54
+ "jest": "^29.7.0",
55
+ "jest-environment-jsdom": "^29.7.0",
56
+ "jsdom": "^26.1.0",
57
+ "prettier": "3.6.2"
58
+ },
59
+ "repository": {
60
+ "type": "git",
61
+ "url": "https://github.com/broadinstitute/celldega.git"
62
+ },
63
+ "files": [
64
+ "src/celldega/static/*"
65
+ ],
66
+ "main": "src/celldega/static/widget.js",
67
+ "prettier": {
68
+ "semi": true,
69
+ "trailingComma": "es5",
70
+ "singleQuote": true,
71
+ "printWidth": 80,
72
+ "tabWidth": 2,
73
+ "useTabs": false,
74
+ "bracketSpacing": true,
75
+ "arrowParens": "always",
76
+ "endOfLine": "lf"
77
+ },
78
+ "jest": {
79
+ "testEnvironment": "jest-environment-jsdom",
80
+ "testMatch": [
81
+ "**/js/**/*.test.js",
82
+ "**/js/**/*.spec.js"
83
+ ],
84
+ "collectCoverageFrom": [
85
+ "js/**/*.js",
86
+ "!js/vendor/**",
87
+ "!js/**/*.test.js",
88
+ "!js/**/*.spec.js"
89
+ ],
90
+ "coverageDirectory": "coverage",
91
+ "coverageReporters": [
92
+ "text",
93
+ "lcov",
94
+ "html"
95
+ ],
96
+ "setupFilesAfterEnv": [
97
+ "<rootDir>/jest.setup.js"
98
+ ]
99
+ }
38
100
  }