Skip to content

python_usage.rst

Latest commit

 

History

History
166 lines (105 loc) · 4.59 KB

python_usage.rst

File metadata and controls

166 lines (105 loc) · 4.59 KB

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:

  1. install the package
  2. create a project
  3. validate the project config
  4. optionally download the pretrained model
  5. train a model
  6. generate a report
  7. optionally build an inference Docker image
  8. 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.