nuclai

A software to identify the presence of cell surface markers based on nuclear signal.

---

This repository was generated with Cookiecutter using @napari's cookiecutter-napari-plugin template.

Installation

If you do not have python installed already, we recommend installing it using the Anaconda distribution. Installing nuclai takes ~5 min and was tested with python 3.12.7.

Virtual environment setup

If you do not use and IDE that handles virtual environments for you (e.g. PyCharm) use your command line application (e.g. Terminal) and one of the many virtual environment tools (see here). We will use conda

1. Create new virtual environment

   conda create -n nuclai python=3.12.7

2. Activate virtual environment

   conda activate nuclai

pip installation

Recommended if you do not want to develop the nuclai code base.

3. Install nuclai

   # update pip
   pip install -U pip==23.2.1
   pip install nuclai

4. (Optional) GPUs greatly speed up training and inference of nuclai and are available for Windows and Linux. Check if your GPU(s) are CUDA compatible (Windows, Linux) and update their drivers if necessary.

5. Install torch/torchvision compatible with your system. nuclai was tested with torch version 2.4.1, torchvision version 0.19.1, and cuda version 12.1.1. Depending on your OS, your CPU or GPU (and CUDA version) the installation may change

# Windows/Linux CPU
pip install torch==2.4.1 torchvision==0.19.1 --index-url https://download.pytorch.org/whl/cpu

# Windows/Linux GPU (CUDA 11.3.X)
pip install torch==2.4.1 torchvision==0.19.1 --index-url https://download.pytorch.org/whl/cu121

# macOS CPU
pip install torch==2.4.1 torchvision==0.19.1

6. Install lightning. nuclai was tested with version 2.4.0.

pip install lightning==2.4.0

Source installation

Installation requires a command line application (e.g. Terminal) with git and python installed. If you operate on Windows we recommend using Ubuntu on Windows. Alternatively, you can install Anaconda and use Anaconda Powershell Prompt. An introductory tutorial on how to use git and GitHub can be found here.

3. (Optional) If you use Anaconda Powershell Prompt, install git through conda

   conda install -c anaconda git

4. clone the repository (consider ssh alternative)

   # change directory
   cd /path/to/directory/to/clone/repository/to
   
   git clone https://github.com/dsethz/nuclai.git

5. Navigate to the cloned directory

   cd nuclai

6. Install nuclai

   # update pip
   pip install -U pip

   1. as a user

      pip install .

   2. as a developer (in editable mode with development dependencies and pre-commit hooks)

      pip install -e ".[testing]"
      pre-commit install

7. (Optional) GPUs greatly speed up training and inference of nuclai and are available for Windows and Linux. Check if your GPU(s) are CUDA compatible (Windows, Linux) and update their drivers if necessary.

8. Install torch/torchvision compatible with your system. nuclai was tested with torch version 2.4.1, torchvision version 0.19.1, and cuda version 12.1.1. Depending on your OS, your CPU or GPU (and CUDA version) the installation may change

# Windows/Linux CPU
pip install torch==2.4.1 torchvision==0.19.1 --index-url https://download.pytorch.org/whl/cpu

# Windows/Linux GPU (CUDA 11.3.X)
pip install torch==2.4.1 torchvision==0.19.1 --index-url https://download.pytorch.org/whl/cu121

# macOS CPU
pip install torch==2.4.1 torchvision==0.19.1

9. Install lightning. nuclai was tested with version 2.4.0.

pip install lightning==2.4.0

Contributing

Contributions are very welcome. Tests can be run with tox, please ensure the coverage at least stays the same before you submit a pull request.

License

Distributed under the terms of the BSD-3 license, "nuclai" is free and open source software

Issues

If you encounter any problems, please file an issue along with a detailed description.