Class Architecture#

PANORAMA is built on top of PPanGGOLiN: every core domain object in PANORAMA extends a corresponding PPanGGOLiN class rather than reimplementing it from scratch. This page maps the full class hierarchy, explains what each class adds, and shows how the pieces fit together.

Inheritance overview#

PPanGGOLiN                          PANORAMA extension
──────────────────────────────────────────────────────
ppanggolin.pangenome.Pangenome  →   panorama.pangenomes.Pangenome
ppanggolin.geneFamily.GeneFamily →  panorama.geneFamily.GeneFamily
ppanggolin.region.Region        →   panorama.region.Region
ppanggolin.region.Spot          →   panorama.region.Spot
ppanggolin.region.Module        →   panorama.region.Module
ppanggolin.region.GeneContext   →   panorama.region.GeneContext
ppanggolin.metadata.MetaFeatures →  panorama.systems.system.SystemUnit
ppanggolin.metadata.MetaFeatures →  panorama.systems.system.System
panorama.pangenomes.Pangenome   →   panorama.pangenomes.Pangenomes  (container)
panorama.geneFamily.GeneFamily  →   panorama.geneFamily.Akin        (cross-pangenome link)

Pangenome layer#

`Pangenome` (`panorama.pangenomes`)#

Extends ppanggolin.pangenome.Pangenome.

PPanGGOLiN’s Pangenome already manages organisms, contigs, genes, gene families, RGPs, spots, and modules. PANORAMA’s subclass panorama.pangenomes.Pangenome adds the systems layer on top:

Addition	Purpose
`_system_getter` / `_name2system`	Index detected `System` objects by ID and name
`systems_sources`	Track which annotation sources have been run
`add_file()` override	Validates that the file is HDF5 and reads PANORAMA-specific status fields via `panorama.format.read_binaries.get_status()`
`status["systems"]`	Extends PPanGGOLiN’s status dict with a `"systems"` key

The constructor takes a name (used throughout outputs) and an optional taxid.

`Pangenomes` (`panorama.pangenomes`)#

A plain PANORAMA class (no PPanGGOLiN parent) that acts as the multi-pangenome container used by every comparative workflow: panorama.pangenomes.Pangenomes.

Feature	Details
Storage	Dict of `name →` `Pangenome`
Thread safety	Accepts a shared `multiprocessing.Manager().Lock()` via `panorama.utils.init_lock()` for concurrent HDF5 reads
Loading	Delegates per-pangenome loading to `ThreadPoolExecutor` (see `panorama.format.read_binaries`)
Input	Populated from a TSV file via `panorama.utils.check_tsv_sanity()`

Gene family layer#

`GeneFamily` (`panorama.geneFamily`)#

Extends ppanggolin.geneFamily.GeneFamily.

Adds HMM-annotation state and cross-pangenome linkage on top of PPanGGOLiN’s graph-node representation: {py:class} panorama.geneFamily.GeneFamily.

Addition	Purpose
`_hmm`, `profile`, `optimized_profile`	Store the pyHMMER `HMM` object and search profiles used during annotation
`_units_getter` / `_systems_getter`	Index the `SystemUnit` and `System` objects that contain this family
`_akin`	Link to an `Akin` object representing equivalent families in other pangenomes

`Akin` (`panorama.geneFamily`)#

A pure PANORAMA class (no PPanGGOLiN parent) that groups GeneFamily objects from different pangenomes that have been determined to be functionally equivalent (by alignment or clustering). It is the data structure behind cross-pangenome family comparison: panorama.geneFamily.Akin.

Region layer#

All four classes in panorama.region extend the matching PPanGGOLiN region class. At present they are thin subclasses — their main purpose is to allow PANORAMA to inject additional attributes without patching PPanGGOLiN objects directly.

PANORAMA class	Extends	Key additions
`Region`	`ppanggolin.region.Region` (RGP)	None — placeholder for future PANORAMA-specific state
`Spot`	`ppanggolin.region.Spot`	`pangenome` back-reference; `conserved_id` for cross-pangenome matching
`Module`	`ppanggolin.region.Module`	Tracks associated `System` objects
`GeneContext`	`ppanggolin.region.GeneContext`	Minimal extension used during system detection

`ConservedSpots` (`panorama.region`)#

A pure PANORAMA class (panorama.region.ConservedSpots) that groups Spot objects from different pangenomes that occupy the same conserved genomic locus. It is the output of panorama compare_spots.

Systems layer#

The systems layer is entirely PANORAMA-specific — PPanGGOLiN has no equivalent.

Model definitions (`panorama.systems.models`)#

These classes parse and validate model JSON files before detection runs.

Class	Role
`Models`	Top-level container; maps `source → {name → Model}`
`Model`	One system definition: name, quorum rules (`min_mandatory`, `min_total`), transitivity, window, and a list of `FuncUnit` objects
`FuncUnit`	One functional unit within a model: presence type (`mandatory`, `accessory`, `forbidden`, `neutral`) and the `Family` profiles that can fill it
`Family`	A named HMM/profile entry inside a `FuncUnit`; the leaf of the model tree

Model and FuncUnit share behaviour via two private mixin bases (_BasicFeatures, _ModFuFeatures); {py:class} FuncUnit <panorama.systems.models.FuncUnit> and Family share a third (_FuFamFeatures).

Detected objects (`panorama.systems.system`)#

These classes hold the results of running detection against a pangenome.

Class	Extends	Role
`SystemUnit`	`ppanggolin.metadata.MetaFeatures`	One detected functional unit: links a `FuncUnit` model to the `GeneFamily` objects that satisfy it in a specific pangenome
`System`	`ppanggolin.metadata.MetaFeatures`	One detected system: groups `SystemUnit` objects and tracks their associated `Spot`, `Module`, and `Region` objects
`ClusterSystems`	—	Groups `System` objects from different pangenomes that represent the same biological system (used during comparison)

Both SystemUnit and System extend PPanGGOLiN’s MetaFeatures, which provides the generic metadata key/value store used for TSV and HDF5 serialisation.

How the layers connect#

Pangenomes
 └─ Pangenome  (one per input .h5 file)
     ├─ GeneFamily  (extends ppanggolin GeneFamily)
     │    └─ Akin  (links equivalent families across pangenomes)
     ├─ Region / Spot / Module  (extend ppanggolin region classes)
     │    └─ ConservedSpots  (groups Spots across pangenomes)
     └─ System  (PANORAMA-only)
          └─ SystemUnit  (one per satisfied FuncUnit)
               └─ GeneFamily  (the families that fill the unit)

Models  (parsed before detection, not stored in Pangenome)
 └─ Model
      └─ FuncUnit
           └─ Family

A System is created when the detection algorithm (in {py:mod} panorama.systems.detection) finds that a set of gene families in a genomic window satisfies the quorum rules of a {py: class}Model <panorama.systems.models.Model>. Each satisfied FuncUnit becomes a SystemUnit; the {py:class} SystemUnit <panorama.systems.system.SystemUnit> objects are collected into a {py:class} System <panorama.systems.system.System> which is then attached to the {py:class} Pangenome <panorama.pangenomes.Pangenome>.

Key PPanGGOLiN touchpoints#

PPanGGOLiN symbol	Where PANORAMA uses it
`ppanggolin.pangenome.Pangenome`	Base of `panorama.pangenomes.Pangenome`
`ppanggolin.geneFamily.GeneFamily`	Base of `panorama.geneFamily.GeneFamily`
`ppanggolin.region.{Region,Spot,Module,GeneContext}`	Bases of the four classes in `panorama.region`
`ppanggolin.metadata.MetaFeatures`	Base of `SystemUnit` and `System`
`ppanggolin.context.searchGeneContext`	Called by `panorama.systems.detection` to build the genomic-context graph used during detection
`ppanggolin.formats.*`	HDF5 read/write helpers extended by `panorama.format.read_binaries` and `panorama.format.write_binaries`

Note

There is a known circular-import risk between pangenomes.py and systems/system.py. If you need to import one from the other, use a function-local import rather than a top-level one. tests/conftest.py documents the current workaround.

Class Architecture#

Inheritance overview#

Pangenome layer#

Pangenome (panorama.pangenomes)#

Pangenomes (panorama.pangenomes)#