Package: oligo-capture
For full documentation, seehttp://oligo.readthedocs.iooligoprovides functionality to automate oligo (bait) design for DNA capture experiments, providing the user with details about capture efficiency of the sequences generated.Since version 0.2, oligo provides a more efficient installation process and provides the user with the option of running the tool via a Docker image. This version is still
in a pre-release beta phase. For the older format of oligo, please use version 0.1.2. Documentation specific for v0.1.2 can be found herehttps://oligo.readthedocs.io/en/0.1.2/.Table of ContentsInstallationLocalDockerUsageInstallationLocaloligoTo installoligoon your local machine, it is recommended to first create a new Python environment ( >=3.8 ) using your preferred method e.g.conda,pyenvetc. Once the new environment is activated, installoligoviapip. Note that the package is calledoligobut has a published name ofoligo-captureto ensure it had a unique name in the public repository.$pipinstalloligo-captureEnsure it has installed correctly by running the following command and verifying that you see the installed version in the standard output$python-moligo--versionoligov0.2Before running the fulloligopipeline you will need to install RepeatMasker and either BLAT or STAR, depending on how you intend to runoligo(see below for more details)DependenciesSince running oligo locally requires a number of third-party software to be installed, users might find it less hassle to runoligovia the Docker image, if this option is available to them. See theDockersection for more details.RepeatMaskeroligouses RepeatMasker (RM) to determine if oligos contain simple sequence repeats as these can reduce the efficiency of the oligo for targeted capture. Follow the instructions
onRepeatMasker home pagefor installing RM on your local system. The most recent version of RM thatoligohas been tested with is v4.1.5. As detailed
on the RM home page, its installation depends on a Sequence Search Engine (it is recommended to useHMMERforoligo) and Tandem Repeat Finder (TRF). For the Repeat Database, RM ships
with the curated set of Dfam 3.7 Transposable Elements which is sufficient but users are free to use the full set if required; further instructions are on the RM home page.The RM home page mentions that it requires the Python libraryh5py, however this is listed as a dependency of theoligopackage so will already be installed in your Python environment
from when you ran thepip installstep.BLAToligouses the BLAST-Like Alignment Tool (BLAT) to determine any off-target binding sites of an oligo within the genome, in addition to its intended binding site. An oligo that binds
to multiple regions will have a reduced score since it will perform a less-specific capture.BLATexecutables can be found by going tohttp://hgdownload.soe.ucsc.edu/admin/exe/and locating the BLAT directory in the for your systems archtecture. For example, for Linux.x86 architecture,rsyncshould be used
to get the BLAT executables on your system:$rsync-aPrsync://hgdownload.soe.ucsc.edu/genome/admin/exe/linux.x86_64/blat/./Seehttp://hgdownload.soe.ucsc.edu/admin/exe/linux.x86_64/blat/for more details.Please note, that as specified on its website, “the Blat source and executables are freely available for academic, nonprofit and personal use. Commercial licensing information is
available on the Kent Informatics website (http://www.kentinformatics.com/)”. Ensure that you are adhering to this licence agreement if you are usingoligowith--blatenabled.STARAs an alternative to BLAT,oligoallows users to use the Spliced Transcripts Alignment to a Reference (STAR) alignment program for increased speed when determining multiple binding
events for oligo sequences. BLAT is more widely used to detect off-target binding events, however BLAT can be particulary slow for large designs, especially for the human
reference genomes. STAR’s exceptional speed is better suited for designs with >1000 oligos. If you think you would prefer to use STAR instead, visit theSTAR GitHub pagefor instructions on how to install it.DockerDue tooligorequiring various third-party software, it can instead be run from a pre-built Docker image that has everything needed already installed. This should make the setup much
easier for users as well as reducing the need to install lots of software on their local machines. Running via Docker is obviously less flexible in terms of the configuration of the
third-party software but has been built with the most common use cases in mind and reducing the image size to as small as possible, without losing any of requirementsoligouses from
the third-party software.Currently the Docker image only supports running oligo with BLAT, not STAR.First pull the latest oligo image onto your local machine:$dockerpulljbkerry/oligo:latestYou can also specify a version if needed. The Docker image versions match the oligo package version i.e., jbkerry/oligo:0.2 will be runningoligov0.2:$dockerpulljbkerry/oligo:0.2The docker entrypoint is set to runoligowith the config file already set up to point to the install executables of BLAT and RepeatMasker so users can run the image, starting with
theoligosubcommand that is required (see theUsagesection for more details).In order for your BED file and reference genome FASTA files to be accessible to the Docker container, your local directories with these files must be mounted into the Docker container
using the-voption when you call thedocker runcommand on the image. The Docker image runs theoligocommand from a top-level directory called/resultsand stores
all of its output files here. In order to see them on your local machine after the run has finished, you will need to mount a local directory where you want to store the results, to
this/resultsdirectory. Again, this mount with the-voption needs to be done at the image runtime.For example, running theoligocommand with theoff-targetsubcommand might look something like this with the Docker image:$dockerrun-v/local/path/oligo_results:/results-v/local/human:/genomejbkerry/oligo:latestoff-target-f/genome/genome.fa-ghg38-b./off_target_sites.bed-o100-t50-m300--blatWith this command, the output results will appear in the example local directory of/local/path/oligo_results. Note that this example command is using the Linux filepath
format (i.e.,/.../) for the local directories. On Windows (not using WSL) the mounting would look like this:$ docker run -v C:\local\path\oligo_results:/results -v C:\local\human:/genome jbkerry/oligo:latest off-target -f /genome/genome.fa -g hg38 -b ./off_target_sites.bed -o 100 -t 50 -m 300 --blatBecause the docker image is built on top of a Debian Linux image, the paths that local directories get mounted to in the container (i.e. the right-hand side of the:for
the-voptions) still need to use the Linux filepath format, even when running from a Windows machine.Installation specificsBelow is a list of the versions and alterations that have been made to the standard installs of third-party software for theoligoDocker image:RepeatMasker v4.1.5Dfam.h5 library has been replaced with an HMM matrices containing only mouse- and human-specific transposable elements in order to reduce the size of the Docker imageHMMER v3.3.2Tandem Repeat Finder v4.09.1BLAT v37.x1The HMM matrices were generated with the following two commands, run from with the top-level RepeatMasker directory (famdb.pycomes bundled with the latest versions of RepeatMasker):$./famdb.py-iLibraries/RepeatMaskerLib.h5families--formathmm'Homo sapiens'--include-class-in-name>humans.hmm$./famdb.py-iLibraries/RepeatMaskerLib.h5families--formathmm'Mus musculus'--include-class-in-name>mouse.hmmThe Dockerfile in theoligoGitHub repository can be referenced for details of the how the Docker image was built. Some reference data files that get copied into the image at build
time are not present in the repository but can be provided to the user if needed.Usageoligocan be run with one of three subcommandscapture: designs oligos for a standard Capture-C experiment. The user supplies a list of viewpoint coordinates, and oligos are generated adjacent to the flanking recognition sequence of a specified restriction enzyme.tiled: designs oligos for multiple adjacent restriction fragments across a specified region of a chromosome, or for the entire chromosome. Iftiledis run in contiguous mode, oligos are generated independent of restriction fragments and
are instead generated for a user-specified step size, in an adjacent manner.off-target: designs oligos to capture DNA surrounding potential CRISPR off-target cut sites to allow for efficient sequencing to determine off-target activity.These subcommands all generate oligo sequences, based on different underlying behaviours. Methods from theToolsclass in theoligo.toolsmodule are then used to check
the off-target binding and repeat content of the oligos. This information is output in a file calledoligo_info.txt; oligo sequences are written to a FASTA file calledoligo_seqs.faExampleThe subcommand follows theoligocommand and options for the subcommand are then specified afterwards. Note that the config text file, specifying paths to the installed RepeatMasker,
BLAT and STAR directories (seeDependencies) must be specified betweenoligoand the chosen subcommand, with the-cfgargument. An example config file can be viewedhere. Below, is an example using theoff-targetsubcommand:$python-moligo-cfg./config.txtoff-target-f/path/to/human/genome.fa-ghg38-b./off_target_sites.bed-o100-t50-m300--blatCommand-line helpTheoligooptions and subcommands can be viewed with the--helpflag from the command-line:$python-moligo--helpUsage:python-moligo[OPTIONS]COMMAND[ARGS]...Options:--version-cfg,--configPATH[required]--helpShowthismessageandexit.Commands:captureoff-targettiledFor options specific to each subcommand, runoligowith the desired subcommand, followed by--help. Note that you will need to provide the-cfgflag for this to work:$python-moligo-cfg./config.txtoff-target--helpUsage:python-moligooff-target[OPTIONS]Options:-f,--fastaPATHPathtoreferencegenomefasta.[required](etc.)For full documentation on each of the subcommands and how each of their options affects the run, see the full documentation athttp://oligo.readthedocs.io. There you will find
a detailed documentation page for each of the subcommands, as well as information regarding the oligo output file and how best to make use of it.