planktonclass

planktonclass is the package repository for training, evaluating, and serving phytoplankton image classifiers.

It is the package-first home for:

• local installation

• project initialization

• training and reporting

• local command-line usage

• local DEEPaaS API usage

• packaged notebook workflows

What the package does

With planktonclass, you can:

• create a standard project structure with planktonclass init

• train a classifier from a project config.yaml

• generate reports from a training run

• start a local DEEPaaS API for browser-based training and prediction

• copy packaged notebooks into a local project

• work with a published pretrained model

Typical workflow

For most users, the common order is:

1. install the package

2. create a project

3. validate the config

4. train a model

5. generate a report

6. optionally continue with command-line, API, or notebook-based usage

Which page to start with

Start with:

• Installation if you only want to install the package

• Quickstart if you want the shortest working pipeline

Then continue with one of these workflows:

• 1. CMD Usage for command-line usage

• 2. API Usage for DEEPaaS API usage

• 3. Notebooks Usage for notebook-based usage

• Reference for the package reference and internal conventions

Companion repository

If you want the full repository with Docker, OSCAR, AI4OS, packaged deployment assets, and broader project explanation, use the companion repository:

• phyto-plankton-classification: https://github.com/ai4os-hub/phyto-plankton-classification

Citation

If you use this package, please consider citing:

• Decrop, W., Lagaisse, R., Mortelmans, J., Muñiz, C., Heredia, I., Calatrava, A., & Deneudt, K. (2025). Automated image classification workflow for phytoplankton monitoring. Frontiers in Marine Science, 12. https://doi.org/10.3389/fmars.2025.1699781

Contents

Package Guide

• Installation
  • Option A: Install from PyPI
  • Option B: Development install
  • Important notes
  • GPU setup
  • Next step
• Quickstart
  • Quickstart pipeline
  • Step 1: Create a project
  • Step 2: Validate the config
  • Step 3: Optional pretrained model
  • Step 4: Train a model
  • Step 5: Generate a report
  • Step 6: Optional inference Docker image
  • Project structure
  • Minimal required input
  • Typical additions
  • Next step
• 1. CMD Usage
  • Overview
  • CMD workflow
  • Step 1: Install the package
  • Step 2: Create a project
  • Step 3: Validate the config
  • Step 4: Optional pretrained model
  • Step 5: Train a model
  • Step 6: Generate a report
  • What the report step creates
  • Step 7: Optional inference Docker image
  • Step 8: What you can do after training
  • Useful command summary
  • Practical caution
• 2. API Usage
  • Overview
  • API workflow
  • Step 1: Install the package
  • Step 2: Create a project
  • Step 3: Validate the config
  • Step 4: Optional pretrained model
  • Step 5: Optional inference Docker image
  • Step 6: Start the API
  • Step 7: Train through the API
  • Step 8: Run prediction through the API
  • Prediction response
  • What the API exposes
  • Runtime behavior
• 3. Notebooks Usage
  • Overview
  • Notebook workflow
  • Step 1: Install the package
  • Step 2: Create a project
  • Step 3: Validate the config
  • Step 4: Optional pretrained model
  • Step 5: Copy the notebooks into the project
  • Step 6: Work through the notebooks
  • Notebook list
  • Step 7: Important notebook notes
  • How to open them
• Reference
  • Package entry points
  • Configuration map
  • Important conventions
  • Practical usage after a model is created
  • Load the project config
  • Load a trained model
  • Predict one image from Python
  • Use a Dockerized inference server from Python
  • Inspect output locations
  • Source files