plotting

CCBigWigCollection

Bases: Track

Source code in capcruncher/api/plotting.py

class CCBigWigCollection(Track):
    DEFAULT_PROPERTIES = {
        "style": "line",
        "fmt": "-",
        "line_width": 2.0,
        "size": 10,
        "color": "#a6cee3",
        "threshold_color": "#ff9c9c",
        "threshold": "inf",
        "cmap": "bwr",
        "orientation": None,
        "data_range_style": "y-axis",
        "min_value": "auto",
        "max_value": "auto",
    }

    def __init__(self, file: list, exclusions: str = None, **kwargs):
        self.file_names = file
        self.exclusions = exclusions
        self.bws = [cb.BigWig(str(fn)) for fn in file]
        self.properties = {"files": self.file_names}
        self.properties.update(CCBigWigCollection.DEFAULT_PROPERTIES.copy())
        self.properties.update(kwargs)
        self.properties["name"] = f"BigWigCollection.{self.properties.get('title')}"
        super(CCBigWigCollection, self).__init__(**self.properties)

        self.coverages = []

        # load features from global feature stack
        features_stack = get_feature_stack()
        for features in features_stack:
            self.properties.update(features.properties)

        # load coverages from global coverages stack
        coverage_stack = get_coverage_stack()
        for coverage in coverage_stack:
            self.coverages.append(coverage)

    def _correct_genomic_range(self, gr: cb.GenomeRange, bw: cb.BigWig):
        """
        Corrects the genomic range to use the same chromosome style as the BigWig file.
        """

        import re

        bw_chromosomes = list(bw.bw.chromsizes())

        if re.match(r'^chr.*', bw_chromosomes[0]) and not re.match(r'^chr.*', gr.chrom):
            gr.chrom = f"chr{gr.chrom}"
        elif not re.match(r'^chr.*', bw_chromosomes[0]) and re.match(r'^chr.*', gr.chrom):
            gr.chrom = gr.chrom[3:]

        return gr


    def fetch_data(self, gr, **kwargs):
        datasets = []
        for bw in self.bws:
            gr = self._correct_genomic_range(gr, bw)
            bw_data = bw.fetch_intervals(gr.chrom, gr.start, gr.end)
            bw_data = bw_data.set_index(["chrom", "start", "end"])
            bw_data = bw_data.rename(columns={"value": os.path.basename(bw.properties["file"])})
            datasets.append(bw_data)

        df = datasets[0].join(datasets[1:])
        df_summary = df.assign(mean=df.mean(axis=1), sem=df.sem(axis=1)).reset_index()

        intervals_to_bp = []
        for interval in df_summary.itertuples():
            interval_len = interval.end - interval.start

            interval_positions = np.arange(interval_len) + interval.start
            scores_mean = np.repeat(interval.mean, interval_len)
            scores_sem = np.repeat(interval.sem, interval_len)

            intervals_to_bp.append(
                np.vstack([interval_positions, scores_mean, scores_sem]).T
            )

        df_intervals = pd.DataFrame(
            np.concatenate(intervals_to_bp), columns=["bp", "mean", "sem"]
        )

        if self.exclusions:
            df_intervals = pd.concat(
                [df_intervals, self.fetch_exluded_regions(gr)]
            ).sort_values("bp")

        if self.properties.get("smooth_window"):
            from scipy.signal import savgol_filter

            df_intervals["mean_smoothed"] = savgol_filter(
                df_intervals["mean"],
                window_length=self.properties.get("smooth_window", 1001),
                polyorder=self.properties.get("polyorder", 1),
            )

        return df_intervals

    def fetch_exluded_regions(self, gr):
        excluded_tabix = BedTool(self.exclusions).tabix(force=True)
        df_excluded = excluded_tabix.tabix_intervals(
            f"{gr.chrom}:{gr.start}-{gr.end}"
        ).to_dataframe()

        intervals_to_bp = []
        for interval in df_excluded.itertuples():
            interval_len = interval.end - interval.start

            interval_positions = np.arange(interval_len) + interval.start
            scores_nan = np.repeat(np.nan, interval_len)
            intervals_to_bp.append(interval_positions)

        df_intervals = pd.Series(np.concatenate(intervals_to_bp)).to_frame("bp")
        df_intervals["mean"] = np.nan
        df_intervals["sem"] = np.nan

        return df_intervals

    def plot(self, ax, gr, **kwargs):
        data = self.fetch_data(gr, **kwargs)

        line_width = self.properties.get("line_width", 1)
        color = self.properties.get("color", "blue")
        alpha = self.properties.get("alpha", 0.2)
        downsample = self.properties.get("downsample", 0)

        if downsample:
            rows = np.arange(0, data.shape[0], downsample)
            data = data.iloc[rows]

        if self.properties.get("smooth_window"):
            scores = data["mean_smoothed"]
        else:
            scores = data["mean"]

        ax.fill_between(
            data["bp"],
            scores - data["sem"],
            scores + data["sem"],
            alpha=alpha,
            color=color,
            zorder=0,
        )

        ax.plot(
            data["bp"],
            scores,
            color=color,
            zorder=1,
        )

        min_val = self.properties.get("min_value")
        max_val = self.properties.get("max_value")

        ymin = round(scores.min()) if min_val == "auto" else min_val
        ymax = round(scores.max() + data["sem"].max()) if max_val == "auto" else max_val

        ax.set_xlim(gr.start, gr.end)
        ax.set_ylim(ymin, ymax)

        self.plot_data_range(ax, ymin, ymax, self.properties["data_range_style"], gr)
        self.plot_label()

    def plot_data_range(self, ax, ymin, ymax, data_range_style, gr: cb.GenomeRange):
        if data_range_style == "text":
            self.plot_text_range(ax, ymin, ymax, gr)
        else:  # 'y-axis' style
            try:
                y_ax = self.y_ax
                self.plot_yaxis_range(ax, y_ax)
            except AttributeError:
                self.plot_data_range(ax, ymin, ymax, "text", gr)

    def plot_yaxis_range(self, plot_axis, y_ax):
        # """
        # Plot the scale of the y axis with respect to the plot_axis
        # plot something that looks like this:
        # ymax ┐
        #      │
        #      │
        # ymin ┘
        # Parameters
        # ----------
        # plot_axis : matplotlib.axes.Axes
        #     Main plot axis.
        # y_ax : matplotlib.axes.Axes
        #     Axis to use to plot the scale
        # """

        if (
            "show_data_range" in self.properties
            and self.properties["show_data_range"] == "no"
        ):
            return

        def value_to_str(value):
            if value % 1 == 0:
                return str(int(value))
            else:
                return f"{value:.4f}" if value < 0.01 else f"{value:.2f}"

        ymin, ymax = plot_axis.get_ylim()

        ymax_str = value_to_str(ymax)
        ymin_str = value_to_str(ymin)
        x_pos = [0, 0.5, 0.5, 0]
        y_pos = [0.01, 0.01, 0.99, 0.99]
        y_ax.plot(x_pos, y_pos, color="black", linewidth=1, transform=y_ax.transAxes)
        y_ax.text(
            -0.2,
            -0.01,
            ymin_str,
            verticalalignment="bottom",
            horizontalalignment="right",
            transform=y_ax.transAxes,
        )
        y_ax.text(
            -0.2,
            1,
            ymax_str,
            verticalalignment="top",
            horizontalalignment="right",
            transform=y_ax.transAxes,
        )
        y_ax.patch.set_visible(False)

    def plot_text_range(self, ax, ymin, ymax, gr: cb.GenomeRange):
        ydelta = ymax - ymin

        # set min max
        def format_lim(lim):
            return int(lim) if float(lim) % 1 == 0 else f"{lim:.2f}"

        ymax_print = format_lim(ymax)
        ymin_print = format_lim(ymin)
        small_x = 0.01 * gr.length
        # by default show the data range
        ax.text(
            gr.start - small_x,
            ymax - ydelta * 0.2,
            f"[ {ymin_print} ~ {ymax_print} ]",
            horizontalalignment="left",
            verticalalignment="top",
        )

CCFigure

Generates a figure from a list of tracks

Parameters:

Name	Type	Description	Default
tracks	List[CCTrack]	List of tracks to plot. Defaults to None.	None
auto_spacing	bool	Automatically add a spacer track between each track. Defaults to False.	False
**kwargs		Additional arguments to pass to the figure	{}

Source code in capcruncher/api/plotting.py

class CCFigure:
    """
    Generates a figure from a list of tracks

    Args:
        tracks (List[CCTrack], optional): List of tracks to plot. Defaults to None.
        auto_spacing (bool, optional): Automatically add a spacer track between each track. Defaults to False.
        **kwargs: Additional arguments to pass to the figure
    """

    def __init__(
        self, tracks: List[CCTrack] = None, auto_spacing: bool = False, **kwargs
    ) -> None:
        self.frame = cb.Frame()
        self.auto_spacing = auto_spacing
        self.properties = dict()
        self.properties.update(kwargs)

        if tracks:
            self.tracks = set(tracks)
            self.add_tracks(tracks)
        else:
            self.tracks = set()

    def add_track(self, track: CCTrack) -> None:
        """
        Add a track to the figure

        Args:
            track (CCTrack): Track to add
        """
        self.tracks.add(track)
        self.frame.add_track(track.get_track())

    def add_tracks(self, tracks: List[CCTrack]) -> None:
        """
        Add a list of tracks to the figure

        Args:
            tracks (List[CCTrack]): List of tracks to add
        """
        for track in tracks:
            if self.auto_spacing:
                spacer = CCTrack(None, file_type="spacer")
                self.add_track(spacer.get_track())

            self.add_track(track)

    def plot(
        self,
        gr: Union[str, GenomeRange],
        gr2: Union[str, GenomeRange] = None,
        show: bool = True,
        **kwargs,
    ) -> None:
        """
        Plot the figure

        Args:
            gr (Union[str, GenomeRange]): GenomeRange to plot
            gr2 (Union[str, GenomeRange], optional): Second GenomeRange to plot. Defaults to None.
            show (bool, optional): Show the figure. Defaults to True.
            **kwargs: Additional arguments to pass to the plot
        """

        if gr2:
            fig = self.frame.plot(gr, gr2, **kwargs)
        else:
            fig = self.frame.plot(gr, **kwargs)
        if show:
            fig.show()

        return fig

    def save(
        self,
        gr: Union[str, GenomeRange],
        gr2: Union[str, GenomeRange] = None,
        output: str = None,
        **kwargs,
    ) -> None:
        """
        Plots the figure and saves it to a file

        Args:
            gr (Union[str, GenomeRange]): GenomeRange to plot
            gr2 (Union[str, GenomeRange], optional): Second GenomeRange to plot. Defaults to None.
            output (str, optional): Path to save the figure to. Defaults to None.
            **kwargs: Additional arguments to pass to the plot
        """

        fig = self.plot(gr, gr2, show=False, **kwargs)
        if output:
            fig.savefig(output, dpi=300)
        else:
            fig.savefig(f"{gr.chrom}_{gr.start}_{gr.end}.png", dpi=300)

    @classmethod
    def from_toml(cls, toml_file: os.PathLike, **kwargs) -> "CCFigure":
        """
        Instantiate a CCFigure from a toml file

        Args:
            toml_file (os.PathLike): Path to toml file
            **kwargs: Additional arguments to pass to the figure
        """
        import toml

        with open(toml_file) as f:
            config = toml.load(f)

        tracks = []
        for track_name, attr in config.items():
            file = attr.pop("file") if attr.get("file") else None
            track_name = attr.pop("title") if attr.get("title") else track_name
            tracks.append(CCTrack(file, title=track_name, **attr))
        return cls(tracks, **kwargs)

    @classmethod
    def from_frame(cls, frame: cb.Frame, **kwargs) -> "CCFigure":
        """
        Instantiate a CCFigure from a coolbox Frame

        Args:
            frame (cb.Frame): coolbox Frame to instantiate from
            **kwargs: Additional arguments to pass to the figure
        """
        tracks = []
        for track in frame.tracks:
            tracks.append(CCTrack(track.properties["file"], **track.properties))

        return cls(tracks, **kwargs)

    def to_toml(self, output: str = None) -> Union[None, Dict[str, Any]]:
        """
        Save the CCFigure to a toml file

        Args:
            output (str, optional): Path to save the toml file to. Defaults to None.

        Returns:
            Union[None, Dict[str, Any]]: If output is not specified, returns a dict of the toml file

        """

        import toml
        from collections import OrderedDict

        def _get_n_tracks_of_type(config: Dict[str, Dict], track_type: str):
            return sum(1 for t in config.keys() if track_type in t)

        config = OrderedDict()
        for track in self.tracks:
            # Perform conversions for file-less tracks
            if track.properties.get("type") in ["spacer", "scale", "xaxis"]:
                track_type = track.properties.get("type")
                n = _get_n_tracks_of_type(config, track_type)
                config[f"{track_type} {n}"] = track.properties
                config[f"{track_type} {n}"]["file"] = None
            elif track.properties.get("type") == "genes":
                track_type = track.properties.get("type")
                n = _get_n_tracks_of_type(config, track_type)
                config[f"{track_type} {n}"] = track.properties
                config[f"{track_type} {n}"]["file"] = track.path
            else:
                config[track.properties["title"]] = track.properties
                config[track.properties["title"]]["file"] = track.path

        outfile = output if output else "config.toml"

        with open(outfile, "w") as f:
            config_str = toml.dumps(config)
            f.write(config_str)

        if not output:
            return config

add_track(track)

Add a track to the figure

Parameters:

Name	Type	Description	Default
track	CCTrack	Track to add	required

Source code in capcruncher/api/plotting.py

def add_track(self, track: CCTrack) -> None:
    """
    Add a track to the figure

    Args:
        track (CCTrack): Track to add
    """
    self.tracks.add(track)
    self.frame.add_track(track.get_track())

add_tracks(tracks)

Add a list of tracks to the figure

Parameters:

Name	Type	Description	Default
tracks	List[CCTrack]	List of tracks to add	required

Source code in capcruncher/api/plotting.py

def add_tracks(self, tracks: List[CCTrack]) -> None:
    """
    Add a list of tracks to the figure

    Args:
        tracks (List[CCTrack]): List of tracks to add
    """
    for track in tracks:
        if self.auto_spacing:
            spacer = CCTrack(None, file_type="spacer")
            self.add_track(spacer.get_track())

        self.add_track(track)

from_frame(frame, **kwargs) classmethod

Instantiate a CCFigure from a coolbox Frame

Parameters:

Name	Type	Description	Default
frame	Frame	coolbox Frame to instantiate from	required
**kwargs		Additional arguments to pass to the figure	{}

Source code in capcruncher/api/plotting.py

@classmethod
def from_frame(cls, frame: cb.Frame, **kwargs) -> "CCFigure":
    """
    Instantiate a CCFigure from a coolbox Frame

    Args:
        frame (cb.Frame): coolbox Frame to instantiate from
        **kwargs: Additional arguments to pass to the figure
    """
    tracks = []
    for track in frame.tracks:
        tracks.append(CCTrack(track.properties["file"], **track.properties))

    return cls(tracks, **kwargs)

from_toml(toml_file, **kwargs) classmethod

Instantiate a CCFigure from a toml file

Parameters:

Name	Type	Description	Default
toml_file	PathLike	Path to toml file	required
**kwargs		Additional arguments to pass to the figure	{}

Source code in capcruncher/api/plotting.py

@classmethod
def from_toml(cls, toml_file: os.PathLike, **kwargs) -> "CCFigure":
    """
    Instantiate a CCFigure from a toml file

    Args:
        toml_file (os.PathLike): Path to toml file
        **kwargs: Additional arguments to pass to the figure
    """
    import toml

    with open(toml_file) as f:
        config = toml.load(f)

    tracks = []
    for track_name, attr in config.items():
        file = attr.pop("file") if attr.get("file") else None
        track_name = attr.pop("title") if attr.get("title") else track_name
        tracks.append(CCTrack(file, title=track_name, **attr))
    return cls(tracks, **kwargs)

plot(gr, gr2=None, show=True, **kwargs)

Plot the figure

Parameters:

Name	Type	Description	Default
gr	Union[str, GenomeRange]	GenomeRange to plot	required
gr2	Union[str, GenomeRange]	Second GenomeRange to plot. Defaults to None.	None
show	bool	Show the figure. Defaults to True.	True
**kwargs		Additional arguments to pass to the plot	{}

Source code in capcruncher/api/plotting.py

def plot(
    self,
    gr: Union[str, GenomeRange],
    gr2: Union[str, GenomeRange] = None,
    show: bool = True,
    **kwargs,
) -> None:
    """
    Plot the figure

    Args:
        gr (Union[str, GenomeRange]): GenomeRange to plot
        gr2 (Union[str, GenomeRange], optional): Second GenomeRange to plot. Defaults to None.
        show (bool, optional): Show the figure. Defaults to True.
        **kwargs: Additional arguments to pass to the plot
    """

    if gr2:
        fig = self.frame.plot(gr, gr2, **kwargs)
    else:
        fig = self.frame.plot(gr, **kwargs)
    if show:
        fig.show()

    return fig

save(gr, gr2=None, output=None, **kwargs)

Plots the figure and saves it to a file

Parameters:

Name	Type	Description	Default
gr	Union[str, GenomeRange]	GenomeRange to plot	required
gr2	Union[str, GenomeRange]	Second GenomeRange to plot. Defaults to None.	None
output	str	Path to save the figure to. Defaults to None.	None
**kwargs		Additional arguments to pass to the plot	{}

Source code in capcruncher/api/plotting.py

def save(
    self,
    gr: Union[str, GenomeRange],
    gr2: Union[str, GenomeRange] = None,
    output: str = None,
    **kwargs,
) -> None:
    """
    Plots the figure and saves it to a file

    Args:
        gr (Union[str, GenomeRange]): GenomeRange to plot
        gr2 (Union[str, GenomeRange], optional): Second GenomeRange to plot. Defaults to None.
        output (str, optional): Path to save the figure to. Defaults to None.
        **kwargs: Additional arguments to pass to the plot
    """

    fig = self.plot(gr, gr2, show=False, **kwargs)
    if output:
        fig.savefig(output, dpi=300)
    else:
        fig.savefig(f"{gr.chrom}_{gr.start}_{gr.end}.png", dpi=300)

to_toml(output=None)

Save the CCFigure to a toml file

Parameters:

Name	Type	Description	Default
output	str	Path to save the toml file to. Defaults to None.	None

Returns:

Type	Description
Union[None, Dict[str, Any]]	Union[None, Dict[str, Any]]: If output is not specified, returns a dict of the toml file

Source code in capcruncher/api/plotting.py

def to_toml(self, output: str = None) -> Union[None, Dict[str, Any]]:
    """
    Save the CCFigure to a toml file

    Args:
        output (str, optional): Path to save the toml file to. Defaults to None.

    Returns:
        Union[None, Dict[str, Any]]: If output is not specified, returns a dict of the toml file

    """

    import toml
    from collections import OrderedDict

    def _get_n_tracks_of_type(config: Dict[str, Dict], track_type: str):
        return sum(1 for t in config.keys() if track_type in t)

    config = OrderedDict()
    for track in self.tracks:
        # Perform conversions for file-less tracks
        if track.properties.get("type") in ["spacer", "scale", "xaxis"]:
            track_type = track.properties.get("type")
            n = _get_n_tracks_of_type(config, track_type)
            config[f"{track_type} {n}"] = track.properties
            config[f"{track_type} {n}"]["file"] = None
        elif track.properties.get("type") == "genes":
            track_type = track.properties.get("type")
            n = _get_n_tracks_of_type(config, track_type)
            config[f"{track_type} {n}"] = track.properties
            config[f"{track_type} {n}"]["file"] = track.path
        else:
            config[track.properties["title"]] = track.properties
            config[track.properties["title"]]["file"] = track.path

    outfile = output if output else "config.toml"

    with open(outfile, "w") as f:
        config_str = toml.dumps(config)
        f.write(config_str)

    if not output:
        return config

CCTrack

Provides a wrapper around tracks to provide a consistent interface

Parameters:

Name	Type	Description	Default
file	PathLike	Path to file to plot	required
file_type	Literal['heatmap', 'bigwig', 'bigwig_summary', 'scale', 'bed', 'xaxis', 'genes', 'spacer']	Type of file to plot. Defaults to None.	None
**kwargs		Additional arguments to pass to the track	{}

Source code in capcruncher/api/plotting.py

class CCTrack:
    """
    Provides a wrapper around tracks to provide a consistent interface

    Args:
        file (os.PathLike): Path to file to plot
        file_type (Literal["heatmap", "bigwig", "bigwig_summary", "scale", "bed", "xaxis", "genes", "spacer"], optional): Type of file to plot. Defaults to None.
        **kwargs: Additional arguments to pass to the track
    """

    def __init__(
        self,
        file,
        file_type: Literal[
            "heatmap",
            "heatmap_summary",
            "bigwig",
            "bigwig_summary",
            "scale",
            "bed",
            "xaxis",
            "genes",
            "spacer",
        ] = None,
        **kwargs,
    ):
        self.file = file
        self.properties = dict()
        self.properties.update(kwargs)

        if file_type:
            self.properties["type"] = file_type
        elif self.properties.get("type"):
            pass
        else:
            raise ValueError(
                "Please specify file_type as one of: heatmap, bigwig, bigwig_summary, scale, bed, xaxis, genes, spacer"
            )

    def get_track(self):
        match self.properties.get("type"):  # noqa
            case "heatmap":
                assert (
                    "binsize" in self.properties
                ), "Binsize must be specified for heatmap track (e.g. binsize=5000)"
                return CCMatrix(self.file, **self.properties)
            case "heatmap_summary":
                assert (
                    "binsize" in self.properties
                ), "Binsize must be specified for heatmap track (e.g. binsize=5000)"

                matricies = []
                for matrix in self.file:
                    matricies.append(CCMatrix(matrix, **self.properties))

                return CCAverageMatrix(matricies, **self.properties)
            case "bigwig":
                if self.properties.get("overlay"):
                    return cb.BigWigCoverage(self.file, **self.properties)
                else:
                    return CCBigWig(self.file, **self.properties)
            case "bigwig_summary":
                return CCBigWigCollection(self.file, **self.properties)
            case "scale":
                return ScaleBar(**self.properties)
            case "bed":
                return CCSimpleBed(self.file, **self.properties)
            case "xaxis":
                return CCXAxisGenomic(**self.properties)
            case "genes":
                if self.properties.get("title"):
                    del self.properties["title"]
                return cb.BED(self.file, **self.properties)
            case "spacer":
                return cb.Spacer(**self.properties)
            case _:
                if getattr(cb, self.properties.get("type")):
                    return getattr(cb, self.properties.get("type"))(
                        self.file, **self.properties
                    )

                else:
                    raise ValueError(
                        f"Unknown track type {self.properties.get('type')}, select from: heatmap, bigwig, bigwig_summary, scale, bed, xaxis, genes, spacer"
                    )

    @property
    def path(self) -> str:
        if isinstance(self.file, (list, tuple, np.ndarray)):
            return [str(pathlib.Path(f).resolve()) for f in self.file]
        else:
            return str(pathlib.Path(self.file).resolve())

    def __repr__(self) -> str:
        return f"CCTrack({self.properties.get('title')}, {self.properties.get('type')})"