Spotiflow

https://github.com/weigertlab/spotiflow
Admin
Deep learning-based, threshold-agnostic spot detection method for 2D and 3D fluorescence microscopy...
Tokens:18,852
Snippets:184
Trust Score:8.1
License:MIT
Update:4 months ago
Show doc for...
Tokens:
Raw
### Install Spotiflow with Pip

Source: https://github.com/weigertlab/spotiflow/blob/main/docs/source/installation.md

Install the spotiflow library using pip after setting up the environment and PyTorch. Windows users should install Build Tools for Visual Studio beforehand.

```bash
$ pip install spotiflow
```

--------------------------------

### Install Documentation Dependencies

Source: https://github.com/weigertlab/spotiflow/blob/main/README.md

Install the 'docs' extras for Spotiflow using pip. This is required for building the project's documentation.

```console
pip install -e ".[docs]"
```

--------------------------------

### Install napari-spotiflow Plugin

Source: https://github.com/weigertlab/spotiflow/blob/main/docs/source/napari.md

Install the napari-spotiflow plugin using pip. Ensure this is done in the environment where Spotiflow is installed.

```console
(spotiflow) $ pip install napari-spotiflow
```

--------------------------------

### Install Testing Dependencies

Source: https://github.com/weigertlab/spotiflow/blob/main/README.md

Install the 'testing' extras for Spotiflow using pip. This command should be run after cloning the repository and navigating into the project directory.

```console
cd spotiflow
pip install -e ".[testing]"
```

--------------------------------

### Install PyTorch

Source: https://github.com/weigertlab/spotiflow/blob/main/README.md

Install the PyTorch library, which is a dependency for Spotiflow. Refer to the PyTorch website for CUDA-specific installation commands if you have a compatible GPU.

```console
pip install torch
```

--------------------------------

### Build Documentation

Source: https://github.com/weigertlab/spotiflow/blob/main/README.md

Build the HTML documentation for Spotiflow using Sphinx. Navigate to the 'docs' directory and run the sphinx-build command. This requires the 'docs' extras to be installed.

```console
cd spotiflow/docs
sphinx-build -M html source build
```

--------------------------------

### Train Spotiflow Model with Specific Parameters via CLI

Source: https://github.com/weigertlab/spotiflow/blob/main/docs/source/train.md

Example of training a 2-channel 3D Spotiflow model for 100 epochs using the CLI.

```console
spotiflow-train /path/to/spots_data -o /my/trained/model --is-3d True --num-epochs 100 --in-channels 2
```

--------------------------------

### Create Conda Environment

Source: https://github.com/weigertlab/spotiflow/blob/main/docs/source/installation.md

Create and activate a new conda environment for spotiflow. Ensure you have conda or miniforge installed.

```bash
$ conda create -n spotiflow python=3.12
$ conda activate spotiflow
```

--------------------------------

### Install Spotiflow via Pip

Source: https://github.com/weigertlab/spotiflow/blob/main/README.md

Install the Spotiflow package using pip after PyTorch has been installed. Ensure you have the latest Build Tools for Visual Studio installed if you are on Windows.

```console
pip install spotiflow
```

--------------------------------

### Install Spotiflow with Conda

Source: https://github.com/weigertlab/spotiflow/blob/main/docs/source/installation.md

Install spotiflow and create a new conda environment simultaneously using conda-forge. This method is available for Linux/MacOS users.

```bash
$ conda create -n spotiflow -c conda-forge spotiflow python=3.12
```

--------------------------------

### Get CLI Help

Source: https://github.com/weigertlab/spotiflow/blob/main/docs/source/cli.md

Access the help message for the `spotiflow-predict` command to see all available options and usage details.

```console
spotiflow-predict -h
```

--------------------------------

### Install PyTorch with Pip

Source: https://github.com/weigertlab/spotiflow/blob/main/docs/source/installation.md

Install the PyTorch library using pip. For users with a CUDA-capable GPU on Linux/Windows, consult the PyTorch website for specific installation commands based on your CUDA version.

```bash
$ pip install torch
```

--------------------------------

### Load Necessary Libraries for Spotiflow

Source: https://github.com/weigertlab/spotiflow/blob/main/examples/2_inference.ipynb

Imports essential libraries for image processing, visualization, and the Spotiflow model. Ensure these are installed before running.

```python
from spotiflow.model import Spotiflow
from spotiflow.sample_data import test_image_hybiss_2d
from skimage.io import imread
import matplotlib.pyplot as plt
import numpy as np
```

--------------------------------

### Get CLI Help for Spotiflow Train

Source: https://github.com/weigertlab/spotiflow/blob/main/docs/source/train.md

View available arguments and options for the spotiflow-train CLI command by running with the --help flag.

```console
spotiflow-train --help
```

--------------------------------

### Custom Spotiflow Model Configuration

Source: https://github.com/weigertlab/spotiflow/blob/main/examples/1_train.ipynb

Example of how to define a custom configuration for the Spotiflow model. Uncomment and modify parameters like `in_channels` or `sigma` as needed.

```python
# config = SpotiflowModelConfig(
#     in_channels=3, # e.g. for RGB
#     sigma=5., # for larger spots
# )
```

--------------------------------

### Create and Activate Conda Environment

Source: https://github.com/weigertlab/spotiflow/blob/main/README.md

Before installing Spotiflow, create and activate a new conda environment. This ensures compatibility with supported Python versions.

```console
conda create -n spotiflow python=3.12
conda activate spotiflow
```

--------------------------------

### spotiflow.sample_data.test_image_hybiss_2d

Source: https://github.com/weigertlab/spotiflow/blob/main/docs/source/index.md

Provides access to a sample 2D Hybiss image dataset for testing and examples.

```APIDOC
## Function spotiflow.sample_data.test_image_hybiss_2d

### Description
Loads and returns a sample 2D image dataset representative of the Hybiss format, useful for testing inference or training pipelines.

### Usage
```python
from spotiflow.sample_data import test_image_hybiss_2d

# Example usage (details not provided in source)
# hybiss_image = test_image_hybiss_2d()
```
```

--------------------------------

### Basic Spotiflow Model Training via API

Source: https://github.com/weigertlab/spotiflow/blob/main/docs/source/train.md

Train a Spotiflow model using the Python API. This involves getting data, initializing the model, and fitting it with training and validation sets.

```python
from spotiflow.model import Spotiflow
from spotiflow.utils import get_data

# Get the data
train_imgs, train_spots, val_imgs, val_spots = get_data("/path/to/spots_data")

# Initialize the model
model = Spotiflow()

# Train and save the model
model.fit(
    train_imgs,
    train_spots,
    val_imgs,
    val_spots,
    save_dir="/path/to/my_trained_model",
)
```

--------------------------------

### Install Spotiflow via Conda

Source: https://github.com/weigertlab/spotiflow/blob/main/README.md

For Linux/MacOS users, Spotiflow can be installed using conda from the conda-forge channel. Note that this version might be outdated compared to the pip version.

```console
conda install -c conda-forge spotiflow
```

--------------------------------

### Visualize 3D Data with Napari

Source: https://github.com/weigertlab/spotiflow/blob/main/examples/4_train_3d.ipynb

Visualizes the first training volume and its corresponding spots using napari. This snippet includes error handling for cases where napari is not installed.

```python
try:
    import napari
    viewer = napari.Viewer(ndisplay=3)
    viewer.add_image(trX[0], name="Training volume", colormap="gray")
    viewer.add_points(trY[0], name="Training spots", face_color="orange", edge_color="orange", size=5, symbol="ring")
except ImportError as _:
    print("napari not installed, skipping visualization")
    viewer = None
except Exception as e:
    raise e
```

--------------------------------

### Docker Pull Command

Source: https://github.com/weigertlab/spotiflow/blob/main/README.md

Pull the Spotiflow Docker container from Dockerhub. This image can be used for running inference without local installation.

```console
docker pull weigertlab/spotiflow:main
```

--------------------------------

### Visualize Prediction Results

Source: https://github.com/weigertlab/spotiflow/blob/main/examples/4_train_3d.ipynb

Visualizes the test volume and the predicted spots using napari, provided that napari is installed and the viewer is active. Clears existing layers before adding new ones.

```python
if viewer is not None:
    while len(viewer.layers) > 0:
        viewer.layers.pop()
    viewer.add_image(testX[0], name="Test volume", colormap="gray")
    viewer.add_points(test_pred, name="Predicted test spots", face_color="orange", edge_color="orange", size=5, symbol="ring")
```

--------------------------------

### Load 3D Dataset

Source: https://github.com/weigertlab/spotiflow/blob/main/examples/4_train_3d.ipynb

Loads a 3D synthetic dataset for training, validation, and testing. Alternatively, provides commented-out examples for loading custom data from a specified folder.

```python
trX, trY, valX, valY, testX, testY = load_dataset("synth_3d", include_test=True)
# trX, trY, valX, valY, testX, testY = get_data("/FOLDER/WITH/DATA", include_test=True, is_3d=True) # with test data
# trX, trY, valX, valY = get_data("/FOLDER/WITH/DATA", include_test=False, is_3d=True) # without test data
```

--------------------------------

### Fine-tuning via CLI

Source: https://github.com/weigertlab/spotiflow/blob/main/docs/source/finetune.md

This snippet shows how to initiate fine-tuning of a Spotiflow model from an existing model using the command line interface. It specifies the training data path, the output directory for the fine-tuned model, and the base model to fine-tune from.

```APIDOC
## Fine-tuning via CLI

### Description
Initiates fine-tuning of a Spotiflow model from a pre-trained model using the command line.

### Command
```console
spotiflow-train /path/to/spots_data -o /path/to/my_finetuned_model --finetune-from general
```

### Parameters
- `/path/to/spots_data`: Path to the directory containing the training dataset.
- `-o /path/to/my_finetuned_model`: Path to the directory where the fine-tuned model will be saved.
- `--finetune-from general`: Specifies the base model to fine-tune from (e.g., 'general').

### Notes
Additional training parameters (e.g., epochs, learning rate) can be passed. Refer to `spotiflow-train -h` for a full list of arguments.
```

--------------------------------

### Instantiate Spotiflow Model

Source: https://github.com/weigertlab/spotiflow/blob/main/examples/1_train.ipynb

Initializes the Spotiflow model with default configuration parameters. This is the first step before training.

```python
model = Spotiflow()
```

--------------------------------

### Configure and Instantiate 3D Model

Source: https://github.com/weigertlab/spotiflow/blob/main/examples/4_train_3d.ipynb

Sets up the configuration for a 3D Spotiflow model, specifying it's a 3D model and the grid downsampling factor.

```python
config = SpotiflowModelConfig(
    is_3d=True, # 3D model
    grid=(2, 2, 2), # predict on a downsampled grid, this is the value used in the paper
)
model = Spotiflow(config=config)
```

--------------------------------

### Load Dataset for Finetuning

Source: https://github.com/weigertlab/spotiflow/blob/main/examples/3_finetune.ipynb

Loads the MERFISH dataset for demonstration. Replace 'merfish' with your dataset name or provide a custom path using get_data.

```python
trX, trY, valX, valY, testX, testY = load_dataset("merfish", include_test=True)
# trX, trY, valX, valY, testX, testY = get_data("YOUR/DATA/PATH/HERE", include_test=True)
```

--------------------------------

### Spotiflow.from_folder

Source: https://github.com/weigertlab/spotiflow/blob/main/docs/source/api.md

Loads a pretrained Spotiflow model from a specified local folder. Allows configuration of inference mode, checkpoint selection, and device mapping.

```APIDOC
## Spotiflow.from_folder

### Description
Loads a pretrained model from a local folder.

### Method
classmethod

### Parameters
#### Path Parameters
- **pretrained_path** (path) - Required - Path to the model folder.

#### Other Parameters
- **inference_mode** (bool) - Optional - Whether to set the model in eval mode. Defaults to True.
- **which** (string) - Optional - Which checkpoint to load. Defaults to 'best'.
- **map_location** (string) - Optional - Device string to load the model to. Defaults to 'auto'.
- **verbose** (bool) - Optional - Verbosity flag. Defaults to False.

### Returns
- **Self** - The loaded model.
```

--------------------------------

### Configure and Train Spotiflow Model

Source: https://github.com/weigertlab/spotiflow/blob/main/examples/1_train.ipynb

Set the save directory and training configuration, then fit the model to the training data. Adjust `num_epochs` for debugging or longer training.

```python
save_folder = "models/synth_complex" # change to where you want to store the model
train_config = SpotiflowTrainingConfig(
    num_epochs=2, # very small number of epochs for debugging purposes
)
model.fit(
    trX,
    trY,
    valX,
    valY,
    save_dir=save_folder,
    train_config=train_config,
)
```

--------------------------------

### Finetune Spotiflow Model

Source: https://github.com/weigertlab/spotiflow/blob/main/examples/3_finetune.ipynb

Configure and execute the finetuning process for a Spotiflow model. Adjust `num_epochs` and set `finetuned_from` in `SpotiflowTrainingConfig`. The `fit` method is then called with the training data and configuration.

```python
save_folder = "models/merfish_finetuned_from_synth" # change to where you want to store the model
train_config = SpotiflowTrainingConfig(
    num_epochs=30,
    finetuned_from="synth_complex"
)
model.fit(
    trX,
    trY,
    valX,
    valY,
    save_dir=save_folder,
    train_config=train_config,
)
```

--------------------------------

### Clone Spotiflow Repository

Source: https://github.com/weigertlab/spotiflow/blob/main/README.md

Clone the Spotiflow Git repository to your local machine. This is the first step for setting up the development environment.

```console
git clone git@github.com:weigertlab/spotiflow.git
```

--------------------------------

### Load Pre-trained Spotiflow Model

Source: https://github.com/weigertlab/spotiflow/blob/main/examples/3_finetune.ipynb

Loads a pre-trained Spotiflow model, 'synth_complex', for finetuning. The model will be downloaded automatically on first use. If you have a custom-trained model, you can specify its path.

```python
model = Spotiflow.from_pretrained("synth_complex")
```

--------------------------------

### Fine-tune Model using CLI

Source: https://github.com/weigertlab/spotiflow/blob/main/docs/source/finetune.md

Use the spotiflow-train command with the --finetune-from argument to fine-tune a model. Specify the data path, output directory, and the pre-trained model to use.

```console
spotiflow-train /path/to/spots_data -o /path/to/my_finetuned_model --finetune-from general
```

--------------------------------

### SpotsDataset.from_folder

Source: https://github.com/weigertlab/spotiflow/blob/main/docs/source/api.md

Builds a SpotsDataset instance by loading images and centers from a specified folder on disk. It handles normalization and can optionally compute flow.

```APIDOC
## classmethod from_folder

### Description
Build dataset from folder. Images and centers are loaded from disk and normalized.

### Method
classmethod

### Parameters
#### Path Parameters
- **path** () - Required - Path to folder containing images (with given extensions) and centers.

#### Optional Parameters
- **augmenter** () - Optional - Augmenter function.
- **downsample_factors** () - Optional - Downsample factors. Defaults to (1,).
- **sigma** () - Optional - Sigma of Gaussian kernel to generate heatmap. Defaults to 1.
- **image_extensions** () - Optional - Image extensions to look for in images. Defaults to (“tif”, “tiff”, “png”, “jpg”, “jpeg”).
- **mode** () - Optional - Mode of heatmap generation. Defaults to “max”.
- **max_files** () - Optional - Maximum number of files to load. Defaults to None (all of them).
- **compute_flow** () - Optional - Whether to compute flow from centers. Defaults to False.
- **normalizer** () - Optional - Normalizer function. Defaults to “auto” (percentile-based normalization with p_min=1 and p_max=99.8).
- **random_state** () - Optional - Random state used when shuffling file names when “max_files” is not None. Defaults to None.
- **add_class_label** () - Optional - Whether to add class label. Defaults to True.
- **grid** () - Optional - Grid parameter.

### Returns
Dataset instance.

### Return type
Self
```

--------------------------------

### Fine-tuning via Python API

Source: https://github.com/weigertlab/spotiflow/blob/main/docs/source/finetune.md

This snippet demonstrates how to fine-tune a Spotiflow model using the Python API. It includes loading data, initializing a pre-trained model, and then training and saving the fine-tuned model to a specified directory.

```APIDOC
## Fine-tuning via Python API

### Description
Fine-tunes a pre-trained Spotiflow model on a custom dataset using the Python API.

### Method
```python
from spotiflow.model import Spotiflow
from spotiflow.utils import get_data

# Get the data
train_imgs, train_spots, val_imgs, val_spots = get_data("/path/to/spots_data")

# Initialize the model from a pre-trained checkpoint
model = Spotiflow.from_pretrained(
    "general",
    inference_mode=False,
)

# Train and save the fine-tuned model
model.fit(
    train_imgs,
    train_spots,
    val_imgs,
    val_spots,
    save_dir="/path/to/my_finetuned_model",
)
```

### Parameters
- `get_data("/path/to/spots_data")`: Loads training and validation image and spot data from the specified directory.
- `Spotiflow.from_pretrained("general", inference_mode=False)`: Initializes the Spotiflow model, loading the 'general' pre-trained weights. `inference_mode=False` is crucial for training.
- `model.fit(...)`: Trains the model using the provided data.
  - `train_imgs`, `train_spots`: Training images and corresponding spot annotations.
  - `val_imgs`, `val_spots`: Validation images and corresponding spot annotations.
  - `save_dir="/path/to/my_finetuned_model"`: Directory to save the fine-tuned model.

### Notes
- To fine-tune from a previously trained custom model, use `Spotiflow.from_folder("/path/to/your/custom/model")` instead of `from_pretrained()`.
- Training customization options from `train.md#customizing-the-training` are applicable.
- Model architecture cannot be changed during fine-tuning.
```

--------------------------------

### Load Spotiflow Model

Source: https://github.com/weigertlab/spotiflow/blob/main/examples/3_finetune.ipynb

Loads a Spotiflow model from a specified folder. Ensure the folder path is correct.

```python
model = Spotiflow.from_folder("YOUR_MODEL_FOLDER_HERE")
```

--------------------------------

### Initialize 3D Spotiflow Model with Configuration

Source: https://github.com/weigertlab/spotiflow/blob/main/docs/source/train.md

To train a 3D model using the API, initialize a SpotiflowModelConfig object with is_3d=True and pass it to the Spotiflow constructor.

```python
from spotiflow.model import SpotiflowModelConfig

# Create the model config
model_config = SpotiflowModelConfig(
    is_3d=True,
    grid=2, # subsampling factor for prediction
    # you can pass other arguments here
)

model = Spotiflow(model_config)
```

--------------------------------

### Import Necessary Libraries

Source: https://github.com/weigertlab/spotiflow/blob/main/examples/4_train_3d.ipynb

Imports the core classes and functions required for Spotiflow model training and data handling.

```python
from spotiflow.model import Spotiflow, SpotiflowModelConfig
from spotiflow.sample_data import load_dataset
from spotiflow.utils import get_data
```

--------------------------------

### Spots3DDataset.from_folder

Source: https://github.com/weigertlab/spotiflow/blob/main/docs/source/api.md

Builds a Spots3DDataset by loading images and centers from a specified folder on disk. It supports various image formats and includes options for data augmentation, downsampling, and normalization.

```APIDOC
## classmethod Spots3DDataset.from_folder

### Description
Builds a dataset from a folder containing images and centers. The data is loaded from disk and normalized.

### Method
classmethod

### Parameters
#### Path Parameters
- **path** (string) - Required - Path to folder containing images (with given extensions) and centers.

#### Optional Parameters
- **augmenter** (function) - Optional - Augmenter function.
- **downsample_factors** (tuple) - Optional - Downsample factors. Defaults to (1,).
- **sigma** (float) - Optional - Sigma of Gaussian kernel to generate heatmap. Defaults to 1.0.
- **image_extensions** (tuple) - Optional - Image extensions to look for in images. Defaults to ('tif', 'tiff', 'png', 'jpg', 'jpeg').
- **mode** (string) - Optional - Mode of heatmap generation. Defaults to 'max'.
- **max_files** (int) - Optional - Maximum number of files to load. Defaults to None.
- **compute_flow** (bool) - Optional - Whether to compute flow from centers. Defaults to False.
- **normalizer** (string or function) - Optional - Normalizer function. Defaults to 'auto'.
- **random_state** (int or None) - Optional - Random state used when shuffling file names when 'max_files' is not None. Defaults to None.
- **add_class_label** (bool) - Optional - Whether to add class labels. Defaults to False.
- **grid** (any) - Optional - Grid parameter.

### Returns
Dataset instance.

### Return type
Self
```

--------------------------------

### Load a Trained Spotiflow Model

Source: https://github.com/weigertlab/spotiflow/blob/main/docs/source/train.md

Load a previously trained Spotiflow model from a specified directory using the from_folder class method.

```python
model = Spotiflow.from_folder("/my/trained/model")
```

--------------------------------

### Load Spotiflow Model

Source: https://github.com/weigertlab/spotiflow/blob/main/examples/2_inference.ipynb

Loads a pre-trained 'general' Spotiflow model. The model will be downloaded automatically on first use. Alternatively, load a custom-trained model from a specified folder.

```python
model = Spotiflow.from_pretrained("general")
# model = Spotiflow.from_folder("YOUR_MODEL_FOLDER_HERE")
```

--------------------------------

### Spotiflow.from_pretrained

Source: https://github.com/weigertlab/spotiflow/blob/main/docs/source/api.md

Loads a pretrained Spotiflow model by its name. Supports specifying the checkpoint, device, cache directory, and additional keyword arguments.

```APIDOC
## Spotiflow.from_pretrained

### Description
Loads a pretrained model with a given name.

### Method
classmethod

### Parameters
#### Path Parameters
- **pretrained_name** (string) - Required - Name of the pretrained model to be loaded.

#### Other Parameters
- **inference_mode** (bool) - Optional - Whether to set the model in eval mode. Defaults to True.
- **which** (string) - Optional - Which checkpoint to load. Defaults to 'best'.
- **map_location** (string) - Optional - Device string to load the model to. Defaults to 'auto'.
- **cache_dir** (path) - Optional - Directory to cache the model. Defaults to None.
- **verbose** (bool) - Optional - Verbosity flag. Defaults to True.

### Returns
- **Self** - The loaded model.
```

--------------------------------

### Configure Spotiflow Model Architecture for Input Channels

Source: https://github.com/weigertlab/spotiflow/blob/main/docs/source/train.md

Create a SpotiflowModelConfig object to customize the model architecture, such as setting the number of input channels. This is necessary for 3D models.

```python
from spotiflow.model import SpotiflowModelConfig

# Create the model config
model_config = SpotiflowModelConfig(
    in_channels=3,
    # you can pass other arguments here
)
model = Spotiflow(model_config)
```

--------------------------------

### Load Dataset for Spotiflow Training

Source: https://github.com/weigertlab/spotiflow/blob/main/examples/1_train.ipynb

Loads a pre-defined dataset or a custom dataset for training Spotiflow models. Supports loading with or without test data.

```python
trX, trY, valX, valY, testX, testY = load_dataset("synth_complex", include_test=True)
# trX, trY, valX, valY, testX, testY = get_data("/FOLDER/WITH/DATA", include_test=True) # with test data
# trX, trY, valX, valY = get_data("/FOLDER/WITH/DATA", include_test=False) # without test data
```

--------------------------------

### Docker Run Command for Inference

Source: https://github.com/weigertlab/spotiflow/blob/main/README.md

Run the Spotiflow Docker container to perform inference on image files. Mount local input folders to the container's input directory using the -v flag. This command supports CPU inference only.

```console
docker run -it -v [/local/input/folder]:/spotiflow/input weigertlab/spotiflow:main spotiflow-predict input/your_file.tif -o .
```

--------------------------------

### Fine-tune Model using Python API

Source: https://github.com/weigertlab/spotiflow/blob/main/docs/source/finetune.md

Load a pre-trained model using Spotiflow.from_pretrained and then train it on custom data using the fit method. Ensure to specify the save directory for the fine-tuned model.

```python
from spotiflow.model import Spotiflow
from spotiflow.utils import get_data

# Get the data
train_imgs, train_spots, val_imgs, val_spots = get_data("/path/to/spots_data")

# Initialize the model
model = Spotiflow.from_pretrained(
    "general",
    inference_mode=False,
)

# Train and save the model
model.fit(
    train_imgs,
    train_spots,
    val_imgs,
    val_spots,
    save_dir="/path/to/my_finetuned_model",
)
```

--------------------------------

### Train Spotiflow Model via CLI

Source: https://github.com/weigertlab/spotiflow/blob/main/docs/source/train.md

Use the spotiflow-train command to train a model from the CLI. Specify the data directory and output directory for the trained model.

```console
spotiflow-train /path/to/spots_data -o /path/to/my_trained_model
```

--------------------------------

### Visualize Training Images and Annotations

Source: https://github.com/weigertlab/spotiflow/blob/main/examples/1_train.ipynb

Displays the first two training images with their corresponding annotations using the `plot_image_with_spots` function. Change indices to view other images.

```python
plot_image_with_spots(trX[0], trY[0], title="Training image")
plot_image_with_spots(trX[1], trY[1], title="Training image")
```

--------------------------------

### Load Custom Spotiflow Model

Source: https://github.com/weigertlab/spotiflow/blob/main/docs/source/index.md

Load a custom trained Spotiflow model from a specified folder path. This is an alternative to using pretrained models.

```python
# Load a custom model
model = Spotiflow.from_folder("/path/to/model")
```

--------------------------------

### Run Inference using CLI

Source: https://github.com/weigertlab/spotiflow/blob/main/README.md

Execute inference on an image or a folder of images using the spotiflow-predict CLI command. The 'general' pretrained model is used by default.

```console
spotiflow-predict PATH
```

--------------------------------

### Train a 3D Model using CLI

Source: https://github.com/weigertlab/spotiflow/blob/main/README.md

Train a 3D model by adding the `--3d True` flag to the spotiflow-train CLI command. This flag enables 3D processing for the training.

```console
spotiflow-train INPUT_DIR -o OUTPUT_DIR --3d True
```

--------------------------------

### spotiflow.model.config.SpotiflowTrainingConfig

Source: https://github.com/weigertlab/spotiflow/blob/main/docs/source/index.md

Configuration class for training Spotiflow models, detailing parameters for the training process.

```APIDOC
## Class spotiflow.model.config.SpotiflowTrainingConfig

### Description
Specifies the configuration options for training a Spotiflow model, including hyperparameters and data settings.

### Usage
```python
from spotiflow.model.config import SpotiflowTrainingConfig

# Example usage (details not provided in source)
# training_config = SpotiflowTrainingConfig(epochs=100, learning_rate=0.001)
```
```

--------------------------------

### Predict Spots using Python API

Source: https://github.com/weigertlab/spotiflow/blob/main/docs/source/index.md

Load an image, a pretrained Spotiflow model, predict spots, and save the results to a CSV file. The predict method expects a numpy array.

```python
from skimage.io import imread
from spotiflow.model import Spotiflow
from spotiflow.utils import write_coords_csv


# Load the desired image
img = imread("/path/to/your/image")

# Load a pretrained model
model = Spotiflow.from_pretrained("general")

# Predict spots
spots, details = model.predict(img) # predict expects a numpy array

# spots is a numpy array with shape (n_spots, 2)
# details contains additional information about the prediction, like the predicted heatmap, the probability per spot, the flow field, etc.

# Save the results to a CSV file
write_coords_csv(spots, "/path/to/save/spots.csv")
```

--------------------------------

### Specify Pretrained Model with CLI

Source: https://github.com/weigertlab/spotiflow/blob/main/docs/source/cli.md

To use a specific pretrained model, use the `--pretrained-model` flag. This command shows how to specify a model other than the default 'general' model.

```console
$ spotiflow-predict PATH --pretrained-model MODEL_NAME
```

--------------------------------

### spotiflow.model.config.SpotiflowModelConfig

Source: https://github.com/weigertlab/spotiflow/blob/main/docs/source/index.md

Configuration class for Spotiflow models, specifying parameters for model loading and initialization.

```APIDOC
## Class spotiflow.model.config.SpotiflowModelConfig

### Description
Defines the configuration parameters for a Spotiflow model, such as paths to model weights or specific model settings.

### Usage
```python
from spotiflow.model.config import SpotiflowModelConfig

# Example usage (details not provided in source)
# model_config = SpotiflowModelConfig(model_path='path/to/model')
```
```

--------------------------------

### SpotsDataset Constructor

Source: https://github.com/weigertlab/spotiflow/blob/main/docs/source/api.md

Initializes a SpotsDataset object, which represents a dataset of spots. It can be initialized with images and centers, or with image files. Various parameters control data augmentation, downsampling, heatmap generation, and normalization.

```APIDOC
## SpotsDataset(
    images=None,
    centers=None,
    augmenter=None,
    downsample_factors=(1,),
    sigma=1.0,
    mode='max',
    compute_flow=False,
    image_files=None,
    normalizer='auto',
    defer_normalization=False,
    add_class_label=True,
    grid=None
)

### Description
Constructor for the SpotsDataset class.

### Parameters
#### Path Parameters
- **images** (Sequence) - Sequence of images.
- **centers** (Sequence) - Sequence of center coordinates.
- **augmenter** (Callable, optional) - Augmenter function. If given, function arguments should two (first image, second spots). Defaults to None.
- **downsample_factors** (Sequence, optional) - Downsample factors. Defaults to (1,).
- **sigma** (float, optional) - Sigma of Gaussian kernel to generate heatmap. Defaults to 1.0.
- **mode** (str, optional) - Mode of heatmap generation. Defaults to 'max'.
- **compute_flow** (bool, optional) - Whether to compute flow from centers. Defaults to False.
- **image_files** (Sequence, optional) - Sequence of image filenames. If the dataset was not constructed from a folder, this will be None. Defaults to None.
- **normalizer** (str, optional) - Normalizer function. Defaults to 'auto' (percentile-based normalization with p_min=1 and p_max=99.8).
- **defer_normalization** (bool, optional) - Whether to defer normalization to data[i] (if normalizer is not None) to save memory. Defaults to False.
- **add_class_label** (bool, optional) - Whether to add a class label. Defaults to True.
- **grid** (Any, optional) - Grid parameter. Defaults to None.

### Returns
- **SpotsDataset** - An instance of the SpotsDataset class.
```

--------------------------------

### spotiflow.sample_data.test_image_synth_3d

Source: https://github.com/weigertlab/spotiflow/blob/main/docs/source/index.md

Provides access to a sample synthetic 3D image dataset.

```APIDOC
## Function spotiflow.sample_data.test_image_synth_3d

### Description
Loads and returns a sample synthetic 3D image dataset, suitable for testing 3D-specific functionalities.

### Usage
```python
from spotiflow.sample_data import test_image_synth_3d

# Example usage (details not provided in source)
# synth_3d_image = test_image_synth_3d()
```
```

--------------------------------

### Spots3DDataset

Source: https://github.com/weigertlab/spotiflow/blob/main/docs/source/api.md

Initializes a 3D spot dataset using pre-loaded images and centers. It supports augmentations and various loading configurations for 3D data.

```APIDOC
### class Spots3DDataset

### Description
3D spot dataset class instantiated with loaded images and centers.

For multi-channel images, DHWC (ZYXC) format is expected, but they will be converted to CDHW (CZYX) patches.

### Parameters
#### Path Parameters
- **images** () - Required
- **centers** () - Required

#### Optional Parameters
- **augmenter** () - Optional - Augmenter function.
- **downsample_factors** () - Optional - Downsample factors. Defaults to (1,).
- **sigma** () - Optional - Sigma of Gaussian kernel to generate heatmap. Defaults to 1.
- **mode** () - Optional - Mode of heatmap generation. Defaults to "max".
- **compute_flow** () - Optional - Whether to compute flow from centers. Defaults to False.
- **image_files** () - Optional - Image files.
- **normalizer** () - Optional - Normalizer function. Defaults to "auto".
- **defer_normalization** () - Optional - Whether to defer normalization. Defaults to False.
- **add_class_label** () - Optional - Whether to add class label. Defaults to True.
- **grid** () - Optional - Grid parameter.
```

--------------------------------

### Spots3DDataset Constructor

Source: https://github.com/weigertlab/spotiflow/blob/main/docs/source/api.md

Initializes a Spots3DDataset object. This constructor allows for the creation of a dataset from images and centers, with options for augmentation, downsampling, flow computation, and normalization.

```APIDOC
## Spots3DDataset.__init__

### Description
Initializes a Spots3DDataset object with provided images, centers, and various optional parameters for data processing and augmentation.

### Method
__init__

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **images** (Sequence) - Required - Sequence of images.
- **centers** (Sequence) - Required - Sequence of center coordinates.
- **augmenter** (function) - Optional - Augmenter function. If given, function arguments should two (first image, second spots). Defaults to None.
- **downsample_factors** (tuple) - Optional - Downsample factors. Defaults to (1,).
- **sigma** (float) - Optional - Sigma of Gaussian kernel to generate heatmap. Defaults to 1.0.
- **mode** (string) - Optional - Mode of heatmap generation. Defaults to 'max'.
- **compute_flow** (bool) - Optional - Whether to compute flow from centers. Defaults to False.
- **image_files** (Sequence) - Optional - Sequence of image filenames. If the dataset was not constructed from a folder, this will be None. Defaults to None.
- **normalizer** (string or function) - Optional - Normalizer function. Defaults to 'auto' (percentile-based normalization with p_min=1 and p_max=99.8).
- **defer_normalization** (bool) - Optional - Whether to defer normalization to data[i] (if normalizer is not None) to save memory. Defaults to False.
- **add_class_label** (bool) - Optional - Whether to add a class label. Defaults to True.
- **grid** (any) - Optional - Grid parameter. Defaults to None.

### Request Example
```python
# Example usage (conceptual, actual data structures depend on library implementation)
from spotiflow.data import Spots3DDataset

# Assuming images and centers are pre-defined numpy arrays or similar structures
# images = [...] 
# centers = [...] 

dataset = Spots3DDataset(images=images, centers=centers, compute_flow=True)
```

### Response
#### Success Response (200)
None (Constructor does not return a value, it initializes an object)

#### Response Example
None
```

--------------------------------

### Load and Prepare Image Data

Source: https://github.com/weigertlab/spotiflow/blob/main/examples/2_inference.ipynb

Loads a sample image from the HybISS dataset or allows loading a custom image file. Ensure your custom image path is correct if used.

```python
img = test_image_hybiss_2d()
# img = imread("YOUR_IMAGE_FILE_HERE")
```

--------------------------------

### spotiflow.sample_data.test_image_terra_2d

Source: https://github.com/weigertlab/spotiflow/blob/main/docs/source/index.md

Provides access to a sample 2D Terra image dataset.

```APIDOC
## Function spotiflow.sample_data.test_image_terra_2d

### Description
Loads and returns a sample 2D image dataset in the Terra format, useful for testing with specific data types.

### Usage
```python
from spotiflow.sample_data import test_image_terra_2d

# Example usage (details not provided in source)
# terra_image = test_image_terra_2d()
```
```

--------------------------------

### Specify Custom Model with CLI

Source: https://github.com/weigertlab/spotiflow/blob/main/docs/source/cli.md

To use a custom model, provide the path to the model directory using the `--model-dir` flag. This allows for inference with user-defined models.

```console
$ spotiflow-predict PATH --model-dir /path/to/custom/model
```

--------------------------------

### spotiflow.utils.get_data

Source: https://github.com/weigertlab/spotiflow/blob/main/docs/source/index.md

Utility function to retrieve sample or specific datasets for testing or demonstration.

```APIDOC
## Function spotiflow.utils.get_data

### Description
This utility function is used to fetch and load specific datasets, likely for testing, examples, or demonstration purposes.

### Usage
```python
from spotiflow.utils import get_data

# Example usage (details not provided in source)
# sample_data = get_data('test_image_hybiss_2d')
```
```

--------------------------------

### Train the 3D Spotiflow Model

Source: https://github.com/weigertlab/spotiflow/blob/main/examples/4_train_3d.ipynb

Trains the Spotiflow model using the loaded training and validation data. Specifies the save directory for the model and training parameters like epochs and crop size.

```python
save_folder = "models/synth_3d" # change to where you want to store the model
train_config = {
    "num_epochs": 1,
    "crop_size": 128,
    "crop_size_depth": 32,
    "smart_crop": True,
}
model.fit(
    trX,
    trY,
    valX,
    valY,
    save_dir=save_folder,
    train_config=train_config,
)
```

--------------------------------

### Spotiflow.fit

Source: https://github.com/weigertlab/spotiflow/blob/main/docs/source/api.md

Trains a Spotiflow model using provided training and validation data, with various configuration options for augmentation, saving, device, logging, and callbacks.

```APIDOC
## fit

### Description
Train a Spotiflow model.

### Method
`fit`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
* **train_images** - Required - training images
* **train_spots** - Required - training spots
* **val_images** - Required - validation images
* **val_spots** - Required - validation spots
* **augment_train** (bool) - Optional - whether to augment the training data. Defaults to True.
* **save_dir** - Optional - directory to save the model to. Must be given if no checkpoint logger is given as a callback. Defaults to None.
* **train_config** - Optional - training config. If not given, will use the default config. Defaults to None.
* **device** - Optional - computing device to use. Can be “cpu”, “cuda”, “mps”. Defaults to “cpu”.
* **logger** - Optional - logger to use. Defaults to “tensorboard”.
* **logging_name** - Optional - name of the expriment name for the logger if applicable. If None or ‘none’, a random one will be generated. Defaults to None.
* **number_of_devices** (int) - Optional - number of accelerating devices to use. Only applicable to “cuda” acceleration. Defaults to 1.
* **num_workers** (int) - Optional - number of workers to use for data loading. Defaults to 0 (main process only).
* **callbacks** - Optional - callbacks to use during training. Defaults to no callbacks.
* **deterministic** (bool) - Optional - whether to use deterministic training. Set to True for deterministic behaviour at a cost of performance. Defaults to True.
* **benchmark** (bool) - Optional - whether to use benchmarking. Set to False for deterministic behaviour at a cost of performance. Defaults to False.
* **dataset_kwargs** - Optional - additional arguments to pass to the SpotsDataset class. Defaults to no additional arguments.

### Request Example
```json
{
  "train_images": "path/to/train/images",
  "train_spots": "path/to/train/spots",
  "val_images": "path/to/val/images",
  "val_spots": "path/to/val/spots"
}
```

### Response
#### Success Response (200)
* **Model training status**: Details about the training process and outcome.

#### Response Example
```json
{
  "status": "Training complete",
  "model_path": "/path/to/saved/model"
}
```
```

--------------------------------

### List Saved Model Files

Source: https://github.com/weigertlab/spotiflow/blob/main/examples/4_train_3d.ipynb

Lists the files in the specified save folder to verify that the model has been stored correctly. This includes model checkpoints and configuration files.

```bash
!ls $save_folder
```

--------------------------------

### Run Tests with Coverage

Source: https://github.com/weigertlab/spotiflow/blob/main/README.md

Execute the test suite for Spotiflow using pytest. This command runs tests verbosely, enables color output, and generates a code coverage report for the spotiflow package.

```console
pytest -v --color=yes --cov=spotiflow
```

--------------------------------

### Customize Spotiflow Training with Train Config

Source: https://github.com/weigertlab/spotiflow/blob/main/docs/source/train.md

Pass a dictionary to the train_config parameter of the fit method to customize training parameters like epochs, batch size, and learning rate.

```python
train_config = {
    "num_epochs": 100,
    "learning_rate": 0.001,
    "smart_crop": True,
    # other parameters
}

model.fit(
    train_imgs,
    train_spots,
    val_imgs,
    val_spots,
    save_dir="/path/to/my_trained_model",
    train_config=train_config,
    # other parameters
)
```

--------------------------------

### spotiflow.sample_data.test_image_terra_2d

Source: https://github.com/weigertlab/spotiflow/blob/main/docs/source/api.md

Provides a single test Terra frame from the Spotiflow paper.

```APIDOC
## spotiflow.sample_data.test_image_terra_2d

### Description
Single test Terra frame from the Spotiflow paper (doi.org/10.1101/2024.02.01.578426)
```

--------------------------------

### Visualize Training and Validation Images

Source: https://github.com/weigertlab/spotiflow/blob/main/examples/3_finetune.ipynb

Uses the plot_image_with_spots function to display a sample training image and a sample validation image, aiding in data quality checks.

```python
plot_image_with_spots(trX[0], trY[0], title="Training image")
plot_image_with_spots(valX[-1], valY[-1], title="Validation image")
```

--------------------------------

### spotiflow.utils.get_data

Source: https://github.com/weigertlab/spotiflow/blob/main/docs/source/api.md

Retrieves data from a specified root path, with options to include subfolders, normalize data, and include test sets. This utility function is useful for loading datasets in various configurations.

```APIDOC
## spotiflow.utils.get_data

### Description
Get data from a given root path and subfolders. Supports normalization and inclusion of test sets.

### Method
Function

### Parameters
#### Path Parameters
- **path** (string) - Required - Path to the data.

#### Optional Parameters
- **normalize** (bool) - Optional - Whether to normalize the data. Defaults to True.
- **include_test** (bool) - Optional - Whether to include the test set. Defaults to False.
- **subfolder** (string or None) - Optional - Subfolders to be used for non-standard datasets. Defaults to None.
- **is_3d** (bool) - Optional - Whether the data is 3D. Defaults to False.
- **kwargs** - Optional - Additional keyword arguments.

### Returns
A tuple of arrays with length 2*len(subfolder) corresponding to the images, centers per subfolder.

### Return type
Tuple[np.ndarray]
```

--------------------------------

### Run Inference with CLI

Source: https://github.com/weigertlab/spotiflow/blob/main/docs/source/cli.md

Use this command to run inference on an image or a folder of images. Specify the input path as an argument.

```console
$ spotiflow-predict PATH
```

--------------------------------

### Specify Output Directory with CLI

Source: https://github.com/weigertlab/spotiflow/blob/main/docs/source/cli.md

Control where the inference results are saved by using the `--out-dir` flag. By default, results are saved in a 'spotiflow_results' subfolder.

```console
$ spotiflow-predict PATH --out-dir /path/to/output/directory
```

--------------------------------

### spotiflow.data.spots.SpotsDataset

Source: https://github.com/weigertlab/spotiflow/blob/main/docs/source/index.md

Dataset class for handling spot data, likely used for loading and preprocessing training or inference data.

```APIDOC
## Class spotiflow.data.spots.SpotsDataset

### Description
A dataset class designed to manage and provide access to spot data, potentially for training or analysis.

### Usage
```python
from spotiflow.data.spots import SpotsDataset

# Example usage (details not provided in source)
# dataset = SpotsDataset(data_path='path/to/data')
```
```

--------------------------------

### Python API for Spot Detection

Source: https://github.com/weigertlab/spotiflow/blob/main/README.md

Use the Spotiflow Python API to detect spots in 2D or 3D images. Load sample data or your own images, and use pre-trained or custom models for prediction. The 'details' object contains heatmap, flow, and intensity information.

```python
from spotiflow.model import Spotiflow
from spotiflow.sample_data import test_image_hybiss_2d

# Load sample image
img = test_image_hybiss_2d()
# Or any other image
# img = tifffile.imread("myimage.tif")

# Load a pretrained model
model = Spotiflow.from_pretrained("general")
# Or load your own trained model from folder
# model = Spotiflow.from_folder("./mymodel")

# Predict
points, details = model.predict(img) # points contains the coordinates of the detected spots, the attributes 'heatmap' and 'flow' of `details` contain the predicted full resolution heatmap and the prediction of the stereographic flow respectively (access them by `details.heatmap` or `details.flow`). Retrieved spot intensities are found in `details.intens`.
```

--------------------------------

### SpotiflowModelConfig

Source: https://github.com/weigertlab/spotiflow/blob/main/docs/source/api.md

Configuration class for the Spotiflow model. Allows customization of network architecture and properties.

```APIDOC
## class spotiflow.model.config.SpotiflowModelConfig

### Description
Configuration class for the Spotiflow model. Allows customization of network architecture and properties.

### Parameters
- **backbone** (str) - Optional - The backbone architecture to use (default: 'unet').
- **in_channels** (int) - Optional - Number of input channels (default: 1).
- **out_channels** (int) - Optional - Number of output channels (default: 1).
- **initial_fmaps** (int) - Optional - Number of initial feature maps (default: 32).
- **fmap_inc_factor** (int) - Optional - Factor by which feature maps increase per level (default: 2).
- **n_convs_per_level** (int) - Optional - Number of convolutional layers per level (default: 3).
- **levels** (int) - Optional - Number of downsampling/upsampling levels (default: 4).
- **downsample_factor** (int) - Optional - Factor for downsampling (default: 2).
- **kernel_size** (int) - Optional - Size of the convolutional kernel (default: 3).
- **padding** (str) - Optional - Padding mode for convolutions (default: 'same').
- **mode** (str) - Optional - Model mode (default: 'slim').
- **background_remover** (bool) - Optional - Whether to include a background remover (default: False).
- **compute_flow** (bool) - Optional - Whether to compute flow (default: True).
- **batch_norm** (bool) - Optional - Whether to use batch normalization (default: True).
- **downsample_factors** (list or tuple) - Optional - Specific downsampling factors for each level (default: None).
- **kernel_sizes** (list or tuple) - Optional - Specific kernel sizes for each level (default: None).
- **dropout** (float) - Optional - Dropout rate (default: 0.0).
- **sigma** (float) - Optional - Sigma value (default: 1.0).
- **is_3d** (bool) - Optional - Whether the model is 3D (default: False).
- **grid** (tuple) - Optional - Grid dimensions (default: (1, 1, 1)).
- **kwargs** - Additional keyword arguments.
```
Tokens:
Raw