Metadata-Version: 2.4
Name: PySCNSlice
Version: 0.1.0
Summary: Automated analysis of bioluminescence and fluorescence time-lapse recordings from organotypic suprachiasmatic nucleus (SCN) slices.
Author-email: Jamie Malcolm <jamiemalcolm12@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://pypi.org/project/PySCNSlice/
Keywords: circadian,suprachiasmatic nucleus,SCN,organotypic slice,bioluminescence,fluorescence,time-lapse,live imaging,neuroscience
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Topic :: Scientific/Engineering :: Image Processing
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24
Requires-Dist: scipy>=1.10
Requires-Dist: tifffile>=2023.7
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Provides-Extra: test
Requires-Dist: pytest>=8; extra == "test"
Dynamic: license-file

# PySCNSlice

Automated analysis of bioluminescence and fluorescence time-lapse recordings from
organotypic suprachiasmatic nucleus (SCN) slices.

The SCN is the master circadian pacemaker of the anterior hypothalamus. Kept alive as
an organotypic slice and imaged for days, it reports its own timekeeping as a movie.
PySCNSlice turns those movies into per-cell and whole-tissue rhythm measurements.

## What is here

The first step, and the one that usually costs a person an afternoon with a mouse:
**finding the tissue**. One call reads a registered recording, draws the accepted
two-lobe outline, rotates it so both lobes sit the same way up in every recording, and
writes a square crop centred on the outline — with no hand-drawn region of interest
anywhere in the chain.

```python
from pyscnslice import automatic_scn_outline

result = automatic_scn_outline(
    "meanred_MCG_04_1_595.tif",
    valid_mask="validfield_MCG_04_1_595.tif",
    output_dir="out",
)
result["output"]           # the two-lobe label image, oriented
result["cropped_output"]   # standard square crop around the SCN centre
result["report"]           # every setting, hash and measurement of that run
```

A registered ImageJ or OME hyperstack works as well as a two-dimensional time mean.
`scn_channel` picks the outline channel and `scn_z` the depth plane, both using
one-based ImageJ numbering; `scn_time` is `"mean"` (the default), `"max"`, or a
one-based frame number such as `320`. Whichever plane is chosen determines one
orientation and one crop, which are then applied to every plane in the stack.

Crops are `"tight"`, `"standard"` (the default), `"wide"`, or an exact
`crop_size_px`. Every preset is checked to keep every outline pixel, and a custom
size that would cut the outline is refused rather than silently clipped.

## The method is frozen

The outline is accepted Round 6 attempt 7 and the orientation accepted Round 9
attempt 6, from the Cry1-DIO-dLuc red-channel tuning project. The public settings
retain the accepted pixel values, because six declared attempts to simplify or
normalise them failed the truth, shape or generalisation gates — a shorter interface
would have meant a less portable method, not a tidier one.

`tests/test_automatic_scn_outline_parity.py` compares **output bytes** against ten
accepted fields rather than comparing behaviour. That evidence lives in the governed
tuning project rather than in this repository; point `PYSCNSLICE_TUNING_ROOT` at it to
run those tests, and without it they skip while the synthetic crop, orientation and
input-safety tests still run.

## Install

```
pip install pyscnslice
```

Only numpy, scipy and tifffile. No plotting stack, no web framework, no audit layer:
outlining a slice should not install any of them.

## Where this came from

These modules lived in [PyMicroglia](https://pypi.org/project/PyMicroglia/) until
2026-08-23. Nothing about outlining a suprachiasmatic nucleus concerns microglia, and
the code was already a leaf — nothing in that package imported it. PyMicroglia keeps
the `automatic_scn_outline` action, which now delegates here:

```
pip install "PyMicroglia[scn]"
```

## Where this is going

PySCNSlice is the SCN layer of an automated Incucyte-to-rhythm pipeline: download,
find the SCN, crop, register and trace, test the rhythm, render videos. See
[`docs/automated-scn-pipeline.md`](docs/automated-scn-pipeline.md) for which package
owns which step and why.

## License

MIT.
