locuscomparepy 0.1.0__py3-none-any.whl

locuscompare/__init__.py

@@ -0,0 +1,25 @@
+"""locuscompare: visualize GWAS-QTL colocalization events.
+
+Python port of the R package ``locuscomparer``
+(https://github.com/boxiangliu/locuscomparer).
+"""
+from .analysis import assign_color, get_lead_snp
+from .core import locuscompare
+from .datasets import example_path
+from .db import get_position, retrieve_LD
+from .io import read_metal
+from .plot import make_combined_plot, make_locuszoom, make_scatterplot
+
+__version__ = "0.1.0"
+__all__ = [
+    "read_metal",
+    "get_position",
+    "retrieve_LD",
+    "get_lead_snp",
+    "assign_color",
+    "make_scatterplot",
+    "make_locuszoom",
+    "make_combined_plot",
+    "locuscompare",
+    "example_path",
+]

locuscompare/analysis.py

@@ -0,0 +1,47 @@
+"""Lead-SNP selection and LD colouring (port of R ``get_lead_snp`` and ``assign_color``)."""
+import pandas as pd
+
+_LD_BINS = [0.0, 0.2, 0.4, 0.6, 0.8, 1.0]
+_LD_LABELS = ["blue4", "skyblue", "darkgreen", "orange", "red"]
+
+
+def get_lead_snp(merged, snp=None):
+    """Return the lead SNP rsID.
+
+    When ``snp`` is ``None``, the lead is ``argmin(pval1 + pval2)`` if p-values are
+    usable (no ``NaN`` and all > 0), otherwise ``argmax(logp1 + logp2)`` -- the
+    fallback for z-score / logp input or underflowed p-values.
+    """
+    if snp is None:
+        p1, p2 = merged["pval1"], merged["pval2"]
+        use_pval = (
+            not p1.isna().any()
+            and not p2.isna().any()
+            and (p1 > 0).all()
+            and (p2 > 0).all()
+        )
+        if use_pval:
+            idx = (p1 + p2).idxmin()
+        else:
+            idx = (merged["logp1"] + merged["logp2"]).idxmax()
+        snp = merged.loc[idx, "rsid"]
+    else:
+        if snp not in set(merged["rsid"]):
+            raise ValueError(f"{snp} not found in the intersection of in_fn1 and in_fn2.")
+    return str(snp)
+
+
+def assign_color(rsid, snp, ld):
+    """Map each rsID to a colour by its r2 with ``snp``.
+
+    Returns a ``dict`` {rsid: colour}. The lead SNP is ``'purple'``; SNPs with no
+    LD record default to ``'blue4'``. Colours are binned as in the R package:
+    (0,0.2]->blue4, (0.2,0.4]->skyblue, (0.4,0.6]->darkgreen, (0.6,0.8]->orange,
+    (0.8,1]->red.
+    """
+    ld_lead = ld[ld["SNP_A"] == snp]
+    binned = pd.cut(ld_lead["R2"], bins=_LD_BINS, labels=_LD_LABELS, include_lowest=True)
+    b2c = dict(zip(ld_lead["SNP_B"].astype(str), binned.astype(object)))
+    colors = {str(r): b2c.get(str(r), "blue4") for r in rsid}
+    colors[str(snp)] = "purple"
+    return colors

locuscompare/config.py

@@ -0,0 +1,26 @@
+"""Database connection configuration.
+
+Mirrors the R package's approach of shipping the (read-only) connection
+parameters with the package so it works out of the box. Any field can be
+overridden with a ``LOCUSCOMPARE_DB_*`` environment variable.
+"""
+import os
+
+_DEFAULT = {
+    "host": "54.254.162.217",
+    "user": "locuscompare",
+    "password": "voddit-7rubfo-faqxoB",
+    "port": 31987,
+    "database": "colotool",
+}
+
+
+def get_db_config():
+    """Return the DB connection parameters, allowing ``LOCUSCOMPARE_DB_*`` overrides."""
+    return {
+        "host": os.environ.get("LOCUSCOMPARE_DB_HOST", _DEFAULT["host"]),
+        "user": os.environ.get("LOCUSCOMPARE_DB_USER", _DEFAULT["user"]),
+        "password": os.environ.get("LOCUSCOMPARE_DB_PASSWORD", _DEFAULT["password"]),
+        "port": int(os.environ.get("LOCUSCOMPARE_DB_PORT", _DEFAULT["port"])),
+        "database": os.environ.get("LOCUSCOMPARE_DB_NAME", _DEFAULT["database"]),
+    }

locuscompare/core.py

@@ -0,0 +1,64 @@
+"""End-to-end orchestrator (port of R ``locuscompare``)."""
+import warnings
+
+import pandas as pd
+
+from .analysis import get_lead_snp
+from .db import get_position, retrieve_LD
+from .io import read_metal
+from .plot import make_combined_plot
+
+
+def locuscompare(
+    in_fn1,
+    in_fn2,
+    marker_col1="rsid",
+    pval_col1="pval",
+    title1="eQTL",
+    marker_col2="rsid",
+    pval_col2="pval",
+    title2="GWAS",
+    snp=None,
+    population="EUR",
+    combine=True,
+    genome="hg19",
+    ld=None,
+):
+    """Make a LocusCompare figure from two association summary-statistics inputs.
+
+    Parameters mirror the R package. Supply ``ld`` (a DataFrame with columns
+    ``SNP_A``, ``SNP_B``, ``R2`` where ``SNP_A`` is the lead ``snp``) to bypass the
+    reference database; ``snp`` is then required and ``population`` is ignored.
+    """
+    if ld is not None:
+        if snp is None:
+            raise ValueError(
+                "When supplying 'ld', you must also specify the lead 'snp' the LD is relative to."
+            )
+        if not isinstance(ld, pd.DataFrame) or not {"SNP_A", "SNP_B", "R2"}.issubset(ld.columns):
+            raise ValueError("'ld' must be a DataFrame with columns SNP_A, SNP_B, R2.")
+        if snp not in set(ld["SNP_A"]):
+            warnings.warn(
+                f"None of the supplied LD rows have SNP_A == '{snp}'; "
+                "all SNPs will be colored as low-LD.",
+                stacklevel=2,
+            )
+
+    d1 = read_metal(in_fn1, marker_col1, pval_col1)
+    d2 = read_metal(in_fn2, marker_col2, pval_col2)
+    merged = d1.merge(d2, on="rsid", suffixes=("1", "2"))
+
+    if genome not in ("hg19", "hg38"):
+        raise ValueError("genome must be 'hg19' or 'hg38'.")
+    merged = get_position(merged, genome)
+
+    chrs = list(pd.unique(merged["chr"]))
+    if len(chrs) != 1:
+        raise ValueError("There must be one and only one chromosome.")
+    chr = chrs[0]
+
+    snp = get_lead_snp(merged, snp)
+    if ld is None:
+        ld = retrieve_LD(chr, snp, population)
+
+    return make_combined_plot(merged, title1, title2, ld, chr, snp, combine)

locuscompare/data/__init__.py

@@ -0,0 +1,2 @@
+# Marks locuscompare.data as a package so bundled example files are importable
+# via importlib.resources. See locuscompare.datasets.example_path.