System#

class panorama.systems.system.System(model, source, system_id=None, units=None)#

Bases: MetaFeatures

Represents a biological system detected in a pangenome, composed of one or more functional units.

A System groups gene families that co-occur according to a defined model. It manages its internal system units (instances of SystemUnit), maintains references to organisms, gene families, regions, modules, and annotation sources, and supports set-based operations such as union, intersection, and inclusion with other systems.

ID#

Unique identifier for the system. Automatically generated if not provided.

Type:: str

model#

The model from which the system structure is derived.

Type:: Model

source#

Source of the annotation or prediction (e.g., experimental, inferred).

Type:: str

canonical#

Set of canonical systems used to group variants of the same system.

Type:: Set[System]

pangenome#

The pangenome object the system belongs to.

Type:: Optional[Pangenome]

cluster_id#

Identifier used to group homologous systems across pangenomes.

Type:: Optional[int]

__delitem__(name)#

Removes a system unit by its name.

Parameters:: name (str) – The name of the unit to remove.
Raises:: KeyError – If no unit with the given name exists.

__eq__(other)#

Compares this system to another for structural equality.

Parameters:: other (System) – Another system to compare with.
Returns:: bool – True if systems are structurally identical.
Raises:: TypeError – If other is not a System.
Return type:: bool

__getitem__(name)#

Retrieves a system unit by its name.

Parameters:: name (str) – The name of the unit.
Returns:: SystemUnit – The system unit corresponding to the name.
Raises:: KeyError – If no unit with the given name exists.
Return type:: SystemUnit

__hash__()#

Computes a hash based on the set of system units.

The hash includes unit names and their content but excludes the system ID to ensure consistent hashing across different launches.

Returns:: int – A hash representing the system units and their content.
Return type:: int

__init__(model, source, system_id=None, units=None)#

Initializes a System object with a model and optional functional units.

Parameters:

model (Model) – The model defining the structure and required components of the system.
source (str) – Source of the system annotation (e.g., predicted, curated).
system_id (Union[str, int]) – Unique identifier for the system. If not provided, an incremental ID is assigned automatically.
units (Set[SystemUnit]) – Optional set of system units (functional components) to initialize the system with.

Raises:

TypeError – If any unit in units is not an instance of SystemUnit.

__len__()#

Returns the number of units in the system.

Returns:: int – Number of system units.
Return type:: int

__repr__()#

Returns a human-readable representation of the system.

Returns:: str – A summary string containing the system ID and model name.
Return type:: str

__setitem__(name, unit)#

Adds a system unit to the system under a given name.

Parameters:

name (str) – Name under which to register the unit.
unit (SystemUnit) – The unit to register.

Raises:

TypeError – If unit is not an instance of SystemUnit.
KeyError – If another unit with the same name already exists and differs.

_mk_fam2unit()#: Internal method to create a mapping from gene family to system unit.

add_canonical(system)#

Adds a canonical system to this instance. If a similar canonical system already exists, merges or replaces it.

Parameters:: system (System) – Canonical system to incorporate.

add_metadata(metadata, metadata_id=None)#

Add metadata to metadata getter

Parameters:

metadata (Metadata) – metadata value to add for the source
metadata_id (int) – metadata identifier

Raises:

AssertionError – Source or metadata is not with the correct type

Return type:

None

add_unit(unit)#

Adds a system unit to the system, replacing it if it is a superset.

Parameters:: unit (SystemUnit) – The unit to add.
Raises:: AssertionError – If the provided unit is not a SystemUnit.

annotation_sources()#

Collects all annotation sources used in the system.

Returns:: Set[str] – Unique annotation source identifiers.
Return type:: Set[str]

canonical_models()#

Returns the canonical model names associated with this system.

Returns:: List[str] – Canonical model names.
Return type:: List[str]

del_metadata_by_attribute(**kwargs)#: Remove a source from the feature

del_metadata_by_source(source)#

Remove a source from the feature

Parameters:

source (str) – Name of the source to delete

Raises:

AssertionError – Source is not with the correct type
KeyError – Source does not belong in the MetaFeature

property families: Generator[GeneFamily, None, None]#

Retrieves all gene families associated with the system.

Returns:: Generator[GeneFamily, None, None] – All gene families from all units.

formatted_metadata_dict()#

Format metadata by combining source and field values.

Given an object with metadata, this function creates a new dictionary where the keys are formatted as ‘source_field’.

Return type:: Dict[str, List[str]]
Returns:: A dictionary with formatted metadata.

formatted_metadata_dict_to_string(separator='|')#

Format metadata by combining source and field values.

Given an object with metadata, this function creates a new dictionary where the keys are formatted as ‘source_field’. In some cases, it is possible to have multiple values for the same field, in this situation, values are concatenated with the specified separator.

Parameters:: separator (str) – The separator used to join multiple values for the same field (default is ‘|’).
Return type:: Dict[str, str]
Returns:: A dictionary with formatted metadata.

get_metadata(source, metadata_id=None)#

Get metadata from metadata getter by its source and identifier

Parameters:

source (str) – source of the metadata
metadata_id (int) – metadata identifier

Raises:

KeyError – No metadata with ID or source is found

Return type:

Metadata

get_metadata_by_attribute(**kwargs)#

Get metadata by one or more attribute

Return type:: Generator[Metadata, None, None]
Returns:: Metadata searched

get_metadata_by_source(source)#

Get all the metadata feature corresponding to the source

Parameters:: source (str) – Name of the source to get
Return type:: Optional[Dict[int, Metadata]]
Returns:: List of metadata corresponding to the source
Raises:: AssertionError – Source is not with the correct type

get_metainfo(gene_family)#

Retrieves metadata associated with a gene family (e.g., annotation source).

Parameters:: gene_family (GeneFamily) – The gene family to query.
Returns:: Tuple[str, int] – Annotation source and metadata ID.
Return type:: Tuple[str, int]

get_module(identifier)#

Retrieves a module by its unique identifier.

Parameters:: identifier (int) – Module ID.
Returns:: Module – The corresponding module.
Raises:: KeyError – If not found.
Return type:: Module

get_region(name)#

Retrieves a region by its name.

Parameters:: name (str) – Region name.
Returns:: Region – Matching region.
Raises:: KeyError – If the region is not associated.
Return type:: Region

get_spot(identifier)#

Retrieves a spot by its unique identifier.

Parameters:: identifier (int) – Spot ID.
Returns:: Spot – Corresponding spot.
Raises:: KeyError – If not found.
Return type:: Spot

get_unit(name)#

Fetches a unit by name.

Parameters:: name (str) – Name of the system unit.
Returns:: SystemUnit – The corresponding unit.
Return type:: SystemUnit

has_metadata()#

Does the feature has some metadata associated.

Return type:: bool
Returns:: True if it has metadata else False

has_source(source)#

Check if the source is in the metadata feature

Parameters:: source (str) – name of the source
Return type:: bool
Returns:: True if the source is in the metadata feature else False

intersection(other)#

Computes the common units between this system and another.

Parameters:: other (System) – Another system to intersect with.
Returns:: Set[SystemUnit] – Units shared between both systems.
Raises:: TypeError – If other is not a System.
Return type:: Set[SystemUnit]

is_subset(other)#

Checks if this system is fully contained in another.

Parameters:: other (System) – System to compare against.
Returns:: bool – True if self is a subset of the other.
Raises:: TypeError – If other is not a System.
Return type:: bool

is_superset(other)#

Checks if this system contains all units of another.

Parameters:: other (System) – System to compare against.
Returns:: bool – True if self is a superset of the other.
Raises:: TypeError – If other is not a System.
Return type:: bool

max_metadata_by_source()#

Get the maximum number of metadata for one source

Return type:: Tuple[str, int]
Returns:: Name of the source with the maximum annotation and the number of metadata corresponding

merge(other)#

Merges another system into this one by unifying their units.

Parameters:: other (System) – The system to merge into this one.
Raises:: TypeError – If other is not a System.

property metadata: Generator[Metadata, None, None]#

Generate metadata in gene families

Returns:: Metadata from all sources

property model_families: Generator[GeneFamily, None, None]#

Retrieves all gene families defined by the model.

Returns:: Generator[GeneFamily, None, None] – Model gene families.

property model_organisms: Generator[Organism, None, None]#

Retrieves organisms matching model gene family requirements.

Returns:: Generator[Organism, None, None] – Organisms satisfying the system’s model constraints.

property modules: Generator[Module, None, None]#

Retrieves all modules associated with the system.

Returns:: Generator[Module, None, None] – Modules involved in the system.

property name: str#

Return the name of the system unit, as defined by its associated functional unit.

Returns:: str – The name of the system unit.

property number_of_families#

Computes the total number of gene families in the system.

Returns:: int – Count of gene families across all units.

property number_of_metadata: int#: Get the number of metadata associated to feature

property number_of_model_gene_families#

Computes the total number of model gene families in the system.

Returns:: int – Count of model gene families across all units.

property organisms: Generator[Organism, None, None]#

Retrieves all organisms where gene families from the system were found.

Returns:: Generator[Organism, None, None] – Organisms represented in the system.

property regions: Generator[Region, None, None]#

Retrieves all genomic regions associated with the system.

Returns:: Generator[Region, None, None] – Regions where system units were found.

property sources: Generator[str, None, None]#

Get all metadata source in gene family

Returns:: Metadata source

property spots: Generator[Spot, None, None]#

Retrieves all genomic spots linked to the system.

Returns:: Generator[Spot, None, None] – All spots.

property units: Generator[SystemUnit, None, None]#

Return a generator yielding all SystemUnit instances contained in the system.

Yields:: SystemUnit – Each unit in the system.