CyFi: Cyanobacteria Finder

CyFi is a command line tool that uses satellite imagery and machine learning to estimate cyanobacteria levels in small, inland water bodies. The goal of CyFi is to help water quality managers better allocate resources for in situ sampling, and make more informed decisions around public health warnings for critical resources like lakes and reservoirs.

Read more at cyfi.drivendata.org

Quickstart

Install

[!NOTE] On a Mac, LightGBM needs OpenMP. Run brew install libomp before pip install cyfi, or install with conda, which includes it.

Install CyFi with pip:

pip install cyfi

Alternatively, CyFi can be installed with conda:

conda install -c conda-forge cyfi

For detailed instructions for those installing python for the first time, see the Installation page.

Generate batch predictions

Generate batch predictions at the command line with cyfi predict.

First, specify your sample points in a csv with the following columns:

• latitude
• longitude
• date

For example,

# sample_points.csv
latitude,longitude,date
41.424144,-73.206937,2023-06-22
36.045,-79.0919415,2023-07-01
35.884524,-78.953997,2023-08-04

Then run:

cyfi predict sample_points.csv

This will output a preds.csv that contains a column for cyanobacteria density and a column for the associated severity level based on WHO thresholds.

# preds.csv
sample_id,date,latitude,longitude,density_cells_per_ml,severity
7ff4b4a56965d80f6aa501cc25aa1883,2023-06-22,41.424144,-73.206937,34173.0,moderate
882b9804a3e28d8805f98432a1a9d9af,2023-07-01,36.045,-79.0919415,7701.0,low
10468e709dcb6133d19a230419efbb24,2023-08-04,35.884524,-78.953997,4053.0,low

To see all of the available options, run cyfi predict --help.

Generate prediction for a single point

Or, generate a cyanobacteria estimate for a single point on a single date using cyfi predict-point.

Just specify the latitude, longitude, and date as arguments at the command line.

cyfi predict-point --lat 41.2 --lon -73.2 --date 2023-09-14

This will print out the estimated cyanobacteria density and associated severity level based on WHO thresholds, along with the date of the Sentinel-2 image the estimate is based on and how many days before the sample date it was taken.

2026-10-25 23:17:31.939 | SUCCESS  | cyfi.cli:predict_point:184 - Estimate generated:
date                    2023-09-14
latitude                      41.2
longitude                    -73.2
density_cells_per_ml        36,957
severity                  moderate
image_date              2023-09-14
days_before_sample               0

To see all of the available options, run cyfi predict-point --help.

A note on severity levels

Severity levels are based on World Health Organization (WHO) cyanobacteria density thresholds.

• Low: 0 - 20,000 cells/ml
• Moderate: 20,000 - 100,000 cells/ml
• High: > 100,000 cells/ml

However users should feel free to to use their own thresholds as makes sense for their needs.

Visualizing predictions

Launch the CyFi Explorer to view the Sentinel-2 imagery used to generate each cyanobacteria estimate!

Using CyFi with AI agents

CyFi has an agent skill for AI coding agents such as Claude Code, Codex, or Cursor. The skill walks the agent through gathering your locations and dates, running CyFi, explaining the results, and opening the CyFi Explorer.

One-time setup. Ask your agent:

Install CyFi and its agent skill from https://github.com/drivendataorg/cyfi

From then on, ask in plain language:

Use CyFi to estimate cyanobacteria in [your lake or location]

To install the skill by hand instead, copy it into ~/.claude/skills/ (every project) or .claude/skills/ (one project) for Claude Code:

git clone https://github.com/drivendataorg/cyfi
cp -r cyfi/skills/cyfi ~/.claude/skills/cyfi

For an agent with no skill mechanism, paste skills/cyfi/SKILL.md into its prompt or project instructions.

Reference paper

Dorne, E., Wetstone, K., Cerquera, T. B., & Gupta, S. (2024). Cyanobacteria detection in small, inland water bodies with CyFi. In Proceedings of the 23nd Python in Science Conference (pp. 154–173). https://doi.org/10.25080/pdhk7238