RNAvigate 1.1.0__py3-none-any.whl

rnavigate/__init__.py

@@ -0,0 +1,63 @@
+"""RNAvigate
+
+RNA visualization and graphical analysis toolset
+
+A Jupyter-compatible toolset for visually exploring RNA structure and chemical
+probing data.
+"""
+
+from rnavigate.rnavigate import Sample
+from rnavigate.plotting_functions import (
+    plot_options,
+    plot_alignment,
+    plot_arcs,
+    plot_arcs_compare,
+    plot_circle,
+    plot_disthist,
+    plot_heatmap,
+    plot_linreg,
+    plot_mol,
+    plot_ntdist,
+    plot_profile,
+    plot_qc,
+    plot_roc,
+    plot_shapemapper,
+    plot_skyline,
+    plot_ss,
+)
+from rnavigate import analysis
+from rnavigate import data
+from rnavigate import plots
+from rnavigate import styles
+from rnavigate import transcriptomics
+
+__version__ = "1.0.0"
+__author__ = "Patrick S. Irving"
+__email__ = "psirving@email.unc.edu"
+
+__all__ = [
+    "Sample",
+    # plotting functions
+    "plot_options",
+    "plot_alignment",
+    "plot_arcs",
+    "plot_arcs_compare",
+    "plot_circle",
+    "plot_disthist",
+    "plot_heatmap",
+    "plot_linreg",
+    "plot_mol",
+    "plot_ntdist",
+    "plot_profile",
+    "plot_qc",
+    "plot_roc",
+    "plot_shapemapper",
+    "plot_skyline",
+    "plot_ss",
+    # modules
+    "analysis",
+    "data",
+    "plots",
+    "styles",
+    "transcriptomics",
+]

rnavigate/analysis/__init__.py

@@ -0,0 +1,18 @@
+from rnavigate.analysis.logcompare import LogCompare
+from rnavigate.analysis.lowss import LowSS
+from rnavigate.analysis.deltashape import DeltaSHAPE, DeltaSHAPEProfile
+from rnavigate.analysis.auroc import WindowedAUROC
+from rnavigate.analysis.fragmapper import FragMaP, Fragmapper, FragmapperReplicates
+from rnavigate.analysis.check_sequence import SequenceChecker
+
+__all__ = [
+    "LogCompare",
+    "LowSS",
+    "DeltaSHAPE",
+    "DeltaSHAPEProfile",
+    "WindowedAUROC",
+    "FragMaP",
+    "Fragmapper",
+    "FragmapperReplicates",
+    "SequenceChecker",
+]

rnavigate/analysis/auroc.py

@@ -0,0 +1,198 @@
+"""Windowed AUROC assesses agreement between reactivities and base-pairing."""
+
+import numpy as np
+from sklearn.metrics import auc, roc_curve
+
+from rnavigate import plots
+
+
+# TODO: refactor as subclass of rnavigate.Sample
+class WindowedAUROC:
+    """Compute and display windowed AUROC analysis.
+
+    This analysis computes the ROC curve over a sliding window for the
+    performance of per-nucleotide data (usually SHAPE-MaP or DMS-MaP Normalized
+    reactivity) in predicting the base-pairing status of each nucleotide. The
+    area under this curve (AUROC) is displayed compared to the median across
+    the RNA. Below, an arc plot displays the secondary structure and
+    per-nucleotide profile.
+
+     AUROC values (should) range from 0.5 (no predictive power) to 1.0
+    (perfect predictive power). A value of 0.5 indicates that the reactivity
+    profile does not fit the structure prediction well. These regions are good
+    candidates for further investigation with ensemble deconvolution.
+
+    References
+    ----------
+    Lan, T.C.T., Allan, M.F., Malsick, L.E. et al. Secondary structural
+        ensembles of the SARS-CoV-2 RNA genome in infected cells. Nat Commun
+        13, 1128 (2022). https://doi.org/10.1038/s41467-022-28603-2
+
+    Methods
+    -------
+    __init__: Computes the AUROC array and AUROC median.
+    plot_auroc: Displays the AUROC analysis over the given region.
+        Returns Plot object
+
+    Attributes
+    ----------
+    sample : rnavigate.Sample
+        sample to retrieve profile and secondary structure
+    structure : str
+        Data keyword of sample pointing to secondary structure
+        e.g. sample.data[structure]
+    profile : str
+        Data keyword of sample pointing to profile
+        e.g. sample.data[profile]
+    sequence : the sequence string of sample.data[structure]
+    window: the size of the windows
+    nt_length: the length of sequence string
+    auroc: the auroc numpy array, length = nt_length, padded with np.nan
+    median_auroc: the median of the auroc array
+    """
+
+    def __init__(
+        self,
+        sample,
+        window=81,
+        profile="default_profile",
+        structure="default_structure",
+    ):
+        """Compute the AUROC for all windows. AUROC is a measure of how well a
+        reactivity profile predicts paired vs. unpaired nucleotide status.
+
+        Parameters
+        ----------
+        sample : rnav.Sample
+            Your rnavigate sample
+        window : int, optional
+            number of nucleotides to include in window
+            Defaults to 81.
+        profile (str, optional): data keyword of provided sample pointing
+            to a profile.
+            Defaults to "default_profile"
+        structure (str, optional): data keyword of provided sample pointing
+            to a secondary structure.
+            Defaults to "default_structure"
+        """
+        # ensure sample contains profile and structure data
+        for data in [profile, structure]:
+            assert data in sample.data.keys(), f"Sample missing {data} data"
+
+        # store basic information
+        self.sample = sample
+        self.structure = sample.get_data(structure)
+        self.profile = sample.get_data(profile)
+        self.sequence = self.structure.sequence
+        self.window = window
+        self.nt_length = self.structure.length
+
+        # get Norm_profile array and structure array
+        profile = self.profile.data["Norm_profile"].values
+        pair_nts = self.structure.pair_nts
+
+        # for each possible window: compute auroc and populate array
+        self.auroc = np.full(len(profile), np.nan)
+        pad = window // 2
+        for i in range(pad, len(profile) - pad):
+            # get profile and structure values within window
+            win_profile = profile[i - pad : i + pad + 1]
+            win_ct = pair_nts[i - pad : i + pad + 1]
+            # ignore positions where profile is nan
+            valid = ~np.isnan(win_profile)
+            # y: classification (paired or unpaired)
+            y = win_ct[valid] == 0
+            scores = win_profile[valid]
+            # skip this window if there are less than 10 paired or unpaired nts
+            if (sum(y) < 10) or (sum(~y) < 10):
+                continue
+            # add window auroc to array
+            tpr, fpr, _ = roc_curve(y, scores)
+            self.auroc[i] = auc(tpr, fpr)
+
+        self.auroc_median = np.nanmedian(self.auroc)
+
+    def plot_auroc(self, region=None):
+        """Plot the result of the windowed AUROC analysis, with arc plot of
+        structure and reactivity profile.
+
+        Args:
+            region (list of int: length 2, optional): Start and end nucleotide
+                positions to plot. Defaults to [1, RNA length].
+        """
+        if region is None:
+            start = 1
+            stop = self.nt_length
+            region = [start, stop]
+            region_length = self.nt_length
+        else:
+            start, stop = region
+            region_length = stop - start + 1
+
+        plot = plots.AP(1, region_length, cols=1, rows=1, region=region)
+        ax = plot.axes[0, 0]
+
+        # fill between auroc values and median, using secondary ax
+        x_values = np.arange(start, stop + 1)
+        auc_ax = ax.twinx()
+        auc_ax.set_ylim(0.5, 1.6)
+        auc_ax.set_yticks([0.5, self.auroc_median, 1.0])
+        auc_ax.fill_between(
+            x_values,
+            self.auroc[start - 1 : stop],
+            self.auroc_median,
+            fc="0.3",
+            lw=0,
+        )
+        plots.adjust_spines(auc_ax, ["left"])
+        plots.clip_spines(auc_ax, ["left"])
+
+        # add structure and reactivity profile track
+        plot.plot_data(
+            sequence=self.structure,
+            structure=self.structure,
+            structure2=None,
+            interactions=None,
+            interactions2=None,
+            profile=self.profile,
+            label="label",
+            seqbar=False,
+            title=False,
+            annotations=[],
+            plot_error=False,
+        )
+
+        # Place Track Labels
+        ax.set_title(
+            f"{self.sample.sample}\n{start} - {stop}",
+            loc="left",
+            fontdict={"fontsize": 48},
+        )
+        ax.text(
+            1.002,
+            6 / 8,
+            "Secondary\nStructure",
+            transform=ax.transAxes,
+            fontsize=36,
+            va="center",
+        )
+        ax.text(
+            1.002,
+            2 / 8,
+            f"{self.window}-nt window\nAUROC",
+            transform=ax.transAxes,
+            va="center",
+            fontsize=36,
+        )
+
+        # limits, ticks, spines, and grid
+        ax.set_ylim([-305, 315])
+        ax.set_xticks(ticks=[x for x in range(500, stop, 500) if x > start])
+        ax.set_xticks(ticks=[x for x in range(100, stop, 100) if x > start], minor=True)
+        ax.tick_params(axis="x", which="major", labelsize=36)
+        plots.adjust_spines(ax, ["bottom"])
+        ax.grid(axis="x")
+
+        # set figure size so that 100 ax units == 1 inch
+        plot.set_figure_size(height_ax_rel=1 / 100, width_ax_rel=1 / 100)
+        return plot

rnavigate/analysis/check_sequence.py

@@ -0,0 +1,171 @@
+"""SequenceChecker analysis used to inspect sequence differences.
+
+Given a list of samples, we can inspect which data keywords belong to the
+samples, which sequences match up perfectly, and inspect the differences
+between sequences.
+"""
+
+import numpy as np
+import pandas as pd
+
+from rnavigate import data
+
+
+class SequenceChecker:
+    """Check the sequences stored in a list of samples.
+
+    Attributes
+    ----------
+    samples : list
+        samples in which to check sequences
+    sequences : list
+        all unique sequence strings stored in the list of samples. These are converted
+        to an all uppercase RNA alphabet.
+    keywords : list
+        all unique data keywords stored in the list of samples.
+    which_sequences : Pandas.DataFrame
+        each row is a sample, keyword, and index of self.sequences
+    """
+
+    def __init__(self, samples):
+        """Creates an instance of SequenceChecker given a list of samples
+
+        Parameters
+        ----------
+        samples : list of rnav.Sample
+            samples for which to compare data keywords and sequences.
+        """
+        self.samples = samples
+        self.keywords = self.get_keywords()
+        self.sequences = self.get_sequences()
+        self.which_sequences = self.get_which_sequences()
+
+    def reset(self):
+        """Reset keywords and sequences from sample list in case of changes."""
+        self.keywords = self.get_keywords()
+        self.sequences = self.get_sequences()
+        self.which_sequences = self.get_which_sequences()
+
+    def get_keywords(self):
+        """A list of all unique data keywords across samples."""
+        return list(set([dkw for s in self.samples for dkw in s.data]))
+
+    def get_sequences(self):
+        """A list of all unique sequences (uppercase RNA) across samples."""
+        sequences = []
+        for sample in self.samples:
+            for dkw in self.keywords:
+                if dkw not in sample.data:
+                    continue
+                seq = sample.get_data(dkw).sequence
+                seq = seq.upper().replace("T", "U")
+                if seq not in sequences:
+                    sequences.append(seq)
+        return sequences
+
+    def get_which_sequences(self):
+        """A DataFrame of sequence IDs (integers) for each data keyword."""
+        df = {key: [] for key in ["Sample"] + self.keywords}
+        for sample in self.samples:
+            df["Sample"].append(sample.sample)
+            for dkw in self.keywords:
+                if dkw not in sample.data:
+                    df[dkw].append(np.nan)
+                else:
+                    seq = sample.get_data(dkw).sequence
+                    seq = seq.upper().replace("T", "U")
+                    df[dkw].append(self.sequences.index(seq))
+        return pd.DataFrame(df)
+
+    def print_which_sequences(self):
+        """Print sequence ID (integer) for each data keyword and sample."""
+        print("Sequence IDs")
+        for _, row in self.which_sequences.iterrows():
+            for column in self.which_sequences.columns:
+                if column == "Sample":
+                    print(f"    {row[column]}")
+                else:
+                    if np.isnan(row[column]):
+                        continue
+                    print(f"        {column:<10} {int(row[column])}")
+        print()
+
+    def print_alignments(self, print_format="long", which="all"):
+        """Print alignments in the given format for sequence IDs provided.
+
+        Parameters
+        ----------
+        print_format : string, defaults to "long"
+            What format to print the alignments in:
+            "cigar" prints the cigar string
+            "short" prints the numbers of mismatches and indels
+            "long" prints the location and nucleotide identity of all
+                mismatches, insertions and deletions.
+        which : tuple of two of integers, defaults to "all" (every pairwise comparison)
+            two sequence IDs to compare.
+        """
+        kwargs = {"print_format": print_format}
+        if which == "all":
+            num = range(len(self.sequences))
+            for s1 in num:
+                for s2 in num:
+                    if s1 < s2:
+                        self.print_alignments(which=(s1, s2), **kwargs)
+            return
+        i, j = int(which[0]), int(which[1])
+        a = self.sequences[i]
+        b = self.sequences[j]
+        alignment = data.SequenceAlignment(sequence1=a, sequence2=b, full=True)
+        print(f"Sequence {i} -> {j} ({len(a)} nts -> {len(b)} nts)")
+        alignment.print(print_format=print_format)
+
+    def print_mulitple_sequence_alignment(self, base_sequence):
+        """Print the multiple sequence alignment with nice formatting.
+
+        Parameters
+        ----------
+        base_sequence : string
+            a sequence string that represents the longest common sequence.
+            Usually, this is the return value from:
+                rnav.data.set_multiple_sequence_alignment()
+        """
+        print("Multiple sequence alignment")
+        alignments = [
+            data.SequenceAlignment(base_sequence, seq).alignment2
+            for seq in self.sequences
+        ]
+        pos = "".join(f"{n:<20}" for n in range(1, len(alignments[0]), 20))
+        misses = "".join("X "[len(set(nts)) == 1] for nts in zip(*alignments))
+        print("    ID    length   alignment")
+        for i, (alignment, seq) in enumerate(zip(alignments, self.sequences)):
+            print(f"    {i:<5} {len(seq):<8} {alignment}")
+        print(f"    {'mismatches':<14} {misses}")
+        print(f"    {'positions':<14} {pos}")
+        print()
+
+    def write_fasta(self, filename, which="all"):
+        """Write all unique sequences to a fasta file.
+
+        This is very useful for using external multiple sequence aligners such
+        as ClustalOmega.
+            1) go to https://www.ebi.ac.uk/Tools/msa/clustalo/
+            2) upload new fasta file
+            3) under STEP 2 output format, select Pearson/FASTA
+            4) click 'Submit'
+            5) wait for your alignment to finish
+            6) download the alignment fasta file
+            7) use rnav.data.set_multiple_sequence_alignment()
+
+        Parameters
+        ----------
+        filename : string
+            path to a new file to which fasta entries are written
+        which : list of integers, defaults to "all" (every sequence)
+            Sequence IDs to write to file.
+        """
+        if which == "all":
+            which = range(len(self.sequences))
+        with open(filename, "w") as fasta:
+            for i in which:
+                fasta.write(f">Sequence_{i}\n")
+                fasta.write(f"{self.sequences[i]}\n")