genome-spy-python 0.1.0__py3-none-any.whl

genome_spy/datasets/_airway.py

@@ -0,0 +1,219 @@
+"""Internal helpers for the packaged airway RNA-seq examples."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import numpy as np
+
+from genome_spy.datasets import load_dataset
+
+if TYPE_CHECKING:
+    import pandas as pd
+
+
+_AIRWAY_GENE_SYMBOLS = {
+    "ENSG00000109906": "ZBTB16",
+    "ENSG00000116711": "PLA2G4A",
+    "ENSG00000145777": "TSLP",
+    "ENSG00000152583": "SPARCL1",
+}
+
+
+def airway_paired_logcounts(
+    *, min_base_mean: float = 10.0
+) -> tuple[pd.Series, pd.DataFrame, pd.DataFrame]:
+    """Load packaged airway counts as paired treated/control log-counts.
+
+    Description:
+        Reads the scaled-count table and sample metadata, filters genes by
+        mean count, transforms counts with ``log2(count + 1)``, and pivots the
+        eight samples into matching treated and control matrices by cell type.
+
+    Args:
+        min_base_mean: Minimum mean count required to retain a gene.
+
+    Returns:
+        The retained base means, treated log-count matrix, and control
+        log-count matrix. All three share the same gene index.
+
+    Raises:
+        ImportError: If pandas is not installed.
+
+    Example:
+        >>> base_mean, treated, control = airway_paired_logcounts()
+        >>> treated.shape == control.shape
+        True
+    """
+    counts = load_dataset("airway_scaledcounts", as_format="dataframe").set_index(
+        "ensgene"
+    )
+    metadata = load_dataset("airway_metadata", as_format="dataframe").set_index("id")
+
+    sample_ids = metadata.index.to_list()
+    count_matrix = counts.loc[:, sample_ids].copy()
+    base_mean = count_matrix.mean(axis=1)
+    count_matrix = count_matrix.loc[base_mean >= min_base_mean]
+    base_mean = base_mean.loc[count_matrix.index]
+
+    long_counts = (
+        np.log2(count_matrix + 1.0)
+        .reset_index()
+        .melt(id_vars="ensgene", var_name="id", value_name="log_count")
+        .merge(
+            metadata.loc[:, ["celltype", "dex"]].reset_index(),
+            on="id",
+            how="left",
+            validate="many_to_one",
+        )
+    )
+    paired = long_counts.pivot(
+        index="ensgene",
+        columns=["celltype", "dex"],
+        values="log_count",
+    )
+
+    celltype_order = metadata["celltype"].drop_duplicates().to_list()
+    control = paired.xs("control", axis=1, level="dex").loc[:, celltype_order]
+    treated = paired.xs("treated", axis=1, level="dex").loc[:, celltype_order]
+    return base_mean.loc[paired.index], treated, control
+
+
+def airway_differential_expression(
+    *,
+    min_base_mean: float = 10.0,
+    max_genes: int = 12_000,
+    log2fc_cutoff: float = 1.0,
+    pvalue_cutoff: float = 0.01,
+    padj_alpha: float = 0.1,
+) -> tuple[pd.DataFrame, dict[str, list[float]]]:
+    """Build the chart-ready airway differential-expression table.
+
+    Description:
+        Uses the paired treated/control log-count matrices from
+        :func:`airway_paired_logcounts`, computes paired t-tests and Benjamini-
+        Hochberg adjusted p-values, then adds the transformed fields and
+        significance classification shared by the MA and volcano examples.
+        A small curated set of genes also receives chart-ready callout labels
+        and label offsets.
+
+    Args:
+        min_base_mean: Minimum mean count required before testing.
+        max_genes: Keep at most this many genes by base mean for plotting.
+        log2fc_cutoff: Absolute fold-change threshold for significance labels.
+        pvalue_cutoff: Raw p-value threshold for significance labels.
+        padj_alpha: FDR level passed to the multiple-testing correction.
+
+    Returns:
+        A chart-ready result table and plotting domains.
+
+    Raises:
+        ImportError: If pandas, SciPy, or statsmodels is not installed.
+
+    Example:
+        >>> data, domains = airway_differential_expression(max_genes=200)
+        >>> {"log2fc", "pvalue", "padj"} <= set(data)
+        True
+    """
+    import pandas as pd
+    from scipy.stats import ttest_rel
+    from statsmodels.stats.multitest import fdrcorrection
+
+    base_mean, treated, control = airway_paired_logcounts(min_base_mean=min_base_mean)
+    log2fc = treated.subtract(control).mean(axis=1)
+    test = ttest_rel(treated.to_numpy(), control.to_numpy(), axis=1, nan_policy="omit")
+    pvalue = np.asarray(test.pvalue, dtype=float)
+    pvalue = np.where(
+        ~np.isfinite(pvalue) & np.isclose(log2fc.to_numpy(), 0.0), 1.0, pvalue
+    )
+    pvalue = np.where(~np.isfinite(pvalue), 0.0, pvalue)
+    _rejected, padj = fdrcorrection(pvalue, alpha=padj_alpha)
+
+    data = pd.DataFrame(
+        {
+            "ensgene": treated.index,
+            "base_mean": base_mean.loc[treated.index].to_numpy(),
+            "log2fc": log2fc.to_numpy(),
+            "pvalue": pvalue,
+            "padj": padj,
+        }
+    )
+    data["neglog10_pvalue"] = -np.log10(np.clip(data["pvalue"], 1e-300, 1.0))
+    data["neglog10_padj"] = -np.log10(np.clip(data["padj"], 1e-300, 1.0))
+    data["log10_base_mean"] = np.log10(data["base_mean"])
+    passes = (data["pvalue"] < pvalue_cutoff) & (data["log2fc"].abs() >= log2fc_cutoff)
+    data["direction"] = np.where(
+        passes & (data["log2fc"] > 0),
+        "up in dex",
+        np.where(passes & (data["log2fc"] < 0), "down in dex", "n.s."),
+    )
+    data = data.nlargest(max_genes, "base_mean").sort_values("log10_base_mean")
+
+    log2fc_extent = float(np.ceil(data["log2fc"].abs().max() * 2) / 2)
+    volcano_y_max = float(np.ceil(data["neglog10_pvalue"].quantile(0.995) / 5) * 5)
+    data["neglog10_pvalue_plot"] = np.minimum(data["neglog10_pvalue"], volcano_y_max)
+    volcano_x_extent = float(np.ceil(data["log2fc"].abs().max() * 2) / 2)
+    domains = {
+        "ma_x": [
+            float(np.floor(data["log10_base_mean"].min() * 2) / 2),
+            float(np.ceil(data["log10_base_mean"].max() * 2) / 2),
+        ],
+        "ma_y": [-log2fc_extent, log2fc_extent],
+        "volcano_x": [-volcano_x_extent, volcano_x_extent],
+        "volcano_y": [0.0, volcano_y_max],
+        "pvalue_cutoff": [-float(np.log10(pvalue_cutoff))],
+    }
+    data["gene_symbol"] = data["ensgene"].map(_AIRWAY_GENE_SYMBOLS)
+    _add_airway_annotation_positions(data)
+    return data, domains
+
+
+def _add_airway_annotation_positions(data: pd.DataFrame) -> None:
+    """Add sparse label endpoints used by the airway gallery examples."""
+    # Pixel offsets keep annotation spacing stable while the reader zooms. The
+    # side tells the text mark to extend away from the leader endpoint.
+    volcano_offsets = {
+        "ZBTB16": (-30, -32),
+        "PLA2G4A": (-30, -38),
+        "TSLP": (-36, 28),
+    }
+    ma_offsets = {
+        "ZBTB16": (48, 16),
+        "PLA2G4A": (-36, 16),
+        "SPARCL1": (48, 15),
+    }
+
+    data["volcano_label"] = data["gene_symbol"].where(
+        data["gene_symbol"].isin(volcano_offsets)
+    )
+    data["ma_label"] = data["gene_symbol"].where(data["gene_symbol"].isin(ma_offsets))
+
+    volcano_dx = data["gene_symbol"].map(
+        {symbol: offset[0] for symbol, offset in volcano_offsets.items()}
+    )
+    volcano_dy = data["gene_symbol"].map(
+        {symbol: offset[1] for symbol, offset in volcano_offsets.items()}
+    )
+    ma_dx = data["gene_symbol"].map(
+        {symbol: offset[0] for symbol, offset in ma_offsets.items()}
+    )
+    ma_dy = data["gene_symbol"].map(
+        {symbol: offset[1] for symbol, offset in ma_offsets.items()}
+    )
+
+    data["volcano_x_offset"] = volcano_dx
+    data["volcano_y_offset"] = volcano_dy
+    data["volcano_label_side"] = data["gene_symbol"].map(
+        {
+            symbol: "left" if offset[0] < 0 else "right"
+            for symbol, offset in volcano_offsets.items()
+        }
+    )
+    data["ma_x_offset"] = ma_dx
+    data["ma_y_offset"] = ma_dy
+    data["ma_label_side"] = data["gene_symbol"].map(
+        {
+            symbol: "left" if offset[0] < 0 else "right"
+            for symbol, offset in ma_offsets.items()
+        }
+    )

genome_spy/datasets/_annotations.py

@@ -0,0 +1,37 @@
+"""Internal helpers for the packaged RefSeq gene-body annotations."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Literal
+
+from genome_spy.datasets import load_dataset
+
+if TYPE_CHECKING:
+    import pandas as pd
+
+
+def refseq_gene_bodies(assembly: Literal["hg19", "hg38"]) -> pd.DataFrame:
+    """Load an assembly-wide RefSeq gene-body annotation table.
+
+    Description:
+        Loads gene bodies independently prepared from assembly-matched UCSC
+        RefSeq records. Coordinates are zero-based and half-open. The number
+        of contributing transcript records is intended only for label
+        prioritization.
+
+    Args:
+        assembly: UCSC assembly identifier.
+    Returns:
+        A chart-ready table containing every packaged gene body for the
+        requested assembly.
+
+    Raises:
+        ImportError: If pandas is not installed.
+
+    Example:
+        >>> genes = refseq_gene_bodies("hg38")
+        >>> "STK3" in set(genes["symbol"])
+        True
+    """
+    genes = load_dataset("refseq_gene_bodies", as_format="dataframe")
+    return genes.loc[genes["assembly"].eq(assembly)].reset_index(drop=True)

genome_spy/datasets/_gistic.py

@@ -0,0 +1,43 @@
+"""Load the complete packaged TCGA OV GISTIC2 example results."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, TypedDict
+
+from genome_spy.datasets import load_dataset
+
+if TYPE_CHECKING:
+    import pandas as pd
+
+
+class TcgaOvGisticData(TypedDict):
+    """Chart tables returned for the TCGA OV GISTIC landscape."""
+
+    scores: pd.DataFrame
+    lesions: pd.DataFrame
+
+
+def tcga_ov_gistic_data() -> TcgaOvGisticData:
+    """Load the TCGA OV GISTIC2 data displayed by the gallery example.
+
+    Description:
+        The tables are the complete ``scores.gistic`` and
+        ``all_lesions.conf_99.txt`` files used by GenomeSpy's TCGA OV example.
+        They originate from the TCGA OV-TP GISTIC2 Level 4 archive published by
+        the Broad GDAC Firehose on 2016-01-28 and use hg19 coordinates. The
+        copies are retained locally so rendering does not depend on
+        GenomeSpy's external data host.
+
+    Returns:
+        Score and lesion tables for the displayed genomic interval.
+
+    Raises:
+        ImportError: If pandas is not installed.
+
+    Example:
+        >>> tcga_ov_gistic_data()["scores"].head()
+    """
+    return {
+        "scores": load_dataset("tcga_ov_gistic_scores", as_format="dataframe"),
+        "lesions": load_dataset("tcga_ov_gistic_lesions", as_format="dataframe"),
+    }

genome_spy/datasets/_grammar.py

@@ -0,0 +1,66 @@
+"""Small deterministic tables used by grammar gallery examples."""
+
+from __future__ import annotations
+
+import math
+
+import pandas as pd
+
+
+def sincos_data() -> pd.DataFrame:
+    """Return a compact table for point and composition examples."""
+    return pd.DataFrame({"x": range(31)})
+
+
+def heatmap_data() -> pd.DataFrame:
+    """Return a deterministic grid with a smooth quantitative value."""
+    rows = [
+        {"x": x, "y": y, "z": math.sin(x / 8) + math.cos(y / 10 - 0.5)}
+        for y in range(20)
+        for x in range(40)
+    ]
+    return pd.DataFrame(rows)
+
+
+def ranged_rule_data() -> pd.DataFrame:
+    """Return intervals for the ranged-rule example."""
+    return pd.DataFrame(
+        [
+            {"y": "A", "x": 2, "x2": 7},
+            {"y": "B", "x": 0, "x2": 3},
+            {"y": "B", "x": 5, "x2": 6},
+            {"y": "C", "x": 4, "x2": 8},
+            {"y": "D", "x": 1, "x2": 5},
+        ]
+    )
+
+
+def link_data() -> pd.DataFrame:
+    """Return interval pairs for the link-mark example."""
+    return pd.DataFrame(
+        [
+            {"x": 1, "x2": 5, "y": 2},
+            {"x": 3, "x2": 8, "y": 4},
+            {"x": 5, "x2": 11, "y": 6},
+            {"x": 7, "x2": 13, "y": 8},
+            {"x": 9, "x2": 16, "y": 10},
+        ]
+    )
+
+
+def sequence_logo_data() -> pd.DataFrame:
+    """Return base counts for a small sequence-logo example."""
+    return pd.DataFrame(
+        [
+            {"pos": 1, "base": "A", "count": 2},
+            {"pos": 1, "base": "C", "count": 3},
+            {"pos": 1, "base": "T", "count": 5},
+            {"pos": 2, "base": "A", "count": 7},
+            {"pos": 2, "base": "C", "count": 3},
+            {"pos": 3, "base": "A", "count": 10},
+            {"pos": 4, "base": "T", "count": 9},
+            {"pos": 4, "base": "G", "count": 1},
+            {"pos": 5, "base": "G", "count": 8},
+            {"pos": 6, "base": "G", "count": 7},
+        ]
+    )

genome_spy/datasets/_hapmap.py

@@ -0,0 +1,180 @@
+"""Prepared HapMap tables used by association-plot examples."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import numpy as np
+
+from genome_spy.datasets import load_dataset
+
+if TYPE_CHECKING:
+    import pandas as pd
+
+
+def hapmap_manhattan_data(
+    *, genome_wide_p: float = 5e-8, suggestive_p: float = 1e-5
+) -> tuple[pd.DataFrame, pd.DataFrame, dict[str, float | list[float]]]:
+    """Build chart tables for the packaged HapMap Manhattan example.
+
+    Description:
+        Loads ``CHR``, ``BP``, ``P``, and annotation columns from the HapMap
+        GWAS table, removes invalid p-values, adds chromosome labels and
+        ``-log10(P)``, and selects the eight smallest p-values for labels.
+
+    Args:
+        genome_wide_p: P-value used for the genome-wide guide line.
+        suggestive_p: P-value used for the suggestive guide line.
+
+    Returns:
+        The transformed point table, top-hit table, and y-axis metadata.
+
+    Raises:
+        ImportError: If pandas is not installed.
+
+    Example:
+        >>> points, top_hits, domains = hapmap_manhattan_data()
+        >>> "neglog" in points
+        True
+    """
+    data = load_dataset("hapmap_gwas", as_format="dataframe")
+    data = data[data["P"] > 0].copy()
+    data["chrom"] = np.where(
+        data["CHR"] == 23,
+        "chrX",
+        "chr" + data["CHR"].astype(str),
+    )
+    data["neglog"] = -np.log10(data["P"])
+    data["chrom_group"] = np.where(data["CHR"] % 2 == 0, "even", "odd")
+    top_hits = data.nsmallest(8, "P")
+    y_domain = [0.0, float(np.ceil(data["neglog"].max()))]
+    return (
+        data,
+        top_hits,
+        {
+            "y_domain": y_domain,
+            "genome_wide_y": float(-np.log10(genome_wide_p)),
+            "suggestive_y": float(-np.log10(suggestive_p)),
+        },
+    )
+
+
+def hapmap_volcano_data(
+    *, effect_cutoff: float = 0.5, pvalue_cutoff: float = 1e-5
+) -> tuple[pd.DataFrame, dict[str, float | list[float]]]:
+    """Build the chart-ready HapMap volcano table and domains.
+
+    Description:
+        Loads the HapMap association table, transforms p-values to ``-log10(P)``,
+        and classifies points by effect direction and the supplied thresholds.
+
+    Args:
+        effect_cutoff: Minimum absolute effect size for a labelled point.
+        pvalue_cutoff: Maximum p-value for a labelled point.
+
+    Returns:
+        The transformed point table and plotting domains.
+
+    Raises:
+        ImportError: If pandas is not installed.
+
+    Example:
+        >>> data, domains = hapmap_volcano_data()
+        >>> "association" in data
+        True
+    """
+    data = load_dataset("hapmap_gwas", as_format="dataframe")
+    data = data[data["P"] > 0].copy()
+    data["neglog"] = -np.log10(data["P"])
+    passes = (data["P"] < pvalue_cutoff) & (data["EFFECTSIZE"].abs() >= effect_cutoff)
+    data["association"] = np.where(
+        passes & (data["EFFECTSIZE"] > 0),
+        "risk",
+        np.where(passes & (data["EFFECTSIZE"] < 0), "protective", "n.s."),
+    )
+    x_extent = float(np.ceil(data["EFFECTSIZE"].abs().max() * 10) / 10)
+    return data, {
+        "x_domain": [-x_extent, x_extent],
+        "y_domain": [0.0, float(np.ceil(data["neglog"].max()))],
+        "effect_cutoff": effect_cutoff,
+        "neglog_pvalue_cutoff": float(-np.log10(pvalue_cutoff)),
+    }
+
+
+def hapmap_qq_data(
+    *, bins: int = 45
+) -> tuple[pd.DataFrame, pd.DataFrame, dict[str, float]]:
+    """Build the chart-ready HapMap QQ and deviation tables.
+
+    Description:
+        Sorts valid HapMap p-values, pairs observed and expected quantiles, and
+        bins their deviation for the lower summary strip.
+
+    Args:
+        bins: Number of expected-quantile bins used for the deviation summary.
+
+    Returns:
+        The QQ table, binned deviation table, and plotting limits.
+
+    Raises:
+        ImportError: If pandas is not installed.
+
+    Example:
+        >>> qq, deviation, domains = hapmap_qq_data()
+        >>> {"expected", "observed"} <= set(qq)
+        True
+    """
+    import pandas as pd
+
+    pvals = np.sort(
+        load_dataset("hapmap_gwas", as_format="dataframe")
+        .query("P > 0")["P"]
+        .to_numpy()
+    )
+    ranks = np.arange(1, len(pvals) + 1)
+    data = pd.DataFrame(
+        {
+            "expected": -np.log10((ranks - 0.5) / len(pvals)),
+            "observed": -np.log10(pvals),
+        }
+    )
+    data["delta"] = data["observed"] - data["expected"]
+    data["pattern"] = np.where(
+        data["delta"] > 0.45, "Tail enrichment", "Null-like bulk"
+    )
+
+    edges = np.linspace(0.0, float(data["expected"].max()), bins + 1)
+    deviation = (
+        data.assign(
+            bin=pd.cut(
+                data["expected"],
+                bins=edges,
+                include_lowest=True,
+                duplicates="drop",
+            )
+        )
+        .groupby("bin", observed=True, as_index=False)
+        .agg(delta_mean=("delta", "mean"))
+    )
+    intervals = deviation["bin"]
+    deviation["x0"] = intervals.map(lambda interval: float(interval.left))
+    deviation["x1"] = intervals.map(lambda interval: float(interval.right))
+    deviation["zero"] = 0.0
+    deviation["direction"] = np.where(
+        deviation["delta_mean"] >= 0,
+        "Observed > expected",
+        "Observed < expected",
+    )
+    deviation = deviation[["x0", "x1", "zero", "delta_mean", "direction"]]
+    limit = float(max(data["expected"].max(), data["observed"].max())) * 1.02
+    delta_limit = float(max(abs(deviation["delta_mean"]).max(), 0.25)) * 1.1
+    return (
+        data,
+        deviation,
+        {
+            "limit": limit,
+            "delta_limit": delta_limit,
+            "annotation_x": round(limit * 0.54, 2),
+            "tail_y": round(limit * 0.93, 2),
+        },
+    )