Python-based UCSC genome browser gallery generator
Python-based UCSC genome browser snapshot gallery-maker
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 pointing
soda to that browser instance's host name.
You provide the script with four required parameters:
- A BED-formatted file containing your regions of interest.
- The genome build name, such as
- The session 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.
- Where you want to store the gallery end-product.
If the BED file contains a fourth column (commonly used to store the name of the region), its values are used as labels for each page in the gallery.
Additional options are available; please see the Options section.
The BED file does not need to be in BEDOPS
sort-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 via
conda create and activate it. Then install via
$ python3 -m pip 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 called
123456_abcdef, with all your tracks selected and display parameters set, using
hg38 as the reference genome build. Finally, you want to store the results in a folder called
$ 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's
index.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 via
Four options are required. At minimum:
--regionsFn to specify the path to the input BED file containing regions of interest.
--browserBuildID option specifies the genome build, e.g.,
--browserSessionID option specify the browser session ID, which references a configuration of tracks and display parameters from a genome browser instance.
--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.
--title to specify a gallery title.
[ -i, --addIntervalAnnotation | -d, --addMidpointAnnotation ]
--addIntervalAnnotation to add a rectangle underneath all tracks that demarcates the original genomic range (useful when used with
--range). Alternatively, use
--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
-d to add an interval or midpoint annotation, these options may be used to override the default
rgba() 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 is
rgba(255, 0, 0, 0.333) and the default point size and font family values are
--range option to pad the BED input's midpoint symmetrically by the specified number of bases. This works regardless of the sort order of the input.
--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
-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.
Use this option if access to your custom browser instance requires a Kerberos ticket (obtained via
kinit, for example).
--verbose to print debug messages, which may be useful for automation or debugging.
The general "soda" gallery tool has been authored in various
bash- 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.
So what's up with the name?
"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
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Hashes for soda_gallery-1.0.1-py3-none-any.whl