Piscis
======

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

Examples
--------

.. image:: /_static/examples.png
   :alt: Examples

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

.. code-block:: bibtex

   @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 <https://raw.githubusercontent.com/zjniu/piscis/main/LICENSE>`_ file shall be included in all copies or substantial portions of the Software.

.. toctree::
   :hidden:

   getting_started
   installation
   inference
   training
   cli