wormscore 0.6.1__tar.gz

wormscore-0.6.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Arjun Bansal
+
+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.

wormscore-0.6.1/PKG-INFO

@@ -0,0 +1,164 @@
+Metadata-Version: 2.4
+Name: wormscore
+Version: 0.6.1
+Summary: Blind scoring of fluorescent neurons in C. elegans confocal stacks, with measurement and genetics statistics.
+Author: Arjun Bansal
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/arjunkai/wormscore
+Project-URL: Documentation, https://github.com/arjunkai/wormscore/blob/main/docs/METHODS.md
+Project-URL: Issues, https://github.com/arjunkai/wormscore/issues
+Project-URL: Releases, https://github.com/arjunkai/wormscore/releases
+Keywords: C. elegans,worm,neuron,blind scoring,fluorescence,microscopy,confocal,penetrance
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Classifier: Topic :: Scientific/Engineering :: Image Processing
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.26
+Requires-Dist: scipy>=1.11
+Requires-Dist: pillow>=10
+Requires-Dist: liffile>=2026.10.14
+Requires-Dist: czifile>=2026.10.14
+Requires-Dist: tifffile>=2024.1
+Requires-Dist: imagecodecs>=2024.1
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pyinstaller>=6.10; extra == "dev"
+Dynamic: license-file
+
+# wormscore
+
+Blind scoring of fluorescent neurons in *C. elegans*, with measurement and genetics statistics.
+Built for scoring reporter neurons (normal / dim / missing) in confocal z-stacks. Nothing is tied
+to one neuron, marker or microscope: those are settings in each project's `config.json`, so other
+organisms work the same way.
+
+- **Blind:** every image gets a random code. Genotypes and file names stay in a sealed key
+  until you finish scoring.
+- **Fixed display:** every image from the same microscope is shown with the same brightness range.
+  You can page through z-planes and overlay brightfield.
+- **Measured, not decided:** suggested cell bodies and your drawn regions are measured (peak, mean,
+  local background, sharpest plane, saturation). The numbers are written to files and never shown
+  while you score. The software never labels a cell normal, dim or missing.
+- **Traceable:** every number links to the exact file, path, series and SHA-256 checksum it came from.
+- **Reproducible:** every parameter and software version is appended to `log.md` on each run.
+- **Local:** runs on your computer only. Nothing is uploaded.
+
+Supported raw formats: Leica `.lif`, Zeiss `.czi`, OME-TIFF (including Micro-Manager style files with
+a `.companion.ome`). Channel identity (marker vs brightfield) is read from metadata, never guessed.
+
+## Install
+
+**Windows, no Python needed:** download `wormscore-windows.zip` from the Releases page, unzip it,
+and double-click `wormscore.exe`.
+
+**With Python 3.12 or newer:**
+
+```
+pip install git+https://github.com/arjunkai/wormscore.git
+```
+
+This installs a `wormscore` command and a `wormscore-launcher` window.
+
+## Try it in two minutes (simulated data)
+
+```
+wormscore demo my_demo
+wormscore inventory my_demo
+wormscore prepare my_demo
+wormscore app my_demo
+```
+
+`demo` writes 20 simulated worm heads (controls with two normal cells; mutants with cells that are
+normal, dim or missing at random) and a `demo_truth.csv` you can check your calls against later.
+In the launcher window the same steps are buttons: **Demo... > 1. Scan data > 2. Build blind set > 3. Score**.
+
+**Real worms:** `wormscore demo my_demo --real` (or Yes in the launcher's Demo dialog) downloads four
+L1 heads with an endogenous GFP reporter, about 150 MB, from
+[Sun and Hobert 2021](https://doi.org/10.1038/s41586-021-04071-4)
+([Zenodo 5602160](https://doi.org/10.5281/zenodo.5602160), CC BY 4.0). Each file is checked against its
+MD5 from the Zenodo record and cached in `%LOCALAPPDATA%\wormscore\demo_cache` (`~/.cache` elsewhere).
+The two reporters stand in for two genotypes; both are normal animals, so this is for practice.
+The images are not part of this repository.
+
+## Using it on your own images
+
+1. **Copy your data** to a local folder (not a synced cloud folder if the data is not yours to share):
+   `wormscore copy D:\from\drive C:\data\my_copy` copies every file, checks each one by SHA-256 and
+   makes the copies read-only.
+2. **Make a project:** `wormscore init C:\projects\my_project`, then edit `config.json`:
+   point `sources` at your images, write genotype rules, and name your neurons. See
+   [`examples/config_example.json`](https://github.com/arjunkai/wormscore/blob/main/examples/config_example.json).
+3. **Scan:** `wormscore inventory my_project` lists every file (`outputs/manifest.csv`: raw image,
+   duplicate, derived projection, reference, hidden system file) and every image with its metadata
+   and channel identity (`outputs/inventory.csv`). Check the flags column.
+4. **Build the blind set:** `wormscore prepare my_project` applies the inclusion rules, assigns codes,
+   finds and measures suggested cells, and writes the sealed key. Excluded images and the reasons are
+   in `outputs/excluded.csv`. To leave out images by name (for example a plate with the wrong
+   reporter), add `"exclude": [{"match": "*pattern*", "reason": "why"}]` to that source.
+   Images taken after scoring started can be added with `wormscore prepare my_project --add-new-images`
+   (scan first): existing codes stay the same and new images get codes after the last one.
+5. **Score:** `wormscore app my_project`. For each image: answer any yellow questions, score each
+   neuron, save, then outline each cell body (or accept a suggestion) and save regions.
+6. **Unblind after scoring:** `wormscore unblind my_project --i-have-finished-scoring`. Writes
+   `outputs/unblinded/merged.csv` (scores + numbers + key, one row per image), a summary, and results
+   tables: `per_neuron.csv` (one row per animal and neuron, for plotting), `penetrance.csv` (animals with
+   0, 1, 2 ... affected neurons) and `fisher_tests.csv` (Fisher's exact within each microscope,
+   Bonferroni-corrected). Set `unblinding.reference_genotype` in `config.json` to test against a control.
+   Optional, off unless set in `unblinding`: `question_outcomes` turns the per-neuron questions into
+   the same penetrance and Fisher tables (for example "process defect" when a dendrite question is
+   answered "no"), and `interaction` tests a double mutant against the value two single mutants predict
+   (Product model by default) with a binomial test. Also optional: a secondary definition of "affected"
+   (descriptive, within one microscope), planned comparisons, one-sided tests, labelled sources, and
+   comparisons across microscopes for chosen measures (with warnings). All of these are recorded as an
+   analysis plan before scoring and locked once scoring starts. See [docs/METHODS.md](https://github.com/arjunkai/wormscore/blob/main/docs/METHODS.md#8-unblinding).
+   `methods_text.md` is a draft Methods paragraph on blinding, measurement and statistics; fill in the
+   `blinding` section of `config.json` (who coded, who scored) or edit the [brackets] it leaves.
+
+## Project folder
+
+| Path | Contents | Open while scoring? |
+|---|---|---|
+| `config.json` | every parameter | yes |
+| `log.md` | every run: parameters, software versions, counts | yes |
+| `outputs/manifest.csv`, `inventory.csv`, `excluded.csv` | what was found and what was left out | yes |
+| `outputs/auto_measurements.csv` | numbers for suggested spots | avoid until done |
+| `blind/` | images for scoring, named by code | used by the app |
+| `scoring/` | your scores, regions and their measurements | scores yes; avoid `roi_measurements.csv` |
+| `key/` | code to file, genotype, settings | **no, not until scoring is finished** |
+
+## How it works
+
+See [docs/METHODS.md](https://github.com/arjunkai/wormscore/blob/main/docs/METHODS.md) for every step in plain language, suitable for adapting into
+a Methods section, including the measurement definitions and their limits.
+
+## Development
+
+```
+pip install -e .[dev]
+pytest
+```
+
+The tests build a simulated project and check the measurements, the blinding (no genotype or file
+name reaches the scoring page), code stability, the unblinding locks and traceability. Leica and
+Zeiss readers are checked against real files locally; real images are never committed.
+
+Build the Windows app: `packaging\build_windows.bat`.
+
+## Privacy
+
+This repository contains code only. `.gitignore` excludes image formats, keys, scores and outputs.
+Do not commit or upload data that belongs to someone else.
+
+## License and citation
+
+MIT License (see [LICENSE](https://github.com/arjunkai/wormscore/blob/main/LICENSE)). If you use wormscore in research, please cite it: GitHub's
+"Cite this repository" button (from [CITATION.cff](https://github.com/arjunkai/wormscore/blob/main/CITATION.cff)) gives the reference.
+
+wormscore reads Leica files with [liffile](https://github.com/cgohlke/liffile) and Zeiss files with
+[czifile](https://github.com/cgohlke/czifile) (both BSD-3). The Windows app bundles these and other
+libraries; their licenses are in `THIRD_PARTY_LICENSES.txt` next to `wormscore.exe`.

wormscore-0.6.1/README.md

@@ -0,0 +1,132 @@
+# wormscore
+
+Blind scoring of fluorescent neurons in *C. elegans*, with measurement and genetics statistics.
+Built for scoring reporter neurons (normal / dim / missing) in confocal z-stacks. Nothing is tied
+to one neuron, marker or microscope: those are settings in each project's `config.json`, so other
+organisms work the same way.
+
+- **Blind:** every image gets a random code. Genotypes and file names stay in a sealed key
+  until you finish scoring.
+- **Fixed display:** every image from the same microscope is shown with the same brightness range.
+  You can page through z-planes and overlay brightfield.
+- **Measured, not decided:** suggested cell bodies and your drawn regions are measured (peak, mean,
+  local background, sharpest plane, saturation). The numbers are written to files and never shown
+  while you score. The software never labels a cell normal, dim or missing.
+- **Traceable:** every number links to the exact file, path, series and SHA-256 checksum it came from.
+- **Reproducible:** every parameter and software version is appended to `log.md` on each run.
+- **Local:** runs on your computer only. Nothing is uploaded.
+
+Supported raw formats: Leica `.lif`, Zeiss `.czi`, OME-TIFF (including Micro-Manager style files with
+a `.companion.ome`). Channel identity (marker vs brightfield) is read from metadata, never guessed.
+
+## Install
+
+**Windows, no Python needed:** download `wormscore-windows.zip` from the Releases page, unzip it,
+and double-click `wormscore.exe`.
+
+**With Python 3.12 or newer:**
+
+```
+pip install git+https://github.com/arjunkai/wormscore.git
+```
+
+This installs a `wormscore` command and a `wormscore-launcher` window.
+
+## Try it in two minutes (simulated data)
+
+```
+wormscore demo my_demo
+wormscore inventory my_demo
+wormscore prepare my_demo
+wormscore app my_demo
+```
+
+`demo` writes 20 simulated worm heads (controls with two normal cells; mutants with cells that are
+normal, dim or missing at random) and a `demo_truth.csv` you can check your calls against later.
+In the launcher window the same steps are buttons: **Demo... > 1. Scan data > 2. Build blind set > 3. Score**.
+
+**Real worms:** `wormscore demo my_demo --real` (or Yes in the launcher's Demo dialog) downloads four
+L1 heads with an endogenous GFP reporter, about 150 MB, from
+[Sun and Hobert 2021](https://doi.org/10.1038/s41586-021-04071-4)
+([Zenodo 5602160](https://doi.org/10.5281/zenodo.5602160), CC BY 4.0). Each file is checked against its
+MD5 from the Zenodo record and cached in `%LOCALAPPDATA%\wormscore\demo_cache` (`~/.cache` elsewhere).
+The two reporters stand in for two genotypes; both are normal animals, so this is for practice.
+The images are not part of this repository.
+
+## Using it on your own images
+
+1. **Copy your data** to a local folder (not a synced cloud folder if the data is not yours to share):
+   `wormscore copy D:\from\drive C:\data\my_copy` copies every file, checks each one by SHA-256 and
+   makes the copies read-only.
+2. **Make a project:** `wormscore init C:\projects\my_project`, then edit `config.json`:
+   point `sources` at your images, write genotype rules, and name your neurons. See
+   [`examples/config_example.json`](https://github.com/arjunkai/wormscore/blob/main/examples/config_example.json).
+3. **Scan:** `wormscore inventory my_project` lists every file (`outputs/manifest.csv`: raw image,
+   duplicate, derived projection, reference, hidden system file) and every image with its metadata
+   and channel identity (`outputs/inventory.csv`). Check the flags column.
+4. **Build the blind set:** `wormscore prepare my_project` applies the inclusion rules, assigns codes,
+   finds and measures suggested cells, and writes the sealed key. Excluded images and the reasons are
+   in `outputs/excluded.csv`. To leave out images by name (for example a plate with the wrong
+   reporter), add `"exclude": [{"match": "*pattern*", "reason": "why"}]` to that source.
+   Images taken after scoring started can be added with `wormscore prepare my_project --add-new-images`
+   (scan first): existing codes stay the same and new images get codes after the last one.
+5. **Score:** `wormscore app my_project`. For each image: answer any yellow questions, score each
+   neuron, save, then outline each cell body (or accept a suggestion) and save regions.
+6. **Unblind after scoring:** `wormscore unblind my_project --i-have-finished-scoring`. Writes
+   `outputs/unblinded/merged.csv` (scores + numbers + key, one row per image), a summary, and results
+   tables: `per_neuron.csv` (one row per animal and neuron, for plotting), `penetrance.csv` (animals with
+   0, 1, 2 ... affected neurons) and `fisher_tests.csv` (Fisher's exact within each microscope,
+   Bonferroni-corrected). Set `unblinding.reference_genotype` in `config.json` to test against a control.
+   Optional, off unless set in `unblinding`: `question_outcomes` turns the per-neuron questions into
+   the same penetrance and Fisher tables (for example "process defect" when a dendrite question is
+   answered "no"), and `interaction` tests a double mutant against the value two single mutants predict
+   (Product model by default) with a binomial test. Also optional: a secondary definition of "affected"
+   (descriptive, within one microscope), planned comparisons, one-sided tests, labelled sources, and
+   comparisons across microscopes for chosen measures (with warnings). All of these are recorded as an
+   analysis plan before scoring and locked once scoring starts. See [docs/METHODS.md](https://github.com/arjunkai/wormscore/blob/main/docs/METHODS.md#8-unblinding).
+   `methods_text.md` is a draft Methods paragraph on blinding, measurement and statistics; fill in the
+   `blinding` section of `config.json` (who coded, who scored) or edit the [brackets] it leaves.
+
+## Project folder
+
+| Path | Contents | Open while scoring? |
+|---|---|---|
+| `config.json` | every parameter | yes |
+| `log.md` | every run: parameters, software versions, counts | yes |
+| `outputs/manifest.csv`, `inventory.csv`, `excluded.csv` | what was found and what was left out | yes |
+| `outputs/auto_measurements.csv` | numbers for suggested spots | avoid until done |
+| `blind/` | images for scoring, named by code | used by the app |
+| `scoring/` | your scores, regions and their measurements | scores yes; avoid `roi_measurements.csv` |
+| `key/` | code to file, genotype, settings | **no, not until scoring is finished** |
+
+## How it works
+
+See [docs/METHODS.md](https://github.com/arjunkai/wormscore/blob/main/docs/METHODS.md) for every step in plain language, suitable for adapting into
+a Methods section, including the measurement definitions and their limits.
+
+## Development
+
+```
+pip install -e .[dev]
+pytest
+```
+
+The tests build a simulated project and check the measurements, the blinding (no genotype or file
+name reaches the scoring page), code stability, the unblinding locks and traceability. Leica and
+Zeiss readers are checked against real files locally; real images are never committed.
+
+Build the Windows app: `packaging\build_windows.bat`.
+
+## Privacy
+
+This repository contains code only. `.gitignore` excludes image formats, keys, scores and outputs.
+Do not commit or upload data that belongs to someone else.
+
+## License and citation
+
+MIT License (see [LICENSE](https://github.com/arjunkai/wormscore/blob/main/LICENSE)). If you use wormscore in research, please cite it: GitHub's
+"Cite this repository" button (from [CITATION.cff](https://github.com/arjunkai/wormscore/blob/main/CITATION.cff)) gives the reference.
+
+wormscore reads Leica files with [liffile](https://github.com/cgohlke/liffile) and Zeiss files with
+[czifile](https://github.com/cgohlke/czifile) (both BSD-3). The Windows app bundles these and other
+libraries; their licenses are in `THIRD_PARTY_LICENSES.txt` next to `wormscore.exe`.

wormscore-0.6.1/pyproject.toml

@@ -0,0 +1,55 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "wormscore"
+version = "0.6.1"
+description = "Blind scoring of fluorescent neurons in C. elegans confocal stacks, with measurement and genetics statistics."
+keywords = ["C. elegans", "worm", "neuron", "blind scoring", "fluorescence", "microscopy", "confocal", "penetrance"]
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Arjun Bansal" }]
+requires-python = ">=3.12"
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Science/Research",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Topic :: Scientific/Engineering :: Bio-Informatics",
+  "Topic :: Scientific/Engineering :: Image Processing",
+]
+dependencies = [
+  "numpy>=1.26",
+  "scipy>=1.11",
+  "pillow>=10",
+  "liffile>=2026.10.14",
+  "czifile>=2026.10.14",
+  "tifffile>=2024.1",
+  "imagecodecs>=2024.1",
+]
+
+[project.urls]
+Homepage = "https://github.com/arjunkai/wormscore"
+Documentation = "https://github.com/arjunkai/wormscore/blob/main/docs/METHODS.md"
+Issues = "https://github.com/arjunkai/wormscore/issues"
+Releases = "https://github.com/arjunkai/wormscore/releases"
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "pyinstaller>=6.10"]
+
+[project.scripts]
+wormscore = "wormscore.cli:main"
+
+[project.gui-scripts]
+wormscore-launcher = "wormscore.launcher:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+wormscore = ["static/*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

wormscore-0.6.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

wormscore-0.6.1/src/wormscore/__init__.py

@@ -0,0 +1,3 @@
+"""wormscore: blind scoring and fluorescence measurement of neurons in confocal stacks."""
+
+__version__ = "0.6.1"

wormscore-0.6.1/src/wormscore/cli.py

@@ -0,0 +1,81 @@
+"""Command line: wormscore <command> <project folder> ..."""
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from . import __version__
+
+
+def main(argv=None):
+    p = argparse.ArgumentParser(prog="wormscore", description="Blind scoring and measurement of neurons in confocal stacks.")
+    p.add_argument("--version", action="version", version=f"wormscore {__version__}")
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    s = sub.add_parser("init", help="create a project folder with a config.json to edit")
+    s.add_argument("project")
+    s.add_argument("--name", default="My project")
+    s = sub.add_parser("demo", help="create a demo project with simulated worms")
+    s.add_argument("project")
+    s.add_argument("--n", type=int, default=10, help="simulated worms per genotype")
+    s.add_argument("--real", action="store_true",
+                   help="download 4 real worm heads (about 150 MB, CC BY 4.0) instead of simulating")
+    s = sub.add_parser("copy", help="copy a data folder and verify every file by SHA-256")
+    s.add_argument("source")
+    s.add_argument("destination")
+    s = sub.add_parser("inventory", help="list every file and image in the project's sources")
+    s.add_argument("project")
+    s = sub.add_parser("prepare", help="build the blind image set, key and automatic measurements")
+    s.add_argument("project")
+    s.add_argument("--reassign-codes", action="store_true", help="new codes (only allowed before any scoring)")
+    s.add_argument("--add-new-images", dest="add", action="store_true",
+                   help="code only images not yet in the key; existing codes are kept")
+    s = sub.add_parser("app", help="open the scoring app")
+    s.add_argument("project")
+    s.add_argument("--port", type=int, default=8765)
+    s.add_argument("--no-browser", action="store_true")
+    s = sub.add_parser("unblind", help="join scores, measurements and the key (after scoring)")
+    s.add_argument("project")
+    s.add_argument("--i-have-finished-scoring", dest="finished", action="store_true")
+    s.add_argument("--anyway", action="store_true", help="unblind below the planned minimum number of scores")
+
+    a = p.parse_args(argv)
+    try:
+        if a.cmd == "init":
+            from .config import template
+            proj = Path(a.project)
+            proj.mkdir(parents=True, exist_ok=True)
+            cfg = proj / "config.json"
+            if cfg.exists():
+                sys.exit(f"{cfg} already exists; not overwriting.")
+            cfg.write_text(json.dumps(template(a.name), indent=2), encoding="utf-8")
+            print(f"Created {cfg}. Edit 'sources' to point at your images, then run 'wormscore inventory {proj}'.")
+        elif a.cmd == "demo":
+            if a.real:
+                from .realdemo import make_real_demo
+                make_real_demo(a.project)
+            else:
+                from .demo import make_demo
+                make_demo(a.project, n_per_group=a.n)
+            print(f"Next: wormscore inventory {a.project} && wormscore prepare {a.project} && wormscore app {a.project}")
+        elif a.cmd == "copy":
+            from .copydata import copy_verified
+            copy_verified(a.source, a.destination)
+        elif a.cmd == "inventory":
+            from .pipeline import inventory
+            inventory(a.project)
+        elif a.cmd == "prepare":
+            from .pipeline import prepare
+            prepare(a.project, reassign=a.reassign_codes, add=a.add)
+        elif a.cmd == "app":
+            from .server import serve
+            serve(a.project, port=a.port, open_browser=not a.no_browser)
+        elif a.cmd == "unblind":
+            from .unblind import unblind
+            unblind(a.project, finished=a.finished, anyway=a.anyway)
+    except FileNotFoundError as exc:
+        sys.exit(str(exc))
+
+
+if __name__ == "__main__":
+    main()