pyranges-plot 0.0.23

'Gene visualization package for dataframe objects generated with PyRanges.'

pyranges_plot

Gene visualization package for dataframe objects generated with PyRanges.

Overview

The goal is getting a plot displaying a series of genes, transcripts, or any kind of ranges contained in a PyRanges object. It displays the genes' intron-exon structure in its corresponding chromosome, enabling easy visualization of your PyRanges data.

To obtain the plot there are some features to be defined by the user, one is the engine since it can be based on Matplotlib or Plotly, the other is the name of the gene ID column in your data. The rest of features can either be left as default or be customized. In example, the plot shows the first 25 genes of the dataframe by default, but this can be modified. It is worth noting that the order of the genes will be conserved when performing the subset.

In the case of coloring, Pyranges Plot offers a wide versatility. The data feature (column) according to which the genes will be colored is by default the gene ID, but this "color column" can be selected manually. Color specifications can be left as the default colormap (plotly.colors.qualitative.Alphabet) or be provided as dictionaries, lists or color objects from either Matplotlib or Plotly regardless of the chosen engine. When a colormap or list of colors is specified, the colors assigned to the genes will iterate over the provided ones following the color column pattern. In the case of concrete color instructions such as dictionary, the genes will be colored according to it while the non-specified ones will be colored in black.

Installation

PyRanges-Plot can be installed using pip:

pip install pyranges-plot

Examples

Minimal version

Next we will test pyranges_plot visualization options using the plot function. For that we will be using a PyRanges object generated from a dictionary.

import pyranges as pr
import pyranges_plot as prp

p = pr.from_dict({"Chromosome": [1, 1, 2, 2, 2, 2, 2, 3],
                  "Strand": ["+", "+", "-", "-", "+", "+", "+", "+"],
                  "Start": [1, 40, 10, 70, 85, 110, 150, 140],
                  "End": [11, 60, 25, 80, 100, 115, 180, 152], 
                  "transcript_id":["t1", "t1", "t2", "t2", "t3", "t3", "t3", "t4"], 
                  "feature1": ["a", "a", "b", "b", "c", "c", "c", "d"], 
                  "feature2": ["A", "A", "B", "B", "C", "C", "C", "D"]})
print(p)

+--------------+--------------+-----------+-----------+-----------------+------------+------------+
|   Chromosome | Strand       |     Start |       End | transcript_id   | feature1   | feature2   |
|   (category) | (category)   |   (int64) |   (int64) | (object)        | (object)   | (object)   |
|--------------+--------------+-----------+-----------+-----------------+------------+------------|
|            1 | +            |         1 |        11 | t1              | a          | A          |
|            1 | +            |        40 |        60 | t1              | a          | A          |
|            2 | +            |        85 |       100 | t3              | c          | C          |
|            2 | +            |       110 |       115 | t3              | c          | C          |
|            2 | +            |       150 |       180 | t3              | c          | C          |
|            2 | -            |        10 |        25 | t2              | b          | B          |
|            2 | -            |        70 |        80 | t2              | b          | B          |
|            3 | +            |       140 |       152 | t4              | d          | D          |
+--------------+--------------+-----------+-----------+-----------------+------------+------------+
Stranded PyRanges object has 8 rows and 7 columns from 3 chromosomes.
For printing, the PyRanges was sorted on Chromosome and Strand.

The generated data is a stranded PyRanges object containing 4 genes in 3 chromosomes as shown above. Having this example data stored in the variable p, we are able to start exploring Pyranges Plot options. We can get a plot in a single line:

prp.plot(p, engine="plt", id_col="transcript_id")

The output is an interactive Matplotlib plot. To obtain it we just need to provide the data, the engine and the name of the ID column. However, the engine and the ID column can be set previously so there is no need to specify them anymore while plotting:

# As engine use 'plotly' or 'ply' for Plotly plots and 'matplotlib' or 'plt' for Matplotlib plots
prp.set_engine('plotly')
prp.set_idcol('transcript_id')

Now the plots will be based on Plotly because we set it as the engine, though they will look the same as the Matplotlib ones. Also, both libraries offer interactive zoom options. For Matplotlib…

and for Plotly.

:left_right_arrow: Playing with limits

Since the data has only 4 genes all of them are plotted, but the function has a default limit of 25, so in a case where the data contains more genes it will only show the top 25, unless the max_ngenes parameter is specified. For example, we can set the maximum number of genes as 2. Note that in the case of plotting more than 25 a warning about the plot's integrity will appear.

prp.plot(p, max_ngenes=2)

Another pyranges_plot functionality is allowing to define the plots' coordinate limits through the limits parameter. The default limits show some space between the first and last plotted exons of each chromosome, but these can be customized. The user can decide to change all or some of the coordinate limits leaving the rest as default if desired. The limits can be provided as a dictionary, tuple or PyRanges object:

• Dictionary where the keys should be the data's chromosome names in string format and the values can be either None or a tuple indicating the limits. When a chromosome is not specified in the dictionary, or it is assigned None the coordinates will appear as default.
• Tuple option sets the limits of all plotted chromosomes as specified.
• PyRanges object can also be used to define limits, allowing the visualization of one object's genes in another object's range window.

prp.plot(p, limits={"1": (None, 100), "2": (60, 200), "3": None})
prp.plot(p, limits=(0,300))

:rainbow: Coloring

We can try to color the genes according to the strand column instead of the ID (default). For that the color_col parameter should be used.

prp.plot(p, color_col="Strand")

This way we see the "+" strand genes in one color and the "-" in another color. Additionally, these colors can be customized through the colormap parameter. For this case we can specify it as a dictionary in the following way:

prp.plot(
    p,
    color_col="Strand",
    colormap={"+": "green", "-": "red"}
)

The parameter colormap is very versatile because it accepts dictionaries for specific coloring, but also Matplotlib and Plotly color objects such as colormaps (or even just the string name of these objects) as well as lists of colors. For example, we can use the Dark2 Matplotlib colormap, even if the plot is based on Plotly:

prp.plot(p, colormap="Dark2")

:eyes: Display options

The disposition of the genes is by default a packed disposition, so the genes are preferentially placed one beside the other. But this disposition can be displayed as 'full' if the user wants to display one gene under the other by setting the packed parameter as False. Also, a legend can be added by setting the legend parameter to True.

prp.plot(p, packed=False, legend = True)

In interactive plots there is the option of showing information about the gene when the mouse is placed over its structure. This information always shows the gene's strand if it exists, the start and end coordinates and the ID. To add information contained in other dataframe columns to the tooltip, a string should be given to the showinfo parameter. This string must contain the desired column names within curly brackets as shown in the example. Similarly, the title of the chromosome plots can be customized giving the desired string to the title_chr parameter, where the correspondent chromosome value of the data is referred to as {chrom}. An example could be the following:

prp.plot(
    p, 
    showinfo="first feature: {feature1}\nsecond feature: {feature2}",
    title_chr = 'Chr: {chrom}'
)

:dizzy: Show transcript structure

Another interesting feature is showing the transcript structure, so the exons appear as wider rectangles than UTR regions. For that the proper information should be stored in the "Feature" column of the data. A usage example is:

pp = pr.from_dict({
	"Chromosome": [1, 1, 2, 2, 2, 2, 2, 3, 4, 4, 4, 4, 4, 4],
	"Strand": ["+", "+", "-", "-", "+", "+", "+", "+", "-", "-", "-", "-", "+", "+"],
	"Start": [1, 40, 10, 70, 85, 110, 150, 140, 30100, 30150, 30500, 30647, 29850, 29970],
	"End": [11, 60, 25, 80, 100, 115, 180, 152, 30300, 30300, 30700, 30700, 29900, 30000],
	"transcript_id":["t1", "t1", "t2", "t2", "t3", "t3", "t3", "t4", "t5", "t5", "t5", "t5", "t6", "t6"],
	"feature1": ["1", "1", "1", "1", "1", "2", "2", "2", "2", "2", "2", "2", "2", "2"],
	"feature2": ["A", "A", "B", "B", "C", "C", "C", "D", "E", "E", "E", "E", "F", "F"],
	"Feature": ["exon", "exon", "CDS", "CDS", "CDS", "CDS", "CDS", "exon", "exon", "CDS", "CDS", "exon", "CDS", "CDS"]
    
})

prp.plot(pp, transcript_str = True)

:dizzy: Reduce intron size

In order to facilitate visualization, pyranges_plot offers the option to reduce the introns which exceed a given threshold size. For that the introns_off parameter should be used. Additionally, the threshold can be defined by the user through kargs or setting the default as explained in the next section, using shrink_threshold, when a float is provided as shrink_threshold it will be interpreted as a fraction of the original coordinate range, while when an int is given it will be interpreted as number of base pairs.

ppp = pr.from_dict({'Chromosome': ['1']*10 + ['2']*10,
 'Strand': ['+','+','+','+','-','-','-','-','+','+'] + ["+", "+", "+", "+", "-", "-", "-", "-", "+", "+"],
 'Start': [90,61,104,228,9,142,52,149,218,151] + [5, 27, 37, 47, 1, 7, 42, 37, 60, 80],
 'End': [92,64,113,229,12,147,57,155,224,153] + [8, 32, 40, 50, 5, 10, 46, 40, 70, 90],
 'transcript_id': ['t1','t1','t1','t1','t2','t2','t2','t2','t3','t3'] + ["t4", "t4", "t4", "t4", "t5", "t5", "t5", "t5", "t6", "t6"],
 'Feature': ["exon"]*20
                    }
                   )

prp.plot(ppp, introns_off=True)
prp.plot(ppp, introns_off=True, shrink_threshold=0.2)

:ribbon: Appearance customizations

There are some features of the plot appearance which can also be customized, like the background, plot border or titles. To check these customizable features and its default values, the print_default function should be used. These values con be modified for all the following plots through the set_default function; However, for a single plot, these features can be given as kargs to the plot function (see shrink_threshold in the example above).

# Check the default values
prp.print_default()

+------------------------+-------+---------+--------------------------------------------------------------+
|        Feature         | Value | Edited? |                         Description                          |
+------------------------+-------+---------+--------------------------------------------------------------+
|     tag_background     | grey  |         | Background color of the tooltip annotation for the gene in   |
|                        |       |         | Matplotlib.                                                  |
|    plot_background     | white |         | Background color for the chromosomes plots.                  |
|      plot_border       | black |         | Color of the line defining the chromosome plots.             |
|       title_size       |  18   |         | Size of the plots' titles.                                   |
|      title_color       | black |         | Color of the plots' titles.                                  |
+------------------------+-------+---------+--------------------------------------------------------------+
|       exon_width       |  0.4  |         | Height of the exon rectangle in the plot.                    |
|    arrow_line_width    |   1   |         | Line width of the arrow lines (for stranded PyRanges).       |
|      arrow_color       | grey  |         | Direction arrow color (for stranded PyRanges).               |
|       arrow_size       | 0.006 |         | Fraction or percentage of the plot occupied by a direction   |
|                        |       |         | arrow.                                                       |
| arrow_intron_threshold | 0.04  |         | Minimum size of the intron to plot a direction arrow in it.  |
|                        |       |         | Provided as a float correspondig to the plot fraction or     |
|                        |       |         | percentage.                                                  |
+------------------------+-------+---------+--------------------------------------------------------------+
|    shrink_threshold    | 0.05  |         | Minimum lenght of an intron in order for it to be shrinked   |
|                        |       |         | while using the introns_off feature. When threshold is       |
|                        |       |         | float, it represents the percentage of the plot space,       |
|                        |       |         | while an int threshold represents number of positions or     |
|                        |       |         | base pairs.                                                  |
|      plotly_port       | 8050  |         | Port to run plotly app.                                      |
+------------------------+-------+---------+--------------------------------------------------------------+

Once you found the feature you would like to customize, it can be modified:

# Change the default values
prp.set_default('plot_background', 'rgb(173, 216, 230)')
prp.set_default('plot_border', '#808080')
prp.set_default('title_color', 'magenta')

# Make the customized plot
prp.plot(p)

Now the modified values will be marked when checking the default values:

prp.print_default()

+------------------------+--------------------+---------+--------------------------------------------------------------+
|        Feature         |       Value        | Edited? |                         Description                          |
+------------------------+--------------------+---------+--------------------------------------------------------------+
|     tag_background     |        grey        |         | Background color of the tooltip annotation for the gene in   |
|                        |                    |         | Matplotlib.                                                  |
|    plot_background     | rgb(173, 216, 230) |    *    | Background color for the chromosomes plots.                  |
|      plot_border       |      #808080       |    *    | Color of the line defining the chromosome plots.             |
|       title_size       |         18         |         | Size of the plots' titles.                                   |
|      title_color       |      magenta       |    *    | Color of the plots' titles.                                  |
+------------------------+--------------------+---------+--------------------------------------------------------------+
|       exon_width       |        0.4         |         | Height of the exon rectangle in the plot.                    |
|    arrow_line_width    |         1          |         | Line width of the arrow lines (for stranded PyRanges).       |
|      arrow_color       |        grey        |         | Direction arrow color (for stranded PyRanges).               |
|       arrow_size       |       0.006        |         | Fraction or percentage of the plot occupied by a direction   |
|                        |                    |         | arrow.                                                       |
| arrow_intron_threshold |        0.04        |         | Minimum size of the intron to plot a direction arrow in it.  |
|                        |                    |         | Provided as a float correspondig to the plot fraction or     |
|                        |                    |         | percentage.                                                  |
+------------------------+--------------------+---------+--------------------------------------------------------------+
|    shrink_threshold    |        0.05        |         | Minimum lenght of an intron in order for it to be shrinked   |
|                        |                    |         | while using the introns_off feature. When threshold is       |
|                        |                    |         | float, it represents the percentage of the plot space,       |
|                        |                    |         | while an int threshold represents number of positions or     |
|                        |                    |         | base pairs.                                                  |
|      plotly_port       |        8050        |         | Port to run plotly app.                                      |
+------------------------+--------------------+---------+--------------------------------------------------------------+

To return to the original appearance of the plot, the reset_default function can restore all or some parameters. By default, it will reset all the features, but it also accepts a string for resetting a single feature or a list of strings to reset a few.

prp.reset_default()  # reset all
prp.reset_default('plot_background')  # reset one feature
prp.reset_default(['plot_border', 'title_color'])  # reset a few features

Once we are able to get the plot we want, it can be exported to pdf or png format using the to_file parameter. This parameter takes a string with the name or path of the file including its extension. Additionally, the size can be customized through the file_size parameter by providing a tuple containing the height and width values.

# Build the plot and save it in pdf or png
prp.plot(p, to_file='my_plot.pdf', file_size=(1300, 600))

# An example of some pyranges adjustments and save
p_subset = p[p.transcript_id.isin(['t3', 't4'])]
prp.plot(p_subset, colormap='Set3', to_file='t3_t4_plot.png')

Coming soon

• Accept different PyRanges objects or DataFrames as input for the same plot.
• Bases will be displayed along coordinates.
• Colorblind friendly.