Bandwagon reference manual

Ladder utilities

Definition of custom ladders for BandWagon.

bandwagon.ladders.custom_ladder(label, bands_migrations)

Generate a BandsPattern object meant to be used as a ladder.

By default the ladder is dark red on a white background.

bandwagon.ladders.ladder_from_aati_fa_calibration_table(filepath=None, dataframe=None, label=None)

Extract a BandPattern from an AATI Fragment Analyzer calibration file.

The calibration table is generated after each run from the migration times of the ladder and is generally in a file called something like 2016 11 08 16H 57M Size Calibration.csv.

This method requires Pandas installed.

Parameters:

• filepath – Path to the calibration file.

• dataframe – Pandas dataframe obtained by reading the file, can be provided instead of filepath.

• label – Label that will be given to the ladder when plotted.

BandsPatternsSet

Define Bandwagon’s classes Band, BandPattern, BandsPatternsSet.

class bandwagon.BandsPatternsSet.BandsPatternsSet(patterns, ladder, label=None, label_fontdict=None, global_patterns_props=None, ladder_ticks=None, ticks_fontdict=None, alternate_background_colors=('#e2edff', '#fffae2'))

A set of band patterns, that will be plotted next to one another.

Parameters:

• patterns – A list of patterns, in the order in which they will be displayed. Each pattern can be either a BandPattern object or a list of Band objects or a list of DNA sizes.

• ladder – A BandsPattern to use as a ladder.

• label – A label that will be displayed vertically on the left of the final plot.

• label_fontdict – Font dictionary for the label e.g. {‘color’: ‘red’, ‘size’: 7}.

• global_patterns_props – Properties that override that of each pattern in the set.

• ladder_ticks – List of DNA sizes that will be represented by ticks on the left of the plot to guide the reading.

• ticks_fontdict – Font dictionnary for the ticks indicating dna sizes.

• alternate_background_colors – Colors that will be alternated for the backgrounds of the different columns. Leave to None for no background. If some patterns have a background color set this color will override the alternate_background_colors.

plot(ax=None)

Plot the band patterns on the given Matplotlib ax.

plot_with_bokeh(max_visible_patterns=12, band_width_pixels=40)

Return an interactive (browser-based) Bokeh figure of the patterns.

Parameters:

• max_visible_patterns – Max number of patterns that will be visible at the same time. A horizontal scroll will allow to see more patterns if there are more.

• band_width_pixels – Size of a band width in pixels on the screen. Said otherwise, the final figure will have a width of band_width_pixels * visible.

BandsPattern

Define Bandwagon’s classes Band, BandPattern, BandsPatternsSet.

class bandwagon.BandsPattern.BandsPattern(bands, ladder=None, label=None, label_fontdict=None, corner_note=None, corner_note_fontdict=None, topology=None, background_color=None, width=1.0, global_bands_props=None, gel_image=None, gel_image_width=0.2, band_is_uncut=False)

Bands set forming a migration pattern. Also used to define ladders.

Parameters:

• bands – Either a list of Band objects, or a list of DNA sizes e.g. [800, 654, 1752]. In the latter case, a ladder must be provided to determine the elements.

• ladder – A BandsPattern to use as a ladder in case bands is a list of DNA sizes. Else leave it to None.

• label – Label to be printed on top of the band pattern.

• label_fontdict – A dict indicating the format of the label if any provided. For instance {'size': 7, 'rotation':30, 'color': '#0011aa'}.

• corner_note – Note to be printed in small prints in the corner of the band lane. Useful to print e.g. the total sum of all bands, or some remark.

• corner_note_fontdict – A dict indicating the format of the label if any provided. For instance {'size': 6, 'color': '#0011aa'}.

• topology – Another type of (top-right) corner note, either “circular” or “linear”.

• background_color – Background color of the column in which the pattern is plotted. Either the name of a color or a html code (‘#0012e4’).

• width – Width of the column (better keep to 1.0 if you want my humble opinion)

• global_bands_props – Dictionary of band properties overwriting that of all bands in the pattern, e.g. {'color': '#012ff45'}.

• gel_image – A numpy array of size w x h and values in 0-1 representing a gel image. This image will be superimposed on the right of the pattern’s color.

• gel_image_width – Width of the gel_image display (remember that the width of the column is 1.0, so 0.2 means this ‘photo’ will occupy 1/5 of the column, the rest being occupied by the pattern plot).

• band_is_uncut – If True, a “UNCUT” message will be added under the single band.

dna_size_to_migration(dna_sizes)

Return the migration distances for the given dna sizes.

initialize()

Create the variables necessary to compute some properties.

Concerned properties are self.dna_sizes, self.migration_distances, self.migration_distances_span, self.dna_size_span, and indirectly the functions dna_size_to_migration and migration_to_dna_size.

merge_with(other)

Merge this band pattern with another pattern’s bands.

migration_to_dna_size(migration_distances)

Return the dna sizes corresponding to the given migrations.

modified(**attributes)

Return a version of this bands pattern with modified attributes.

plot(ax, x_coord)

Plot background, bands, label, gel_image at the given x_coord.

Band

class bandwagon.Band.Band(dna_size, migration_distance=None, ladder=None, band_color='#000000', band_thickness=2, band_width=0.7, label=None, label_fontdict=None, html=None)

A band in a migration pattern.

This class controls all visual aspects of the band (form, color, label…).

Parameters:

• dna_size

• migration_distance – Observed migration distance of the band. Useful if you are using this band to define a ladder, otherwise keep to None.

• ladder – Ladder used to determine the migration distance of the band, if no migration_distance was provided.

• band_color – Color of the band. Can be a color name (like ‘black’, ‘red’…) or an hexadecimal code like ‘#001aff’ (this format is mandatory if you want to export to browser-based display.

• band_thickness – Thickness of the band in pixels.

• band_width – Proportion of the column width that is occupied by the band (the columns for each band pattern have a width of 1.0).

• label – Label to be printed on the band, if any provided. Set to ‘=size’ for printing the band sizes.

• label_fontdict – A dict indicating the format of the label if any provided. For instance {'size': 7, 'weight':'bold', 'color': '#0011aa'}.

• html – HTML appearing when hovering the band.

modified(**attributes)

Return a new version of this band, with modified attributes.

plot(ax, x_coord)

Plot the band’s line and label on the ax at the x-coordinate.

to_json(ladder=None)

Return a dictionary version of the band (for bokeh plotting).

Plots

class bandwagon.plot_records_digestions.DigestGraphicTranslator(features_filters=(), features_properties=None)

compute_feature_color(feature)

Compute a color for this feature.

If the feature has a color qualifier it will be used. Otherwise, the classe’s default_feature_color is used.

To change the behaviour, create a subclass of BiopythonTranslator and overwrite this method.

bandwagon.plot_records_digestions.annotate_digestion_bands(record, enzymes, ladder)

Annotate the record to indicate the regions corresponding to bands.

bandwagon.plot_records_digestions.plot_all_digestion_patterns(records, digestions, ladder, axes=None, group_by='digestions', show_band_sizes=False, plot_ladder=False)

Plot a grid (RECORD x DIGESTION) of predicted records digestions.

Parameters:

• records – List of biopython records whose digests need to be digested by the digestions.

• digestions – List of tuples of enzyme names e.g. [('BsaI',),`('MfeI', 'BsmBI')...] representing the digestions for the provided records.

• ladder – A Ladder object representing the ladder to be used for placing the bands axes. If None, new axes will be created.

• group_by – Either “sequence” or “digestion”. Determines the plotting order.

• show_band_sizes – If true, the band sizes will be printed on each band.

• plot_ladder

bandwagon.plot_records_digestions.plot_record_digestion(record_digestion, ladder, record_label, digestion_label)

Plot the digestion along with a schema of cuts locations in the record.

Parameters:

• record_digestion – Biopython record with features indicating bands.

• ladder

• record_label – Label to use as the title of the record digestion plot.

• digestion_label – Label to use as the title of the bands pattern(s).

bandwagon.plot_records_digestions.plot_records_digestions(target, ladder, records_and_digestions=None, records=None, digestions=None)

Plot records digestions in a multipage PDF file.

Parameters:

• target – path to a PDF file, or file-like object.

• ladder – A Ladder object representing the ladder to be used for placing the bands.

• records_and_digestions – A list [(record, digestion), …] where record is a Genbank record and digestions a tuple of enzymes. Alternatively, a list of records and digestions can be provided.

• records – List of biopython records whose digests need to be digested by the digestions.

• digestions – List of tuples of enzyme names e.g. [('BsaI',),`('MfeI', 'BsmBI')...] representing the digestions for the provided records.