Pangenome

class panorama.pangenomes.Pangenome(name, taxid=None)

Bases: Pangenome

This is a class representing pangenome based on PPanGGOLLiN class. It is used as a basic unit for all the analysis to access to the different elements of your pangenome, such as organisms, contigs, genes or gene families. This class provides some more methods needed to analyze pangenome.

Parameters:

name – Name of the pangenome

property RNAs: Generator[Gene, None, None]

Generator of genes in the pangenome.

Returns:

gene generator

__init__(name, taxid=None)

Constructor method.

_create_gene_family(name)

Creates a gene family object with the given name

Parameters:

name (str) – The name to give to the gene family. Must not exist already.

Returns:

GeneFamily – The created GeneFamily object

Return type:

GeneFamily

_mk_contig_getter(check_name=False, name='')

Builds the attribute _contig_getter of the pangenome

Since the genes are never explicitly ‘added’ to a pangenome (but rather to an organism), the pangenome cannot directly extract a gene from a geneID since it does not ‘know’ them. If at some point we want to extract contig from a pangenome we’ll create a contig_getter. The assumption behind this is that the pangenome has been filled and no more contig will be added.

_mk_gene_getter()

Builds the attribute _gene_getter of the pangenome

Since the genes are never explicitly ‘added’ to a pangenome (but rather to a gene family, or a contig), the pangenome cannot directly extract a gene from a geneID since it does not ‘know’ them. If at some point we want to extract genes from a pangenome we’ll create a gene_getter. The assumption behind this is that the pangenome has been filled and no more gene will be added.

add_edge(gene1, gene2)

Adds an edge between the two gene families that the two given genes belong to.

Parameters:

• gene1 (Gene) – The first gene

• gene2 (Gene) – The second gene

Return type:

Edge

Returns:

The created Edge

Raises:

• AssertionError – Genes object are expected

• AttributeError – Genes are not associated to any families

add_file(pangenome_file, check_version=True)

Links an HDF5 file to the pan.

If needed elements will be loaded from this file, and anything that is computed will be saved to this file when ppanggolin.formats.writeBinaries.writePangenome() is called.

Parameters:

• pangenome_file (Path) – A string representing the filepath to the hdf5 pan file to be either used or created

• check_version (bool) – Check ppanggolin version of the pangenome file to be compatible with the current version of ppanggolin being used.

Raises:

• AssertionError – If the pangenome_file is not an instance of the Path class

• TypeError – If the pangenome_file is not a HDF5 format file

add_gene_family(family)

Adds a gene family to the pangenome

Parameters:

family (Union[GeneFamily, GeneFamily]) – GeneFamily object to add

add_module(module)

Add the given module to the pangenome

Parameters:

module (Module) – Module to add in pangenome

Raises:

• AssertionError – Error if module is not a Module object

• KeyError – Error if another module exist in pangenome with the same name

add_organism(organism)

Adds an organism that did not exist previously in the pangenome if an Organism object is provided. If an organism with the same name exists it will raise an error. If a str object is provided, will return the corresponding organism that has this name OR create a new one if it does not exist.

Parameters:

organism (Organism) – Organism to add to the pangenome

Raises:

• AssertionError – If the organism name is not a string

• KeyError – if the provided organism is already in pangenome

add_region(region)

Add a region to the pangenome

Parameters:

region (Region) – Region to add in pangenome

Raises:

• AssertionError – Error if region is not a Region object

• KeyError – Error if another Region exist in pangenome with the same name

add_spot(spot)

Adds the given iterable of spots to the pangenome.

Parameters:

spot (Spot) – Spot which should be added

Raises:

• AssertionError – Error if spot is not a Spot object

• KeyError – Error if another Spot exist in pangenome with the same identifier

add_system(system)

Add a detected system to the pangenome.

Parameters:

system (System) – Detected system to be added.

compute_family_bitarrays(part='all')

Based on the index generated by get_org_index, generate a bitarray for each gene family. If the family j is present in the organism with the index i, the bit at position i will be 1. If it is not, the bit will be 0. The bitarrays are gmpy2.xmpz object.

Parameters:

part (str) – Filter the organism in function of the given partition

Return type:

Dict[Organism, int]

Returns:

The index of organisms in pangenome

compute_mod_bitarrays(part='all')

Based on the index generated by get_fam_index, generated a bitarray for each gene family present in modules. If the family j is present in the module with the index i, the bit at position i will be 1. If it is not, the bit will be 0. The bitarrays are gmpy2.xmpz object.

Parameters:

part (str) – Filter the organism in function of the given partition

Return type:

Dict[GeneFamily, int]

Returns:

A dictionary with Organism as key and int as value.

compute_org_bitarrays(part='all')

Based on the index generated by get_fam_index, generate a bitarray for each gene family. If the family j is present in the organism with the index i, the bit at position i will be 1. If it is not, the bit will be 0. The bitarrays are gmpy2.xmpz object.

Parameters:

part – Filter the organism in function of the given partition

Return type:

Dict[GeneFamily, int]

Returns:

The index of gene families in pangenome

contig_lengths_unavailable()

Check if the pangenome has contig lengths unavailable

Return type:

bool

Returns:

True if contig lengths are unavailable, False otherwise

property contigs: Generator[Contig, None, None]

property edges: Generator[Edge, None, None]

Returns all the edges in the pangenome graph

Returns:

Generator of edge

exact_core_families()

Retrieves gene families considered as the exact core (present in all organisms).

Return type:

Set[GeneFamily]

Returns:

A set containing gene families identified as the exact core.

property gene_families: Generator[GeneFamily, None, None]

Returns all the gene families in the pangenome

Returns:

Generator[GeneFamily, None, None] – Generator of gene families

property genes: Generator[Gene, None, None]

Generator of genes in the pangenome.

Returns:

gene generator

get_contig(identifier=None, name=None, organism_name=None)

Returns the contig by his identifier or by his name. If name is given the organism name is needed

Parameters:

• identifier (int) – ID of the contig to look for

• name (str) – The name of the contig to look for

• organism_name (str) – Name of the organism to which the contig belong

Return type:

Contig

Returns:

Returns the wanted contig

Raises:

• AssertionError – If the contig_id is not an integer

• KeyError – If the contig is not in the pangenome

get_elem_by_metadata(metatype, **kwargs)

Get element in pangenome with metadata attribute expected

Parameters:

• metatype (str) – Select to which pangenome element metadata

• kwargs – attributes to identify metadata

Return type:

Generator[Union[GeneFamily, Gene, Organism, Region, Spot, Module], None, None]

Returns:

Metadata element

get_elem_by_source(source, metatype)

Get gene families with a specific source in pangenome

Parameters:

• source (str) – Name of the source

• metatype (str) – select to which pangenome element metadata should be written

Return type:

Generator[Union[GeneFamily, Gene, Contig, Organism, Region, Spot, Module], None, None]

Returns:

Gene families with the source

get_fam_index()

Creates an index for gene families (each family is assigned an Integer).

Return type:

Dict[GeneFamily, int]

Returns:

The index of families in pangenome

get_gene(gene_id)

Returns the gene that has the given gene ID

Parameters:

gene_id (str) – The gene ID to look for

Return type:

Gene

Returns:

Returns the gene that has the ID gene_id

Raises:

• AssertionError – If the gene_id is not a string

• KeyError – If the gene_id is not in the pangenome

get_gene_family(name)

Get the gene family by its name in the pangenome

Parameters:

name (str) – Name of the gene family to get

Returns:

Union[GeneFamily, None] – The desired gene family

Return type:

Optional[GeneFamily]

get_module(module_id)

Returns the module that has the given module ID.

Parameters:

module_id (Union[int, str]) – The module ID to look for. It can be an integer or a string in the format ‘module_<integer>’.

Return type:

Module

Returns:

The module with the specified ID.

Raises:

• KeyError – If the module ID does not exist in the pangenome.

• ValueError – If the provided module ID does not have the expected format.

get_multigenics(dup_margin, persistent=True)

Returns the multigenic persistent families of the pangenome graph. A family will be considered multigenic if it is duplicated in more than dup_margin of the genomes where it is present.

Parameters:

• dup_margin (float) – The ratio of presence in multicopy above which a gene family is considered multigenic

• persistent (bool) – if we consider only the persistent genes

Return type:

Set[GeneFamily]

Returns:

Set of gene families considered multigenic

get_org_index()

Creates an index for Organisms (each organism is assigned an Integer).

Return type:

Dict[Organism, int]

Returns:

The index of organisms in pangenome

get_organism(name)

Get an organism that is expected to be in the pangenome using its name, which is supposedly unique. Raises an error if the organism does not exist.

Parameters:

name (str) – Name of the Organism to get

Return type:

Organism

Returns:

The related Organism object

Raises:

• AssertionError – If the organism name is not a string

• KeyError – If the provided name is not an organism in the pangenome

get_region(name)

Returns a region with the given region_name. Creates it if it does not exist.

Parameters:

name (str) – The name of the region to return

Return type:

Region

Returns:

The region

Raises:

• AssertionError – If the RGP name is not a string

• KeyError – If the provided name is not a RGP in the pangenome

get_single_copy_persistent_families(dup_margin, exclude_fragments)

Retrieves gene families that are both persistent and single copy based on the provided criteria.

Parameters:

• dup_margin (float) – The maximum allowed duplication margin for a gene family to be considered single copy.

• exclude_fragments (bool) – A boolean indicating whether to exclude fragments when determining single copy families.

Return type:

Set[GeneFamily]

Returns:

A set containing gene families that are both persistent and single copy.

get_spot(spot_id)

Returns the spot that has the given spot ID.

Parameters:

spot_id (Union[int, str]) – The spot ID to look for. It can be an integer or a string in the format ‘spot_<integer>’.

Return type:

Spot

Returns:

The spot with the specified ID.

Raises:

• KeyError – If the spot ID does not exist in the pangenome.

• ValueError – If the provided spot ID does not have the expected format.

get_system(system_id)

Get a system by its ID in the pangenome

Parameters:

system_id (str) – ID of the system to get

Returns:

System – The desired system

Raises:

KeyError – If the system doesn’t exist in the pangenome

Return type:

System

get_system_by_source(source)

Retrieve systems by their source.

Parameters:

source (str) – Source identifier.

Yields:

Generator[System, None, None] – Systems with the given source.

has_metadata()

Whether or not the pangenome has metadata associated with any of its elements.

Return type:

bool

property max_fam_id

Get the last family identifier

metadata(metatype)

Create a generator with all metadatas in the pangenome

Parameters:

metatype (str) – Select to which pangenome element metadata should be generate

Return type:

Generator[Metadata, None, None]

Returns:

Set of metadata source

metadata_sources(metatype)

Returns all the metadata source in the pangenomes

Parameters:

metatype (str) – Select to which pangenome element metadata should be searched

Return type:

Set[str]

Returns:

Set of metadata source

Raises:

AssertionError – Error if metatype is not a string

property modules: Generator[Module, None, None]

Generate modules in the pangenome

property number_of_contigs: int

Returns the number of contigs present in the pangenome

Returns:

The number of contigs

property number_of_edges: int

Returns the number of edge present in the pangenome

Returns:

The number of gene families

property number_of_gene_families: int

Returns the number of gene families present in the pangenome

Returns:

The number of gene families

property number_of_genes: int

Returns the number of gene present in the pangenome

Returns:

The number of genes

property number_of_modules: int

Returns the number of modules present in the pangenome

Returns:

The number of modules

property number_of_organisms: int

Returns the number of organisms present in the pangenome

Returns:

The number of organism

property number_of_rgp: int

Returns the number of gene families present in the pangenome

Returns:

The number of gene families

property number_of_rnas: int

Returns the number of gene present in the pangenome

Returns:

The number of genes

property number_of_spots: int

Returns the number of gene families present in the pangenome

Returns:

The number of gene families

number_of_systems(source=None, with_canonical=True)

Get the number of systems in the pangenome.

Parameters:

• source (str) – Source identifier. Defaults to None.

• with_canonical (bool) – Include canonical systems. Defaults to True.

Returns:

int – Number of systems.

Return type:

int

property organisms: Generator[Organism, None, None]

Returns all the organisms in the pangenome

Returns:

Generator ppanggolin.genome.Organism

property regions: Generator[Region, None, None]

returns all the regions (RGP) in the pangenome

Returns:

list of RGP

select_elem(metatype)

Get all the element for the given metatype

Parameters:

metatype (str) – Name of pangenome component that will be get

Returns:

All elements from pangenome for the metatype

Raises:

• AssertionError – Error if metatype is not a string

• KeyError – Error if metatype is not recognized

soft_core_families(soft_core_threshold)

Retrieves gene families considered part of the soft core based on the provided threshold.

Parameters:

soft_core_threshold (float) – The threshold to determine the minimum fraction of organisms required for a gene family to be considered part of the soft core.

Return type:

Set[GeneFamily]

Returns:

A set containing gene families identified as part of the soft core.

property spots: Generator[Spot, None, None]

Generate spots in the pangenome

Returns:

Spot generator

property systems: Generator[System, None, None]

Get all systems in the pangenome

Yields:

Generator[System, None, None] – Generator of systems

property systems_sources: Set[str]

Get sources of all systems in the pangenome

Returns:

Set[str] – Set of system sources

systems_sources_to_metadata_source()

Get metadata sources related to system sources

Returns:

Dict[str, Set[str]] – System source as key linked to their metadata sources as value

Return type:

Dict[str, Set[str]]