Running Your First Report

Two ways to run any report: from the command line (CLI) or from Python (notebook or script). Both produce the same output. Pick whichever fits your workflow.

CLI — quickest path

List what’s available:

biofilter report list

Run a report and print the result to the terminal:

biofilter report run --report-name etl_status

Save the output to a CSV file:

biofilter report run --report-name etl_status --output etl_status.csv

Pass parameters with --param KEY=VALUE:

biofilter report run \
  --report-name entity_filter \
  --input "BRCA1" \
  --input "TP53" \
  --param match_mode=exact

For input lists too long for the command line, use --input-file:

biofilter report run \
  --report-name entity_filter \
  --input-file ./genes.txt

To see what parameters a report accepts:

biofilter report explain --report-name entity_filter

Python API — best for notebooks and scripts

from biofilter import Biofilter

bf = Biofilter()  # picks up DB from .biofilter.toml or DATABASE_URL

df = bf.report.run(
    "entity_filter",
    input_data=["BRCA1", "TP53", "APOE"],
    match_mode="exact",
)

print(f"{len(df)} rows")
df.head()

Every report returns a pandas DataFrame, so you can chain it with the rest of your analysis without saving to disk first.

A complete first example

Here’s a full session — install, connect, run:

# Install
pip install biofilter

# Configure
biofilter config init --path .
biofilter config set database.db_uri "postgresql+psycopg2://user:password@db.example.com:5432/database_name"

# Run
biofilter report list
biofilter report run --report-name etl_status --output etl_status.csv

Open etl_status.csv in your favorite tool and you’ll see the current state of every data source in the database.

Next steps