Command-line Interface (CLI)

Piscis also offers a command-line interface (CLI) for inference and training directly from the terminal. The CLI supports two commands: predict and train.

Predict Command

The predict command is used to detect spots in an image or a folder of images using a trained Piscis model. The results are saved as .csv files containing the coordinates of predicted spots.

Usage:

piscis predict [--options] input_path output_path

Positional Arguments:

input_path

Path to image or folder of images.

output_path

Path to save predicted spots as CSV.

Options:

-h, --help

show this help message and exit

--model-name MODEL_NAME

Model name. (default: 20251212)

--batch-size BATCH_SIZE

Batch size for the CNN. (default: 1)

--stack

Whether the input is a stack of images. (default: False)

--scale SCALE

Scale factor for rescaling the input. (default: 1.0)

--threshold THRESHOLD

Spot detection threshold. (default: 0.5)

--min-distance MIN_DISTANCE

Minimum distance between spots. (default: 1)

Example:

piscis predict ./images ./predictions --model-name 20251212

This command processes all images in the ./images folder using the 20251212 model and saves results in the ./predictions folder.

Train Command

The train command is used to train a new Piscis model or fine-tune an existing one with your custom dataset.

Usage:

piscis train [--options] model_name dataset_path

Positional Arguments:

model_name

Model name.

dataset_path

Path to a dataset or path to a directory containing multiple datasets.

Options:

-h, --help

show this help message and exit

--initial-model-name INITIAL_MODEL_NAME

Name of an existing model to initialize the weights. (default: None)

--adjustment ADJUSTMENT

Adjustment type applied to images. Supported types are ‘normalize’ and ‘standardize’. (default: standardize)

–input-size INPUT_SIZE INPUT_SIZE

Input size used for training. (default: (256, 256))

--random-seed RANDOM_SEED

Random seed used for initialization and training. (default: 0)

--batch-size BATCH_SIZE

Batch size for training. (default: 4)

--num-workers NUM_WORKERS

Number of workers for data loading. (default: 0)

--learning-rate LEARNING_RATE

Learning rate for the optimizer. (default: 0.1)

--weight-decay WEIGHT_DECAY

Strength of the weight decay regularization. (default: 1e-05)

--epochs EPOCHS

Number of epochs to train the model for. (default: 500)

--warmup-fraction WARMUP_FRACTION

Fraction of epochs for learning rate warmup. (default: 0.04)

--decay-fraction DECAY_FRACTION

Fraction of epochs for learning rate decay. (default: 0.4)

--l2-loss-weight L2_LOSS_WEIGHT

Weight for the masked L2 loss term in the overall loss function. (default: 0.1)

--decay-transitions DECAY_TRANSITIONS

Number of times to decay the learning rate. (default: 10)

--decay-factor DECAY_FACTOR

Multiplicative factor of each learning rate decay transition. (default: 0.5)

--dilation-iterations DILATION_ITERATIONS

Number of iterations to dilate ground truth labels to minimize class imbalance and misclassifications due to minor offsets. (default: 1)

--max-distance MAX_DISTANCE

Maximum distance for matching predicted and ground truth displacement vectors. (default: 3.0)

--temperature TEMPERATURE

Temperature parameter for softmax. (default: 0.05)

--epsilon EPSILON

Small constant for numerical stability. (default: 1e-07)

--checkpoint_every CHECKPOINT_EVERY

Number of epochs between saving model checkpoints. (default: 10)

--device DEVICE

Device for training. (default: cuda)

Example:

piscis train new_model ./dataset

This command trains a model named new_model using the dataset in ./dataset and default training parameters.