PavMatrix
pavvis.pav_matrix.PavMatrix
Constructor
The PavMatrix() class is the core data structure behind pavvis. By default, all that is required to generate it is
a pav.csv and accompanying metadata.csv file.
File formats
For more information on how these input files should be structured, see the concepts page.
pavvis.pav_matrix.PavMatrix.__init__(matrix_path, metadata_path, soft_core_min=0.95, dispensable_min=0.15, private_min=0.0)
Load and validate a PAV matrix with associated sample metadata.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
matrix_path
|
str | Path
|
Path to the PAV matrix CSV. Genes must be rows (unique index), samples must be columns (unique headers), values must be 0 or 1. |
required |
metadata_path
|
str | Path
|
Path to the metadata CSV. Samples must be rows (index must match PAV matrix column headers exactly). |
required |
soft_core_min
|
float
|
Minimum presence frequency for soft core genes (inclusive). Defaults to 0.95. |
0.95
|
dispensable_min
|
float
|
Minimum presence frequency for dispensable genes (inclusive). Defaults to 0.15. |
0.15
|
private_min
|
float
|
Minimum presence frequency for private genes (exclusive lower bound — genes at exactly this frequency are excluded). Defaults to 0.0. |
0.0
|
Raises:
| Type | Description |
|---|---|
FileNotFoundError
|
If either file path does not exist. |
ValueError
|
If sample IDs do not match between files, if any PAV value is not 0 or 1, if any cell is blank, or if thresholds are invalid. |
Identity & IDs
pavvis.pav_matrix.PavMatrix.__repr__()
Return a summary string of the form 'PavMatrix(N genes × M samples)'.
pavvis.pav_matrix.PavMatrix.sample_ids
property
Sample identifiers, taken from the PAV matrix column headers.
Returns:
| Type | Description |
|---|---|
list[str]
|
List of sample ID strings. |
pavvis.pav_matrix.PavMatrix.gene_ids
property
Gene identifiers, taken from the PAV matrix row index.
Returns:
| Type | Description |
|---|---|
list[str]
|
List of gene ID strings. |
pavvis.pav_matrix.PavMatrix.metadata_columns
property
Column names present in the loaded metadata DataFrame.
Returns:
| Type | Description |
|---|---|
list[str]
|
List of metadata column name strings. |
Gene categories
pavvis.pav_matrix.PavMatrix.gene_counts
property
Count of genes in each category and subcategory.
Returns:
| Type | Description |
|---|---|
dict[str, int]
|
Dict with keys 'core', 'soft_core', 'dispensable', 'private', and 'absent' |
dict[str, int]
|
mapping to integer counts. |
pavvis.pav_matrix.PavMatrix.core_genes
property
Genes present in every sample (all values equal 1).
Returns:
| Type | Description |
|---|---|
list[str]
|
List of gene ID strings. |
pavvis.pav_matrix.PavMatrix.absent_genes
property
Genes absent from every sample (all values equal 0).
Returns:
| Type | Description |
|---|---|
list[str]
|
List of gene ID strings. |
pavvis.pav_matrix.PavMatrix.variable_genes
property
Genes present in at least one but not all samples.
Returns:
| Type | Description |
|---|---|
list[str]
|
List of gene ID strings. |
Variable gene subcategories
pavvis.pav_matrix.PavMatrix.thresholds
property
Current variable gene subcategory thresholds.
Returns:
| Type | Description |
|---|---|
dict[str, float]
|
Dict with keys 'soft_core_min', 'dispensable_min', 'private_min'. |
pavvis.pav_matrix.PavMatrix.soft_core_genes
property
Variable genes present in >= soft_core_min and < 1.0 of samples.
Returns:
| Type | Description |
|---|---|
list[str]
|
List of gene ID strings. |
pavvis.pav_matrix.PavMatrix.dispensable_genes
property
Variable genes present in >= dispensable_min and < soft_core_min of samples.
Returns:
| Type | Description |
|---|---|
list[str]
|
List of gene ID strings. |
pavvis.pav_matrix.PavMatrix.private_genes
property
Variable genes present in > private_min and < dispensable_min of samples.
Returns:
| Type | Description |
|---|---|
list[str]
|
List of gene ID strings. |
pavvis.pav_matrix.PavMatrix.presence_frequency
property
Fraction of samples in which each gene is present.
Returns:
| Type | Description |
|---|---|
Series
|
pd.Series indexed by gene ID, with values in [0.0, 1.0]. |
Exclusive genes
pavvis.pav_matrix.PavMatrix.exclusive_gene_counts(column)
Count exclusive variable genes for each group in a discrete metadata column.
An exclusive gene is a variable gene present in at least one sample within a group and absent from every sample outside that group.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
column
|
str
|
A discrete metadata column name. |
required |
Returns:
| Type | Description |
|---|---|
dict[str, int]
|
Dict mapping each group label to its exclusive gene count, sorted |
dict[str, int]
|
alphabetically by group label. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If column is not found in metadata. |
UMAP
Uniform Manifold Approximation Projection (UMAP) is a dimensionality reduction technique that is used to
visualise high-dimensional data. In the context of PAV, it can help gain insight into the relationships between samples
through similarity in PAV profiles. Generating UMAP embeddings can be done by calling the compute_umap() method. This
is not automatically called on initial construction of new PavMatrix() objects, as it can be computationally
intensive, particularly for large datasets.
pavvis.pav_matrix.PavMatrix.compute_umap(n_neighbors=15, min_dist=0.1, metric='jaccard', random_state=None)
Compute a 3D UMAP embedding of the samples and cache it on this object.
Always computes 3 components so the result can be used for both 2D and 3D plots without recomputing. The embedding is computed on the transposed PAV matrix (samples × genes). Re-calling with the same parameters returns the cached result immediately. Re-calling with different parameters recomputes and overwrites the cache.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
n_neighbors
|
int
|
UMAP n_neighbors parameter. Controls local vs global structure. Defaults to 15. |
15
|
min_dist
|
float
|
UMAP min_dist parameter. Controls how tightly points are packed. Defaults to 0.1. |
0.1
|
metric
|
str
|
Distance metric passed to UMAP. Defaults to 'jaccard', which ignores shared absences and is appropriate for binary PAV data. |
'jaccard'
|
random_state
|
int | None
|
Random seed for reproducibility. Defaults to None. |
None
|
Returns:
| Type | Description |
|---|---|
PavMatrix
|
self, so calls can be chained: pm.compute_umap().plot... |