# 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
[JAX](https://github.com/google/jax) and [Flax](https://github.com/google/flax) libraries. 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
[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/Kitware/UPennContrast), a cloud platform for biological image analysis enabling
researchers to interactively visualize their data while leveraging state-of-the-art machine learning algorithms.


## 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
```

By default, this will install the CPU version of JAX. If you would like to run or train `piscis` on a GPU or TPU, follow
[JAX's instructions](https://github.com/google/jax#instructions).


## 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 [preprint](https://doi.org/10.1101/2024.01.31.578123).
> Niu, Z., O’Farrell, A., Li, J., Reffsin, S., Jain, N., Dardani, I., Goyal, Y., & Raj, A. (2024). Piscis: A novel loss
> estimator of the F1 score enables accurate spot detection in fluorescence microscopy images via deep learning.
> _bioRxiv_. https://doi.org/10.1101/2024.01.31.578123
```
@article{Niu2024-Piscis,
    title={Piscis: A novel 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=2024,
    journal="bioRxiv",
    DOI={10.1101/2024.01.31.578123}
}
```

## 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.