Piscis 1.0.0
An automatic deep learning algorithm for spot detection in fluorescence microscopy images.
Requires Python: <4,>=3.7
Keywords: machine learning, deep learning, spot detection, fluorescence microscopy

# Piscis

<img src="https://raw.githubusercontent.com/zjniu/piscis/main/docs/source/_static/logo.svg" width="40%" max-width="250" alt="Piscis" align="right">

`piscis` is an automatic deep learning algorithm for spot detection, written in Python using the
[PyTorch](https://pytorch.org/) framework. It is named after the Latin word for fish, as it was designed specifically
for microscopy images generated by RNA fluorescence _in situ_ hybridization (FISH). However, we have found it to be
useful for other imaging methods, such as immunofluorescence (IF) and FISH-based spatial transcriptomics. To learn more
about `piscis`, please read our _Cell Systems_
[paper](https://www.cell.com/cell-systems/abstract/S2405-4712(25)00281-9) or bioRxiv
[preprint](https://doi.org/10.1101/2024.01.31.578123).

This Python package allows users to apply pre-trained models from [Hugging Face](https://huggingface.co/wniu/Piscis) to
both single plane images and z-stacks or to train new models using custom datasets. It provides a simple API for both
training and inference that can be used in traditional Python scripts or [Jupyter](https://jupyter.org/) notebook
environments such as on [Google Colab](https://colab.research.google.com/). It also provides a command line interface
for those who prefer the terminal. For a user-friendly graphical user interface, we have implemented `piscis` as a
[Docker image](https://github.com/arjunrajlaboratory/ImageAnalysisProject/tree/master/workers/annotations/piscis) for
[NimbusImage](https://github.com/arjunrajlaboratory/NimbusImage), a cloud platform for biological image analysis
enabling researchers to interactively visualize their data while leveraging state-of-the-art machine learning
algorithms.

For more information, please refer to the comprehensive documentation available at https://piscis.netlify.app.


## Examples

<img src="https://raw.githubusercontent.com/zjniu/piscis/main/docs/source/_static/examples.png" width="750" alt="Examples">


## Installation

Install `piscis` from [PyPI](https://pypi.org/project/piscis/) with `pip`.
```
pip install piscis
```


## Usage

If you want to use `piscis` with its Python API, check out the [inference example](notebooks/run_piscis.ipynb) and
[training example](notebooks/train_piscis.ipynb) notebooks.

If you want to use `piscis` with its command line interface, run the following commands.
```
# Run Piscis.
piscis predict INPUT_PATH OUTPUT_PATH [OPTIONS]

# Train Piscis.
piscis train MODEL_NAME DATASET_PATH [OPTIONS]
```
To see the full list of options, run `piscis predict --help` or `piscis train --help`.

## Citation

If you use `piscis` in your research, please cite our
[paper](https://www.cell.com/cell-systems/abstract/S2405-4712(25)00281-9).
> Niu, Z., O’Farrell, A., Li, J., Reffsin, S., Jain, N., Dardani, I., Goyal, Y., & Raj, A. (2025). Piscis: A loss
estimator of the F1 score enables accurate spot detection in fluorescence microscopy images via deep learning.
> _Cell Systems_. https://doi.org/10.1016/j.cels.2025.101448
```
@article{Niu2025-Piscis,
    title={Piscis: A loss estimator of the F1 score enables accurate spot detection in fluorescence microscopy images via deep learning},
    author={Niu, Zijian and O’Farrell, Aoife and Li, Jingxin and Reffsin, Sam and Jain, Naveen and Dardani, Ian and Goyal, Yogesh and Raj, Arjun},
    year=2025,
    journal="Cell Systems",
    DOI={10.1016/j.cels.2025.101448}
}
```

## License

`piscis` is licensed under the MIT License. The copyright and permission notices found in the [LICENSE](LICENSE) file
shall be included in all copies or substantial portions of the Software.