Variable gene plots

This submodule contains plotting functions for visualising and exploring the variable gene pool within a PAV matrix. Variable genes — those present in at least one but not all samples — are often the most biologically informative component of a pangenome. These plots help characterise the distribution and exclusivity of variable gene content across groups defined in a metadata.csv file.

Presence frequency distribution

Description

The frequency of presence for a single gene can be calculated using the following calculation:

\[ \text{presence frequency} = \frac{\text{number of samples where gene} = 1}{\text{total number of samples}} \]

The result is a value in the range [0, 1], where 0 indicates a gene is absent in all samples and 1 means it is present in every sample. After presence frequency has been calculated for each gene, a histogram can be plotted to summarise the distribution of presence across all genes.

Unlike the presence frequency histogram in the presence submodule, this plot colours each bin by gene category — absent, private, dispensable, soft core, and core — so the composition of each frequency range is visible at a glance.

This plot can be useful as a first-pass overview of the variable gene pool — a heavily left-skewed distribution indicates most variable genes are rare across the sample set, which is typical of an open pangenome. A distribution concentrated at higher frequencies suggests a more closed pangenome where most variable genes are shared broadly across the sample set.

Function

`pavvis.plots.variable_genes.frequency_histogram(pm, n_bins=20, exclude_absent=False, exclude_core=False, log_y=False)`

Plot gene presence frequency as a stacked histogram coloured by gene category.

Each bin is subdivided by category — absent, private, dispensable, soft core, and core — so the composition of each frequency range is visible at a glance. Categories are determined by the thresholds stored on the PavMatrix instance.

Parameters:

Name	Type	Description	Default
`pm`	`PavMatrix`	A PavMatrix instance.	required
`n_bins`	`int`	Number of equal-width bins across [0, 1]. Defaults to 20.	`20`
`exclude_absent`	`bool`	If True, absent genes (frequency = 0) are not shown. Defaults to False.	`False`
`exclude_core`	`bool`	If True, core genes (frequency = 1) are not shown. Defaults to False.	`False`
`log_y`	`bool`	If True, display the y-axis on a log10 scale. Defaults to False.	`False`

Returns:

Type	Description
`Figure`	A Plotly Figure. Call .show() to display or .write_html() to export.

Example

from pavvis import PavMatrix
import pavvis.plots.variable_genes as vg

pm = PavMatrix(
    matrix_path="path/to/pav.csv",
    metadata_path="path/to/metadata.csv",
)

vg.frequency_histogram(pm, log_y=True).show()

Interpretation

The stacked colouring reveals the category composition at each frequency bin. A dominant private (low-frequency) bar suggests the pangenome is open and highly variable. A dominant soft-core or core bar at high frequencies suggests a more closed pangenome where most genes are conserved across samples.

Exclusive genes

Description

An exclusive gene is a variable gene present in at least one sample within a group and absent from every sample outside that group. Plotting exclusive gene counts per group allows the researcher to identify which groups harbour gene content that is not shared with any other group in the dataset.

A high exclusive gene count within a group may indicate lineage-specific content, such as adaptation to a local environment, unique metabolic capabilities, or a functional repertoire distinct from the rest of the sample set. Conversely, groups with very few exclusive genes may be more genomically similar to the broader population or may have fewer samples represented.

Function

`pavvis.plots.variable_genes.exclusive_genes_bar(pm, column, log_y=False)`

Plot the number of exclusive variable genes per group in a metadata column.

An exclusive gene is a variable gene that is present in at least one sample within a group and absent from every sample outside that group. Each bar represents one group; the height is its exclusive gene count.

Only discrete metadata columns are supported.

Parameters:

Name	Type	Description	Default
`pm`	`PavMatrix`	A PavMatrix instance.	required
`column`	`str`	A discrete metadata column to group samples by.	required
`log_y`	`bool`	If True, display the y-axis on a log10 scale. Defaults to False.	`False`

Returns:

Type	Description
`Figure`	A Plotly Figure. Call .show() to display or .write_html() to export.

Raises:

Type	Description
`ValueError`	If column is not a discrete metadata column.

Example

from pavvis import PavMatrix
import pavvis.plots.variable_genes as vg

pm = PavMatrix(
    matrix_path="path/to/pav.csv",
    metadata_path="path/to/metadata.csv",
)

vg.exclusive_genes_bar(pm, column="clade").show()

Interpretation

Tall bars indicate groups with a large number of genes found nowhere else in the dataset, suggesting lineage-specific gene content. Groups with very few exclusive genes may be more genomically similar to the rest of the population or may simply have fewer samples represented.