Getting Started

Installation

pipuvDevelopment

pip install pavvis

uv pip install pavvis

git clone https://github.com/<your-username>/pavvis.git
cd pavvis
pip install -e ".[dev]"

Loading your data

pavvis requires two CSV files to generate a PavMatrix object. The PavMatrix class is central to the pavvis workflow.:

• PAV matrix — genes as rows, samples as columns, values must be 0 or 1, i.e a binary matrix.
• Metadata — samples as rows, any number of metadata columns

from pavvis import PavMatrix

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

print(pm)
# PavMatrix(34295 genes × 1039 samples)

File formats

For examples of how these files should be formatted, see the concepts page.

When building the PavMatrix() class, pavvis will automatically validate that:

• Both files exist on the system
• Sample IDs of the PAV matrix columns match the metadata row indexes
• All PAV values are binary (0 or 1) with no blank cells

Exploring your data

Now you have generated a PavMatrix object, you can explore basic summary statistics using the class attributes.

# Get gene category counts
print(pm.gene_counts)
# {'core': 12, 'variable': 28761, 'absent': 5522}

# List gene IDs by category
print(pm.core_genes[:3])
print(pm.variable_genes[:3])
print(pm.absent_genes[:3])

# List exclusive variable genes for a metadata category
print(pm.exclusive_gene_counts("population_group"))
# {'GroupA': 183, 'GroupB': 204}

First plot

Aside from allowing the user to easily group and summarise their data, the pavvis package also provides functions that allow the user to generate plots for thier data. All of these functions are contained in the plots module.

import pavvis.plots as pp

# Histogram of presence frequencies (log y-axis)
pp.presence_frequency_histogram(pm).show()

# Bar chart of top 50 genes by presence frequency
pp.presence_frequency_histogram(pm, type="bar").show()