plotting

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')})"