first release of the plugin

.github/workflows/ci.yaml

@@ -0,0 +1,15 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  tests:
+    uses: ./.github/workflows/tests.yaml
+  lint:
+    uses: ./.github/workflows/lint.yaml
+  format:
+    uses: ./.github/workflows/format.yaml

.github/workflows/format.yaml

@@ -0,0 +1,25 @@
+name: format
+
+on: [workflow_call]
+
+jobs:
+  format:
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11"]
+        os: [ubuntu-22.04]
+    runs-on: ${{ matrix.os }}
+
+    steps:
+      - uses: actions/checkout@v3
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v4
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install project
+        run: pip install .[formatting]
+      - name: Run codespell
+        run: codespell --enable-colors
+      - name: Run ruff
+        run: ruff format --diff .

.github/workflows/lint.yaml

@@ -0,0 +1,25 @@
+name: lint
+
+on: [workflow_call]
+
+jobs:
+  lint:
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11"]
+        os: [ubuntu-22.04]
+    runs-on: ${{ matrix.os }}
+
+    steps:
+      - uses: actions/checkout@v3
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v4
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install project
+        run: pip install .[linting]
+      - name: Run mypy on Python ${{ matrix.python-version }} on ${{ matrix.os }}
+        run: mypy
+      - name: Run ruff on Python ${{ matrix.python-version }} on ${{ matrix.os }}
+        run: ruff check .

.github/workflows/tests.yaml

@@ -0,0 +1,23 @@
+name: Tests 
+
+on: [workflow_call]
+
+jobs:
+  tests:
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: [ "3.10", "3.11" ]
+        os: [  ubuntu-latest, macos-latest, windows-latest, ubuntu-20.04 ]
+    runs-on: ${{ matrix.os }}
+
+    steps:
+      - uses: actions/checkout@v3
+      - name: Set up Python ${{ matrix.python-version }} on ${{ matrix.os }}
+        uses: actions/setup-python@v4
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install project
+        run: python -m pip install .[testsuite]
+      - name: Run unit tests on Python ${{ matrix.python-version }} on ${{ matrix.os }}
+        run: pytest tests -vv --cov

.gitignore

@@ -0,0 +1,9 @@
+# build-related
+build/
+*.egg-info/
+*.pyc
+.venv/
+__pycache__/
+
+# test-related
+.coverage*

CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [v0.1.0] - 2024-04-20
+
+### Added
+* This package, first release

docs/README.md

@@ -0,0 +1,18 @@
+## Documentation
+Here you will find both a [user guide](./using-the-plugin.md) and [development documentation](./development.md).
+
+### Installation and environment
+This project uses a Nix shell to provide a development environment. 
+To use this plugin, you have at least two options.
+
+__Nix shell (preferred)__
+
+If you've installed the [Nix package manager](https://nixos.org/download/) installed, then from the this project's [root folder](../), you can simply launch the Nix shell with `nix-shell`, and you should have everything you need ready to go. 
+Note that in general, we use this on Mac machines with relatively new processors. 
+If something doesn't work for you, and especially if you're using this on different hardware, please let us know by opening a ticket on our [issue tracker](https://github.com/gerlichlab/looptrace-loci-vis/issues). 
+Please open a ticket even if you're able to resolve the problem yourself, as it will help us define the environment in a way that's compatible with a wider variety of hardwares.
+If you'd like, you may even open a pull request to suggest an improvement to our environment definition.
+
+__Virtual environment (e.g. `virtualenv`)__
+
+If you're not inclined to use Nix, ensure that you've installed `virtualenv` (e.g., `brew install virtualenv` on a Mac), and that you have Python available (e.g., `brew install [email protected]`). Then you may create and activate a virtual environment, into which you may install this project. Simply run `pip install .` from this project's [root folder](../).

docs/development.md

@@ -0,0 +1,10 @@
+## Development
+First, please refer to the general [installation and environment](./README.md#installation-and-environment).
+
+By default, with `nix-shell`, you should have all the dependencies you'll need not only to _use_ this plugin, but also to _develop_ on it. 
+In other words, dependencies to do things like run tests, run linter(s), and run type checking should all be provided. 
+If you try and that's not the case, please check the [Issue Tracker](https://github.com/gerlichlab/looptrace-loci-vis/issues).
+If an issue's open for what you're experiencing, please upvote the initial description of the issue and/or comment on the ticket.
+
+### Testing, formatting, and linting
+The various tests run against the project can be found in the [GitHub actions workflows](../.github/workflows/).

docs/using-the-plugin.md

@@ -0,0 +1,53 @@
+## Viewing locus spots
+First, check the general information about [installation and environment](./README.md#installation-and-environment).
+
+### Quickstart
+To visualise the locus spots, you need to __drag-and-drop a _folder___ into an active Napari window. This folder will have been produced directly by `looptrace`, or you'll create it by moving files created by `looptrace`.
+
+That folder must...
+* be named like `PXXXX`, where `XXXX` is the 4-digit representation of the 1-based field of view from which data came, with the 4 digits being left-padded with 0.
+* contain __3 items__:
+    * ZARR (folder) array with name matching the folder it's in (up to the `.zarr` extension)
+    * `*.qcfail.csv`: CSV file with coordinate of spot fit centers, and column encoding QC fail reasons
+    * `*.qcpass.csv`: same as QC fail file, but without column for failures
+
+These properties should be entirely or nearly satisfied by a run of `looptrace`. 
+At most, only these steps should be required to prepare the data:
+1. Create a new folder, ideally just locally on your desktop, to organise the data.
+1. Within that folder, create a subfolder named like `PXXXX` for each FOV you want to visualised.
+1. Copy, for each FOV you want to view, the ZARR and QC pass/fail CSV files from the locus spot images visualisation folder made by `looptrace`, into the corresponding FOV subfolder.
+
+For the image layer, you'll want to select "continuous" rather than "once" for the "auto-contrast" setting in the upper-left area of the Napari window. For each field of view, you'll need to clear the layers from the active Napari window, then drag in the next folder.
+
+### What you should see / notice
+* __Sliders__: A Napari window with three sliders (trace ID on bottom, timepoint in middle, $z$ slice on top) should be displayed. 
+* __Colors__: Yellow indicates a locus spot that passed all QC filters, and blue indicates that the spot failed at least one QC filter. 
+* __Sizes and Shapes__: A larger star indicates that you're viewing the $z$-slice corresponding to the truncation-toward-0 of the $z$-coordinate of the centroid of the Gaussian fit to the locus spot pixels. A smaller point/circle is shown when you're in a non-central $z$-slice. Text is shown for QC-fail points
+* __Text__: Text labels encode [QC failure reasons](#qc-failure-codes).
+
+### QC failure codes
+* `O`: "*O*ut-of-bounds" -- the locus point's center is literally outside the bounding box, or within one standard deviation of its fit to at least one of the boundaries
+* `R`: "far from *R*egion center" -- the locus spot's center is too far from its region barcode's spot's center
+* `S`: "*S*ignal-to-noise (too low)" -- the fit's signal-to-noise ratio is too low.
+* `xy`: The fit's too diffuse in `xy`.
+* `z`: The fit's too diffuse in `z`.
+
+### Details and troubleshooting
+* Each relevant file, regardless of which kind of data are inside, should have a basename like `PXXXX`, where `XXXX` corresponds to the 1-based integer index of the field of view, left-padded with zeroes, e.g. `P0001`.
+* Each image file should have a `.zarr` extension.
+* Each points file should have a `.qc(pass|fail).csv` extension.
+* Each `.zarr` should either have a `.zarray` immediately inside it, or have a single `0` subfolder which has a `.zarray` inside it.
+* Each points file should have __NO HEADER__. See [the examples](../looptrace_loci_vis/examples/).
+* Ensure that "continuous" rather than "once" is selected for the "auto-contrast" setting in the upper-left area of the Napari window.
+
+### Frequently asked questions (FAQ)
+1. __Why blue and yellow as the colors for QC-fail and QC-pass (respectively) spots?__\
+    This pair of colors is relatively tends to be seen roughly the same (or at least to maintain sharp contrast) by a colorblind person as for a non-colorblind person.
+1. __Why are the layers named the same (e.g., P0001[2], P0001[1], P0001s) but with little boxed numbers?__\
+    The name for each layer comes from the file or folder represented (in the case of this plugin, corresponding to the field of view of the data). The bracketed numbers just distinguish the layers but may be regarded as arbitrary.
+1. __Why are some points a different shape or size?__\
+    A star is represents the center of the locus point's Gaussian fit when viewing the $z$-slice corresponding to the truncated-toward-0 $z$-coordinate of the center of that fit. In all other slices/planes, a circle/dot is used instead of a star.
+1. __Why are some slices entirely empty?__\
+    This can happen when the bounding box for the region went outside actual image boundaries, resulting in a case of unextractable data.
+1. __Why do some slices lack a point at all?__\
+    This can happen when the center of the Gaussian fit to the pixel volume's data lies outside that volume ($z$-stack / rectangular prism).

looptrace_loci_vis/__init__.py

@@ -0,0 +1,3 @@
+"""Napari plugin for visualising locus-specific points from looptrace"""
+
+__version__ = "0.1.0"

looptrace_loci_vis/examples/P0001.qcfail.csv

@@ -0,0 +1,10 @@
+0,13,5.880338307654485,12.20211975317036,10.728294496728491,S
+0,17,10.594366532607864,10.95875680073854,20.711938561802768,R;S;xy;z
+0,47,10.198132167665957,14.398450914314138,15.378219719077295,R
+0,48,0.7173811741523715,13.999908344240598,2.011625563698183,R;z
+0,49,6.274792365451074,14.440034853392085,8.81613597404698,S
+0,69,10.03907938905064,18.453449673327853,7.594187495036839,R;S;xy;z
+0,71,8.157075382512406,12.780500232574296,3.1916456736466685,R
+0,74,7.03360935199292,15.324188332927145,3.6995859572616823,xy
+0,76,2.426576702500344,20.546530442060508,2.151493771689803,R;S;xy;O
+0,77,6.0415531254567885,13.910733825016758,10.238202728231837,S

looptrace_loci_vis/examples/P0001.qcpass.csv

@@ -0,0 +1,10 @@
+0,1,5.81567065413679,19.474750228527004,12.175479170066252
+0,2,4.127040930402973,16.836316423238255,16.211982617584344
+0,3,4.694554107453964,16.789722139429465,12.25402999243208
+0,4,4.813168873918884,15.256065437706804,17.11569530869283
+0,5,4.548093164740155,14.213239208919436,12.147029706673518
+0,6,5.541487916309182,16.87867172260054,11.99790265928896
+0,7,5.363507239961485,12.895567140315253,11.943658590602544
+0,8,6.516566467869967,11.700423462604856,13.31509301523442
+0,9,5.419675410652808,13.538758567521947,11.329204727566513
+0,10,6.9955481900291785,11.640001066231846,11.540667655397932

looptrace_loci_vis/examples/README.md

@@ -0,0 +1,2 @@
+## Examples
+This folder contains examples of some of the relevant files for using this plugin.

looptrace_loci_vis/napari.yaml

@@ -0,0 +1,16 @@
+name: looptrace-loci-vis
+contributions:
+  commands:
+  - id: looptrace-loci-vis.read_looptrace_locus_points
+    title: Read looptrace locus-specific image points data and overlays
+    python_name: looptrace_loci_vis.reader:get_reader
+  readers:
+  - command: looptrace-loci-vis.read_looptrace_locus_points
+    filename_patterns:
+    # - '*.qcfail.csv'
+    # - '*.qcpass.csv'
+    # - '*.qc_fail.csv'
+    # - '*.qc_pass.csv'
+    #accepts_directories: false
+      - 'P*'
+    accepts_directories: true