Repository files navigation

Python-based UCSC genome browser snapshot gallery-maker

• Description
• Dependencies
• Usage
• Options
• Credits

soda is a Python script that generates a gallery of images made from snapshots from a UCSC genome browser instance, so-called "soda plots". Snapshots can be derived from an external browser instance, by pointingsoda to that browser instance's host name.

You provide the script with four required parameters:

1. A BED-formatted file containing your regions of interest.
2. The genome build name, such ashg19,hg38,mm10, etc.
3. Thesession ID from your genome browser session, which specifies the browser tracks you want to visualize, as well as other visual display parameters that are specific to your session.
4. Where you want to store the gallery end-product.

If the BED file contains a fourth column (commonly used to store thename of the region), its values are used as labels for each page in the gallery.

Additional options are available; please see theOptions section.

The BED file does not need to be in BEDOPSsort-bed order. In fact, it can be useful to order the regions in a BED file by some criteria other than genomic position, such as some numerical value stored in the BED file's score column,e.g.:

$ sort -k5,5n input.bed> input_sorted_by_scores.bed

Any ordering is allowed. Gallery snapshots are presented in the same order as rows in the input BED file.

Set up a virtual environment viavirtualenv orconda create and activate it. Then install viapip:

$ python3 -m pip install soda-gallery

Or viaBioconda:

$ conda config --add channels bioconda$ conda install soda-gallery

Clone it from Github and install locally into a virtual environment:

$ git clone https://github.com/alexpreynolds/soda.git$cd soda$ python3 -m pip install -e.

As a usage example, you may have a BED file in some home directory called/home/abc/regions.bed. You have a session ID from the UCSC genome browser called123456_abcdef, with all your tracks selected and display parameters set, usinghg38 as the reference genome build. Finally, you want to store the results in a folder called/home/abc/my-soda-plot-results:

$ soda -r"/home/abc/regions.bed" -b"hg38" -s"123456_abcdef" -o"/home/abc/my-soda-plot-results"

If you run this locally, you can open the result folder'sindex.html file with your web browser to load the gallery. For example, from the Terminal application in OS X, you can run:

$ open /Users/abc/my-soda-plot-results/index.html

which opens the gallery index in your default web browser.

A full listing of options is available viasoda --help.

Four options are required. At minimum:

-r, --regionsFn

Use-r or--regionsFn to specify the path to the input BED file containing regions of interest.

-b, --browserBuildID

The-b or--browserBuildID option specifies the genome build,e.g.,hg19,mm10, etc.

-s, --browserSessionID

The-s or--browserSessionID option specify the browser session ID, which references a configuration of tracks and display parameters from a genome browser instance.

-o, --outputDir

Use the-o or--outputDir option to specify where the image gallery is saved. If this path already exists,soda will exit with a fatal error message.

Other options are available depending on how you want to customize the run.

-t, --title

Use-t or--title to specify a gallery title.

[ -i, --addIntervalAnnotation|-d, --addMidpointAnnotation ]

Use-i or--addIntervalAnnotation to add a rectangle underneath all tracks that demarcates the original genomic range (useful when used with--range). Alternatively, use-d or--addMidpointAnnotation to add a vertical line underneath all tracks, centered on the midpoint of the input genomic range. In both cases, the annotation is labeled with the genomic coordinates of the original interval or the calculated midpoint, respectively. It is not allowed to specify both options together.

-w, --annotationRgba-z, --annotationFontPointSize-f, --annotationFontFamily

When used with-i or-d to add an interval or midpoint annotation, these options may be used to override the defaultrgba() color, typeface point size, and typeface family (where supported by the local installation of ImageMagick), which are parameters used to render the appearance of the annotation components. The default color isrgba(255, 0, 0, 0.333) and the default point size and font family values are5 andHelvetica-Bold, respectively.

-a, --range

Use the-a or--range option to pad the BED input'smidpoint symmetrically by the specified number of bases. This works regardless of the sort order of the input.

-g, --browserURL

Use the-g or--browserURL option to specify a different genome browser URL other than the UCSC genome browser. If a different host is specified and credentials are required, please use the-u and-p options (see below).

-u, --browserUsername-p, --browserPassword

Use these two options to specify a username and password for the browser instance, if you pick a different--browserURL and that browser instance requires basic credentials. If these options are not specified, no credentials are passed along. If authentication is required and it fails,soda may exit with an error.

-y, --useKerberosAuthentication

Use this option if access to your custom browser instance requires a Kerberos ticket (obtained viakinit, for example).

-v, --verbose

Use-v or--verbose to print debug messages, which may be useful for automation or debugging.

Use the-m option to specify the gallery framework. The default isphotoswipe; alternatively, useblueimp to generate a blueimp-backed gallery.

The general "soda" gallery tool has been authored in variousbash- and Perl-flavored incarnations since 2008 by primary authors Richard Sandstrom and Scott Kuehn, with modifications over time by Bob Thurman, Jay Hesselberth, Richard Humbert, Brady Miller and Alex Reynolds.

This Python rewrite and new functionality were authored by Alex Reynolds.

This tool uses thePhotoSwipe,blueimp Gallery andGithub octicons projects, which are MIT-licensed.

"Scott Kuehn: he came up with the name. The legend is that when asked what to call the program, he lifted a can of cola, sighed deeply, and said: 'soda plot'." - R. Sandstrom