1. CMD Usage

Overview

This page shows the command-line workflow as a sequence of practical steps.

Use this path when you want to work mainly with the planktonclass commands from the terminal.

CMD workflow

The common order is:

install the package
create a project
validate the project config
optionally download the pretrained model
train a model
generate a report
optionally build an inference Docker image
continue with prediction, API usage, notebooks, or model inspection

Step 1: Install the package

pip install planktonclass

Step 2: Create a project

planktonclass init my_project

This creates:

a project-local config.yaml
a data/ folder
a models/ folder

For a runnable demo project:

planktonclass init my_project --demo

Step 3: Validate the config

planktonclass validate-config my_project

This is the easiest way to catch path or configuration problems before training.

Step 4: Optional pretrained model

If you want to start from a published pretrained model:

planktonclass pretrained my_project --model FlowCam

The published model id selects the instrument-specific weights, while model.modelname in config.yaml remains the architecture choice.

Step 5: Train a model

planktonclass train my_project

For a quick smoke test on a demo project:

planktonclass train my_project --quick

This creates a new timestamped output directory under my_project/models/.

Step 6: Generate a report

planktonclass report my_project

What the report step creates

The report step writes figures and summary files under models/<timestamp>/results/.

Typical outputs include:

overview performance figures
class-based evaluation plots
CSV summary files
additional threshold-based plots when you use full mode

Important note:

quick mode creates the core report figures
full mode also creates the threshold-based plots in the results/ subfolders

If you leave out --timestamp, planktonclass report suggests the newest run automatically.

Step 7: Optional inference Docker image

Once you are happy with the report for a trained run, you can package that run into a Docker image for more stable API-based inference:

planktonclass docker my_project

You can select a specific run and checkpoint if needed:

planktonclass docker my_project --timestamp 2026-04-21_120000 --ckpt-name best_model.keras --tag my-plankton-api:latest

Step 8: What you can do after training

Once a model has been created, you can continue in several directions.

You can:

inspect the checkpoints under models/<timestamp>/ckpts/
inspect logs under models/<timestamp>/logs/
inspect stats under models/<timestamp>/stats/
inspect saved predictions under models/<timestamp>/predictions/
inspect reports under models/<timestamp>/results/
package a run into Docker with planktonclass docker my_project
start the API with planktonclass api my_project
copy notebooks with planktonclass notebooks my_project
list available trained runs with planktonclass list-models my_project

Useful command summary

planktonclass init my_project
planktonclass init my_project --demo
planktonclass validate-config my_project
planktonclass pretrained my_project --model FlowCyto
planktonclass train my_project
planktonclass train my_project --quick
planktonclass report my_project
planktonclass docker my_project
planktonclass list-models my_project

For published pretrained entries, planktonclass list-models my_project prints the model id together with architecture, version, and checkpoint metadata.

Practical caution

For most users, it is best to keep the standard project layout created by planktonclass init unless you deliberately want to override paths in config.yaml.

In that standard layout, commands such as planktonclass validate-config my_project and planktonclass train my_project automatically use my_project/config.yaml. Use --config PATH only when you want to point to a different config file.