SystemUnit#

class panorama.systems.system.SystemUnit(functional_unit, source, gene_families=None, families_to_metainfo=None)#

Bases: MetaFeatures

Represents a functional unit detected in a pangenome system, associating a FuncUnit model with gene families, annotation sources, and metadata. Provides methods for managing gene families, modules, spots, and regions, as well as set operations and metadata retrieval for gene families within the unit.

ID#

Identifier of the system unit object.

Type:: int

source#

Source of the functional unit.

Type:: str

__eq__(other)#

Determine if two SystemUnit instances are equal by comparing their sets of model gene families.

Parameters:: other (SystemUnit) – The other SystemUnit to compare with.
Returns:: bool – True if both units have the same model gene families, False otherwise.
Raises:: TypeError – If ‘other’ is not a SystemUnit instance.
Return type:: bool

__getitem__(name)#

Retrieve a GeneFamily by its name from the system unit.

Parameters:: name (str) – The name of the gene family to retrieve.
Returns:: GeneFamily – The gene family associated with the given name.
Raises:: KeyError – If no gene family with the specified name exists in the system unit.
Return type:: GeneFamily

__hash__()#

Compute a hash value for the SystemUnit based on its gene families and annotation sources.

The hash includes gene family names and their annotation sources but excludes the ID to ensure consistent hashing across different launches.

Returns:: int – The hash value representing the gene families and their annotation sources.
Return type:: int

__init__(functional_unit, source, gene_families=None, families_to_metainfo=None)#

Initialize a SystemUnit instance representing a functional unit detected in a pangenome.

Parameters:

functional_unit (FuncUnit) – The FuncUnit model associated with this system unit.
source (str) – Source of the functional unit.
gene_families (Set[GeneFamily]) – Set of gene families in the system unit.
families_to_metainfo (Dict[GeneFamily, Tuple[str, int]]) – Mapping of gene families to their annotation source and metadata ID.

__len__()#

Returns the number of gene families in the functional unit.

Returns:: int – Number of gene families.

__repr__()#

Return a string representation of the SystemUnit, including its ID, name, and associated model name.

Returns:: str – String representation of the SystemUnit.

__setitem__(name, family)#

Assigns a GeneFamily to the system by name.

Parameters:

name (str) – The name of the gene family.
family (GeneFamily) – The GeneFamily instance to assign.

Raises:

TypeError – If the provided family is not a GeneFamily instance.
KeyError – If a different GeneFamily with the same name already exists.

_asso_modules()#: Associates modules to the unit based on the gene families present.

_get_model_families()#

Return the set of gene families in this SystemUnit that are associated with a nonzero metadata ID.

Returns:: Set[GeneFamily] – Set of gene families with a nonzero metadata identifier.
Return type:: Set[GeneFamily]

_make_spot_getter()#: Creates and populates the spot getter with spots associated to the unit, either from regions or gene families.

add_family(gene_family, annotation_source='', metadata_id=0)#

Adds a GeneFamily to the system and associates it with annotation source and metadata ID.

Parameters:

gene_family (GeneFamily) – The gene family to add.
annotation_source (str) – The source of the annotation. Defaults to “”.
metadata_id (int) – The metadata identifier. Defaults to 0.

Raises:

AssertionError – If gene_family is not an instance of GeneFamily.

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_module(module)#

Associate a module with this unit.

Parameters:: module (Module) – The module to add.
Raises:: Exception – If a different module with the same identifier is already associated with this unit.

add_region(region)#

Adds a region to the unit.

Parameters:: region (Region) – The region to add.
Raises:: Exception – If a different region with the same identifier is already associated with the unit.

add_spot(spot)#

Adds a spot to the unit.

Parameters:: spot (Spot) – The spot to add.
Raises:: Exception – If a different spot with the same identifier is already associated with the unit.

annotation_sources()#

Retrieve a set of unique annotation source names from the system.

Returns:: Set[str] – A set containing all non-empty annotation source names.
Return type:: Set[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

difference(other)#

Return the set of gene families present in this SystemUnit but not in another.

Parameters:: other (SystemUnit) – The SystemUnit to compare against.
Returns:: Set[GeneFamily] – Gene families unique to this unit.
Raises:: TypeError – If ‘other’ is not a SystemUnit instance.
Return type:: Set[GeneFamily]

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

Returns a generator yielding all gene families associated with this system unit.

Yields:: GeneFamily – Each gene family in the unit.

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.

property functional_unit: FuncUnit#

Return the Functional unit model associated with this system unit.

Returns:: FuncUnit – The functional unit model.
Raises:: AttributeError – If the functional unit is not set.

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)#

Return the annotation source and metadata ID associated with the given gene family.

Parameters:: gene_family (GeneFamily) – The gene family for which to retrieve metadata.
Returns:: Tuple[str, int] – A tuple containing the annotation source and metadata identifier.
Return type:: Tuple[str, int]

get_module(identifier)#

Retrieve the module associated with the given identifier.

Parameters:: identifier (int) – The identifier of the module to retrieve.
Returns:: Module – The module corresponding to the given identifier.
Raises:: KeyError – If no module with the specified identifier is associated with this unit.
Return type:: Module

get_region(name)#

Retrieves a region by its name.

Parameters:: name (str) – Name of the region.
Returns:: Region – The region with the given name.
Raises:: KeyError – If the region is not associated with the unit.
Return type:: Region

get_spot(identifier)#

Retrieves a spot by its identifier.

Parameters:: identifier (int) – Identifier of the spot.
Returns:: Spot – The spot with the given identifier.
Raises:: KeyError – If the spot is not associated with the unit.
Return type:: Spot

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

hash_content()#

Generate string content for hashing based on gene families and annotation sources.

Returns:: str – String representation of the content to be hashed.
Return type:: str

intersection(other)#

Return the set of model gene families common to both this SystemUnit and another.

Parameters:: other (SystemUnit) – The other SystemUnit to compare with.
Returns:: Set[GeneFamily] – Set of gene families present in both units.
Raises:: TypeError – If ‘other’ is not a SystemUnit instance.
Return type:: Set[GeneFamily]

is_subset(other)#

Check if this SystemUnit is a subset of another, i.e., contains all model gene families of the other unit.

Parameters:: other (SystemUnit) – The unit to compare against.
Returns:: bool – True if this unit is a subset of the other, False otherwise.
Raises:: TypeError – If ‘other’ is not a SystemUnit instance.

is_superset(other)#

Check if this SystemUnit is a superset of another, i.e., contains all model gene families of the other unit.

Parameters:: other (SystemUnit) – The unit to compare against.
Returns:: bool – True if all model gene families in ‘other’ are present in this unit, False otherwise.
Raises:: TypeError – If ‘other’ is not a SystemUnit instance.

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)#

Merge another SystemUnit into this one by adding gene families present in the other unit but not in this unit.

Parameters:: other (SystemUnit) – The SystemUnit to merge with.
Raises:: TypeError – If ‘other’ is not a SystemUnit instance.

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

Generate metadata in gene families

Returns:: Metadata from all sources

property model: Model#

Return the Model instance associated with the functional unit of this system unit.

Returns:: Model – The model in which the functional unit is defined.

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

Return a generator yielding all gene families in this SystemUnit that are associated with a nonzero metadata ID.

Yields:: GeneFamily – Each gene family described in the model.

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

Return a generator yielding all unique Organism instances present in at least min_total model gene families within this SystemUnit.

Yields:: Organism – Each organism meeting the minimum model family presence threshold.

Note

Considers only gene families associated with a nonzero metadata ID (model families). Attempts to use a matrix approach for efficient computation. TODO: Try to use organisms bitarray for optimization.

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

Generator that yields all modules associated with the unit.

Yields:: Module – Each module associated with the unit.

property name: str#

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

Returns:: str – Name of the system unit.

property nb_model_families: int#

Return the number of unique gene families in this SystemUnit that are associated with a nonzero metadata ID.

Returns:: int – Number of distinct model-associated gene families.

property nb_organisms: int#

Return the number of unique Organism instances associated with the gene families in this SystemUnit.

Returns:: int – Number of distinct organisms linked to the unit.

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

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

Return a generator yielding all unique Organism instances associated with the gene families in this SystemUnit.

Yields:: Organism – Each unique organism linked to any gene family in the unit.

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

Retrieves the regions associated with the unit.

Yields:: Region – Each region associated with the unit.

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

Get all metadata source in gene family

Returns:: Metadata source

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

Retrieves the spots associated with the unit.

Yields:: Spot – Each spot associated with the unit.

symmetric_difference(other)#

Return the set of gene families that are present in exactly one of this SystemUnit or another.

Parameters:: other (SystemUnit) – The SystemUnit to compare with.
Returns:: Set[GeneFamily] – Gene families unique to either this unit or the other.
Raises:: TypeError – If ‘other’ is not a SystemUnit instance.
Return type:: Set[GeneFamily]

property system: System | None#

Return the System instance this unit is associated with, or None if not assigned.

Returns:: System or None – The associated System object, or None if the unit is not linked to any system.