Perturbation registries ¶

The pertdb module is designed to model complex pertdb.Experiment of any pertdb.ExperimentType that include perturbations in the experimental design.

Perturbations are intentional disruptions in biological systems, such as pertdb.GeneticPerturbation, pertdb.CompoundPerturbation, or pertdb.EnvironmentalPerturbation, to study their effects on molecular and cellular processes. Such perturbations sometimes also have known pertdb.PerturbationTarget which can be one or serveral Gene, Pathway, or Protein. While single perturbations are common, it is also possible to combine several perturbations into a pertdb.CombinationPerturbation.

# pip install lamindb pertdb
!lamin init --storage ./test-pert-registries --modules bionty,pertdb

→ initialized database anonymous/test-pert-registries in /home/runner/work/pertdb/pertdb/docs/guide

import bionty as bt
import pertdb

→ connected lamindb: anonymous/test-pert-registries

Gefitinib is primarily a pharmaceutical drug, specifically a targeted therapy used in cancer treatment, particularly for non-small cell lung cancer (NSCLC). Let’s assume that we want to better understand the effectiveness of gefitinib and EGFR/KRAS knockdown combination perturbation for people that have a smoking history. In our early experimental setup, we therefore subject mice to smoke.

bt.settings.organism = "mouse"

Genetic perturbations¶

We create two pertdb.GeneticPerturbation records associated with the corresponding pertdb.PerturbationTarget.

EGFR_kd = pertdb.GeneticPerturbation(
    type="CRISPR-Cas9",
    name="EGFR knockdown",
    sequence="AGCTGACCGTGA",
    on_target_score=85,
    off_target_score=15,
).save()

EGFR_gene = bt.Gene.from_source("EGFR").save()
EGFR_kd_target = pertdb.PerturbationTarget(name="EGFR").save()
EGFR_kd_target.genes.add(EGFR_gene)

EGFR_kd.targets.add(EGFR_kd_target)
EGFR_kd_target

PerturbationTarget(uid='24H5UbVpLE2HqM', abbr=None, synonyms=None, description=None, name='EGFR', branch_id=1, created_on_id=1, space_id=1, created_by_id=1, run_id=None, source_id=None, created_at=2026-10-02 23:37:02 UTC, is_locked=False)

KRAS_kd = pertdb.GeneticPerturbation(
    type="CRISPR-Cas9",
    name="KRAS",
    sequence="TTGGTGGTGAACT",
    on_target_score=100,
    off_target_score=20,
).save()

KRAS_gene = bt.Gene.from_source("KRAS").save()
KRAS_kd_target = pertdb.PerturbationTarget(name="KRAS").save()
KRAS_kd_target.genes.add(KRAS_gene)

KRAS_kd.targets.add(KRAS_kd_target)
KRAS_kd_target

PerturbationTarget(uid='70cvOG8PqLVsFT', abbr=None, synonyms=None, description=None, name='KRAS', branch_id=1, created_on_id=1, space_id=1, created_by_id=1, run_id=None, source_id=None, created_at=2026-10-02 23:37:07 UTC, is_locked=False)

Compound perturbations¶

Next, we create a pertdb.Compound records including associated pertdb.PerturbationTarget.

gefitinib = pertdb.Compound(name="gefitinib").save()

Gefitinib is a tyrosine kinase inhibitor (TKI) that specifically targets the epidermal growth factor receptor (EGFR) pathway and the EGFR protein. Therefore, we can also define the and associate it with a :class:bionty.Pathway and :class:bionty.Protein.

egfr_pathway = bt.Pathway.from_source(
    name="epidermal growth factor receptor activity"
).save()
egfr_protein = bt.Protein.from_source(uniprotkb_id="Q5SVE7").save()
EGFR_kd_target.pathways.add(egfr_pathway)
EGFR_kd_target.proteins.add(egfr_protein)
EGFR_kd_target

! ontology ID BFO:0000015 not found in DataFrame

PerturbationTarget(uid='24H5UbVpLE2HqM', abbr=None, synonyms=None, description=None, name='EGFR', branch_id=1, created_on_id=1, space_id=1, created_by_id=1, run_id=None, source_id=None, created_at=2026-10-02 23:37:02 UTC, is_locked=False)

gefitinib.targets.add(EGFR_kd_target)
gefitinib

Compound(uid='2aqd1p2AqzhulX', ontology_id=None, abbr=None, synonyms=None, description=None, name='gefitinib', type=None, chembl_id=None, smiles=None, canonical_smiles=None, inchikey=None, molweight=None, molformula=None, moa=None, branch_id=1, created_on_id=1, space_id=1, created_by_id=1, run_id=None, source_id=None, created_at=2026-10-02 23:37:07 UTC, is_locked=False)

Environmental perturbations ¶

smoking = pertdb.EnvironmentalPerturbation(
    name="smoking status measurement", ontology_id="EFO:0006527"
).save()

Combination Perturbation¶

Now we can combine all individual perturbations into a single pertdb.CombinationPerturbation.

from datetime import timedelta

gefitinib_pert = pertdb.CompoundPerturbation(
    name="gefitinib 10uM treatment",
    concentration=10.0,
    concentration_unit="uM",
    duration=timedelta(hours=24),
    compound=gefitinib,
).save()

combination_perturbation = pertdb.CombinationPerturbation(
    name="gefitinib and EGFR/KRAS knockdown combination perturbation subject to smoking"
).save()
combination_perturbation.genetic_perturbations.set([EGFR_kd, KRAS_kd])
combination_perturbation.compound_perturbations.add(gefitinib_pert)
combination_perturbation.environmental_perturbations.add(smoking)

combination_perturbation

CombinationPerturbation(uid='tezzUrOOBjOMBF', abbr=None, synonyms=None, description=None, name='gefitinib and EGFR/KRAS knockdown combination perturbation subject to smoking', branch_id=1, created_on_id=1, space_id=1, created_by_id=1, run_id=None, source_id=None, created_at=2026-10-02 23:37:16 UTC, is_locked=False)

Perturbation registries ¶

Genetic perturbations¶

Compound perturbations¶

Environmental perturbations¶

Combination Perturbation¶

Environmental perturbations ¶