geneviewer
0.3.11GitHub

geneviewer for Python ​

The Python package builds the same charts as the R package and the JavaScript library, from pandas data frames, and shows them in Jupyter notebooks and in Shiny for Python. It reads GenBank, GFF, FASTA and BED files and aligns clusters, as the R package does: the articles in the sidebar go through each, from GenBank files to a published figure.

These pages describe version 0.2.1.

Installation ​

sh
pip install "geneviewer-py[jupyter]"

The distribution is geneviewer-py and the import name is geneviewer. It needs Python 3.11 or later and pandas. The extras add what a part of the package needs:

ExtraFor
jupyterCharts in Jupyter notebooks
shinyCharts in Shiny for Python
alignprotein_blast(), which aligns with Biopython

Your first chart ​

GC() makes a chart from a table of genes: a pandas DataFrame with a row per gene and a column for its start and its end. This uses the ophA_clusters dataset of the package:

python
from geneviewer import GC, datasets

clusters = datasets.load("ophA_clusters")
ophA = clusters[clusters["cluster"] == "ophA"]

chart = GC(ophA, group="class", height="150px")

In a Jupyter notebook, a cell that ends with the chart draws it. In a Shiny app, an output draws it. This is the whole app for the chart above; save it as app.py and run shiny run app.py:

python
from shiny import App, ui

from geneviewer import GC, datasets
from geneviewer.shiny import output_geneviewer, render_geneviewer

clusters = datasets.load("ophA_clusters")
ophA = clusters[clusters["cluster"] == "ophA"]

app_ui = ui.page_fluid(output_geneviewer("chart", height="150px"))


def server(input, output, session):
    @render_geneviewer
    def chart():
        return GC(ophA, group="class", height="150px")


app = App(app_ui, server)

Shiny for Python has the events a chart reports and how to move its zoom slider from the server.

Adding to a chart ​

Each method of a chart adds a part or changes one, and returns a new chart, so the calls are chained. With cluster, each cluster gets its own row:

python
chart = (
    GC(clusters, cluster="cluster", group="class", height="300px")
    .title("Omphalotin gene clusters", height="40px")
    .labels("name")
    .links(group="class", label=False)
    .cluster_label(["<i>O. olearius</i>", "<i>D. bispora</i>"])
    .scale_bar()
    .legend(position="bottom")
)

The methods are the GC_ functions of the R package under Python names: GC_clusterLabel() is .cluster_label(), and its argument titleFont is title_font. The reference describes each method.

The guide explains every part of a chart with live examples in R and JavaScript. What it says about an R function holds for the Python method of the same name. Options that take a list in R take a dict in Python, with the names the guide uses:

python
chart = (
    GC(clusters, cluster="cluster", group="class", height="260px")
    .labels("name", font_size="11px")
    .genes(marker="boxarrow", marker_size="small")
    .theme("vintage")
)

chart.to_spec() returns the chart as the spec the JavaScript library draws: a dict that can be written as JSON and drawn on any web page with geneviewer.newChart().

Example datasets ​

The package has the 11 datasets of the R package, as pandas DataFrames:

python
from geneviewer import datasets

datasets.names()
transcripts = datasets.load("BRCA1_splice_variants")

The reference lists them. A table of exons and UTRs is drawn as transcripts with .transcript(), which adds the introns:

python
from geneviewer import GC, datasets

transcripts = datasets.load("BRCA1_splice_variants")

chart = (
    GC(transcripts, height="450px")
    .transcript(transcript="ensembl_transcript_id", strand="strand", type="type")
    .cluster_title(
        list(transcripts["ensembl_transcript_id"].unique()),
        title_font={"fontSize": "12px"},
    )
)

Differences from the R package ​

The charts are the same: both packages write the same spec, and the Python package is tested against the specs the R package makes. The file readers give the same tables as R's. protein_blast() can give slightly different identities for some protein pairs, where several alignments are equally good.