metaloci.plot package

Collection of functions to plot METALoci output.

Submodules

metaloci.plot.plot module

Functions to generate plots from METALoci objects.

metaloci.plot.plot.create_composite_figure(mlobject: MetalociObject, signal_type: str, del_args: Series = False, neighourhood_circle: bool = False, args: Series = False, mark_regions: DataFrame = None, signipval: float = 0.05, silent: bool = False)

Generates a composite figure consisting of multiple plots related to Hi-C data analysis and saves the resulting images in various formats. The function handles different configurations based on the provided arguments. :param mlobject: The MetalociObject containing Hi-C data and associated metadata. :type mlobject: mlo.MetalociObject :param signal_type: The type of signal to be plotted (e.g., “wt”, “intact”). :type signal_type: str :param del_args: A pandas Series containing deletion-related arguments. Defaults to False. :type del_args: pd.Series, optional :param neighourhood_circle: Whether to include neighborhood circles in the plots. Defaults to False. :type neighourhood_circle: bool, optional :param args: A pandas Series containing additional arguments. Defaults to False. :type args: pd.Series, optional :param mark_regions: A DataFrame specifying regions to be marked on the plots. Defaults to None. :type mark_regions: pd.DataFrame, optional :param signipval: The significance p-value threshold for certain plots. Defaults to 0.05. :type signipval: float, optional :param silent: If True, suppresses console output. Defaults to False. :type silent: bool, optional

Returns:: None

Side Effects:

Saves multiple plot images (e.g., Hi-C plot, Kamada-Kawai plot, Gaudi Signal plot, etc.) in PNG and PDF formats.
Creates a composite image combining all individual plots.
Deletes intermediate plot files after the composite image is created.

Notes

The function dynamically adjusts plot filenames and configurations based on the provided arguments.
If del_args is provided, additional processing is performed to handle deletion-specific configurations.
The composite image is saved as a PNG and optionally as a PDF, with intermediate files being removed afterward.

metaloci.plot.plot.create_number_image(output_path: <module 'posixpath' (frozen)>, number: int = None, font_size: float = 192, image_size: tuple = (512, 512), font_path: <module 'posixpath' (frozen)> = None)

Creates an image with a specified number rendered at the center and saves it as a PNG file. :param number: The number to render on the image. :type number: int or str :param output_path: The file path where the generated image will be saved. :type output_path: str :param font_size: The size of the font to use for rendering the number. :type font_size: int :param image_size: The size of the image in pixels as a tuple (width, height). :type image_size: tuple :param font_path: The file path to a TTF font file. If not provided, the function :type font_path: str, optional :param will attempt to use the “DejaVuSans-Bold.ttf” font. If this font is not available: :param : :param a RuntimeError will be raised.:

Notes

The image is created with a transparent background.
The number is rendered in black color.
The output directory will be created if it does not exist.

metaloci.plot.plot.get_gaudi_signal_plot(mlobject: MetalociObject, lmi_geometry: DataFrame, cmap_user: str = 'PuOr_r', mark_regions: DataFrame = None, neighbourhood: bool = False)

Get a Gaudí signal plot.

Parameters:

mlobject (mlo.MetalociObject) – METALoci object.
lmi_geometry (pd.DataFrame) – Merging from MetalociObject.lmi_info for a specific signal and MetalociObject.geometry for a specific region.
cmap_user (str) – Color map used on the plotting of the HiC data, by default PuOr_r.
mark_regions (pd.DataFrame, optional) – DataFrame containing the regions to be marked on the plot, by default None.
neighbourhood (bool, optional) – Draw a circle showing the neighbourhood around the point, by default False.

Returns:

gsp – matplotlib figure containing the Gaudi signal plot.

Return type:

matplotlib.pyplot.figure.Figure

Notes

The Gaudi signal plot is a plot of the LMI values for each bin in the region, where the color of the bin represents the signal value. The point of interest is represented by a green point.

metaloci.plot.plot.get_gaudi_type_plot(mlobject: MetalociObject, lmi_geometry: DataFrame, signipval: float = 0.05, colors_lmi: dict = None, mark_regions=None, neighbourhood=False)

Get a Gaudí type plot.

Parameters:

mlobject (mlo.MetalociObject) – METALoci object.
lmi_geometry (pd.DataFrame) – Merging from MetalociObject.lmi_info for a specific signal and MetalociObject.geometry for a specific region.
signipval (float, optional) – Significance threshold for p-value, by default 0.05.
colors_lmi (dict, optional) – Dictionary containing the colors of the quadrants to use in the plot, in matplotlib format; by default {1: “firebrick”, 2: “lightskyblue”, 3: “steelblue”, 4: “orange”}.

Returns:

gtp – matplotlib figure containing the Gaudi type plot.

Return type:

matplotlib.pyplot.figure.Figure

Notes

The Gaudi type plot is a plot of the LMI values for each bin in the region, where the color of the bin represents the quadrant to which the bin belongs. The significance of the LMI value is represented by the transparency of the color, where the more significant the LMI value, the more opaque the color. The point of interest is represented by a green point.

metaloci.plot.plot.get_hic_plot(mlobject: MetalociObject, del_args=None, cmap_user: str = 'YlOrRd', clean_mat: bool = False)

Create a plot of the HiC matrix for the region. Only the upper triangle of the array is represented, rotated 45ª counter-clock wise.

Parameters:

mlobject (mlo.MetalociObject) – METALoci object with a matrix (MetalociObject.matrix) in it.
cmap_user (str) – Color map used on the plotting of the HiC data, by default YlOrRd.
clean_mat (bool) – If True, the function will use the subset matrix, otherwise it will use the original matrix, by default False.

Returns:

matplotlib object containing the Hi-C matrix figure.

Return type:

matplotlib.pyplot.figure.Figure

metaloci.plot.plot.get_highlight(mlobject: MetalociObject, lmi_geometry: DataFrame, neighbourhood: float, quadrants: list = None, signipval: float = 0.05, metaloci_only: bool = False) → dict

Generate a dictionary containing metaloci information and their bin indices based on given parameters.

Parameters:

mlobject (mlo.MetalociObject) – A METALoci object.
lmi_geometry (pd.DataFrame) – A DataFrame containing LMI information and geometry of all bins in the region.
neighbourhood (float) – Radius of the circle that determines the neighbourhood of each of the points in the Kamada-Kawai layout.
quadrants (list, optional) – The list of quadrants to consider for selecting bins (default is [1, 3]).
signipval (float, optional) – The significance p-value threshold for selecting bins (default is 0.05).
metaloci_only (bool, optional) – If True, the function will only consider the region within a neighborhood radius around ‘mlobject.poi’, otherwise, it will consider all significant bins in ‘lmi_geometry’ (default is False).

Returns:

A dictionary containing bin indices of bins that meet the selection criteria, grouped by quadrants.

Return type:

dict

Notes

The function filters bins based on their significance p-value and quadrant, as specified by the parameters. If ‘metaloci_only’ is True, it will select bins that are adjacent to the specified ‘mlobject.poi’ within a distance of ‘neighbourhood’.

The resulting bed file data will contain the following columns:

‘chr’: The chromosome name of the metaloci.
‘start’: The start position of the metaloci on the chromosome.
‘end’: The end position of the metaloci on the chromosome.
‘bin’: The bin index representing the metaloci.
‘quadrant’: The quadrant to which the metaloci belongs.

metaloci.plot.plot.get_kk_plot(mlobject: MetalociObject, restraints: bool = True, neighbourhood: bool = False, remove_poi: bool = False)

Generate Kamada-Kawai plot from pre-calculated restraints.

Parameters:

mlobject (mlo.MetalociObject) – METALoci object with Kamada-Kawai graphs and nodes (MetalociObject.kk_nodes and MetalociObject.kk_graph).
restraints (bool, optional) – Boolean to set whether or not to plot restraints, by default True.
neighbourhood (float, optional) – Draw a circle showing the neighbourhood around the point, by default False.

Returns:

kk_plt – Kamada-Kawai layout plot object.

Return type:

matplotlib.pyplot.figure.Figure

metaloci.plot.plot.get_lmi_change_scan_plot(moran_data_folder: <module 'posixpath' (frozen)>, results_folder: <module 'posixpath' (frozen)> = None, poi: int = None)

Generates and saves a scatter plot visualizing the change in LMI (Local Moran’s I) scores over a series of deletions for a given point of interest (POI). The function reads multiple TSV files from the specified folder, extracts the LMI scores for the given POI, and calculates the mean and standard deviation of the scores. It then plots the scores along with the mean, ±2 standard deviation range, and highlights points that fall outside this range.

Parameters:

moran_data_folder (str) – Path to the folder containing the TSV files with Moran’s I data.
poi (int) – The point of interest (POI) for which the LMI scores are analyzed.

Saves:: A PNG file named lmi_change_scan_plot_<poi>.png in the specified folder, containing the generated plot.

Notes

Points with LMI scores below (mean - 2 * std_dev) are highlighted in blue, and points above (mean + 2 * std_dev) are highlighted in red.

metaloci.plot.plot.get_lmi_scatterplot(mlobject: MetalociObject, merged_lmi_geometry: DataFrame, neighbourhood: float, signipval: float = 0.05, zscore_signal: bool = False, colors_lmi: dict = None) → tuple

Get a scatterplot of Z-scores of signal vs Z-score of signal spacial lag, given LMI values.

Parameters:

mlobject (mlo.MetalociObject) – METALoci object.
lmi_geometry (pd.DataFrame) – Merging from MetalociObject.lmi_info for a specific signal and MetalociObject.geometry for a specific region.
neighbourhood (float) – Radius of the circle that determines the neighbourhood of each of the points in the Kamada-Kawai layout.
signipval (float, optional) – Significance threshold for p-value, by default 0.05.
colors_lmi (_type_, optional) – Dictionary containing the colors of the quadrants to use in the plot, in matplotlib format; by default {1: “firebrick”, 2: “lightskyblue”, 3: “steelblue”, 4: “orange”}.

Returns:

scatter (matplotlib.pyplot.figure.Figure) – matplotlib figure containing the LMI scatterplot.
r_value_scat (float) – r-value of the linear regression.
p-value – p-value of the linear regression.

metaloci.plot.plot.kk_plot_to_subplot(ax, mlobject: MetalociObject, restraints: bool = True, neighbourhood: float = None)

Generate Kamada-Kawai plot from pre-calculated restraints and plot it on the given axes.

Parameters:

ax (matplotlib.axes._subplots.AxesSubplot) – The axes on which to plot the Kamada-Kawai layout.
mlobject (mlo.MetalociObject) – METALoci object with Kamada-Kawai graphs and nodes (MetalociObject.kk_nodes and MetalociObject.kk_graph)
restraints (bool, optional) – Boolean to set whether or not to plot restraints, by default True
neighbourhood (float, optional) – Draw a circle showing the neighbourhood around the point, by default False

Return type:

None

metaloci.plot.plot.mixed_matrices_plot(mlobject: MetalociObject)

Get a plot of a subset of the Hi-C matrix with the top contact interactions in the matrix (defined by a cutoff) in the lower diagonal and the original Hi-C matrix in the upper diagonal, including a Kamada-Kawai plot.

Parameters:: mlobject (mlo.MetalociObject) – METALoci object with the flat original matrix (MetalociObject.flat_matrix), the MetalociObject.kk_top_indexes, and MetalociObject.kk_cutoff in it.
Returns:: fig_matrix – matplotlib object containing the mixed matrices figure.
Return type:: matplotlib.pyplot.figure.Figure

Notes

The mixed matrices plot is a plot of the Hi-C matrix for the region. Only the upper triangle of the array is represented, rotated 45º counter-clockwise. The top triangle is the original matrix, and the lower triangle is the subsetted matrix.

metaloci.plot.plot.place_composite(image: Image, image_to_add: str, ifactor: float, ixloc: int, iyloc: int)

Place an image on a composite image (PIL Image) at a specified location.

Parameters:

new_PI (PIL.Image.Image) – The composite image (PIL Image) to which the new image will be added.
ifile (str) – The filename or path of the image to be placed on the composite image.
ifactor (float) – The scaling factor for resizing the input image before placement.
ixloc (int) – The x-coordinate (horizontal position) at which the new image will be placed on the composite image.
iyloc (int) – The y-coordinate (vertical position) at which the new image will be placed on the composite image.

Returns:

The updated composite image (PIL Image) after adding the new image.

Return type:

PIL.Image.Image

metaloci.plot.plot.place_pdf(page: Page, pdf_path: str, target_width: float, x: float, y: float): Open a PDF file, extract the first page, and place it on a given page at a specified location and size. :param page: The page on which the PDF will be placed. :type page: fitz.Page :param pdf_path: The file path of the PDF to be placed. :type pdf_path: str :param target_width: The desired width of the placed PDF on the page. :type target_width: float :param x: The x-coordinate of the top-left corner where the PDF will be placed on the page. :type x: float :param y: The y-coordinate of the top-left corner where the PDF will be placed on the page. :type y: float

metaloci.plot.plot.save_mm_kk(mlobject: MetalociObject, work_dir: str, remove_poi: bool = False)

Save the mixed matrices and Kamada-Kawai plot for a given METALoci object.

Parameters:

mlobject (mlo.MetalociObject) – The METALoci object containing the mixed matrices and Kamada-Kawai plot.
work_dir (str) – The directory path where the plots will be saved.

metaloci.plot.plot.signal_plot(mlobject: MetalociObject, lmi_geometry: DataFrame, neighbourhood: float, quadrants: list = None, signipval: float = 0.05, metaloci_only: bool = False)

Generate a signal plot to visualize the signal intensity and the positions of significant bins.

Parameters:

mlobject (mlo.MetalociObject) – A METALoci object.
lmi_geometry (pd.DataFrame) – A DataFrame containing LMI information and geometry of all bins in the region.
neighbourhood (float) – Radius of the circle that determines the neighbourhood of each of the points in the Kamada-Kawai layout.
quadrants (list, optional) – The list of quadrants to consider for selecting bins (default is [1, 3]).
signipval (float, optional) – The significance p-value threshold for selecting bins (default is 0.05).
metaloci_only (bool, optional) – If True, the function will only consider the region within a neighborhood radius around ‘mlobject.poi’, otherwise, it will consider all significant bins in ‘lmi_geometry’ (default is False).

Returns:

matplotlib.figure.Figure – The matplotlib Figure object containing the signal plot.
matplotlib.axes._subplots.AxesSubplot – The matplotlib AxesSubplot object representing the plot.

Notes

The function generates a line plot of the signal intensity in ‘lmi_geometry’ with respect to the bin indices. It highlights the bins in the ‘metalocis’ list with red vertical lines if ‘metaloci_only’ is True, otherwise, it uses different colors for different quadrants.

Returns matplotlib.axes._subplots.AxesSubplot as it is used to create the composite plot.