Automation

Why Automate?

You've seen one genome assembly, you've seen 'em all -- hardly! But there are some very predictable, repetitive things that developers need to do every time we build a genome annotation database on a new genome assembly. It is in our best interest to automate these steps when possible for these reasons:

• it saves time
• it reduces copy-paste and didn't-see-that-error-message errors
• it helps to enforce naming conventions, which helps us use each other's data
• it can produce detailed and accurate documentation of the data
• it keeps our eyes from glazing over

Of course, nothing is for free. When something goes wrong in an automated process, we must work our way back from a usually cryptic error message through an additional level of code to the source of the problem. (Or if it's GenBank automation, bug MarkD. ;) But the hope is that developers will spend their time on more tasks that require critical thinking and fewer boring repetitive tasks.

The 5/30/06 genecats meeting was devoted to discussion and planning of build automation; Hiram transcribed the whiteboard notes from the meeting in High Throughput Genome Builds.

GenBank Update Automation Is a Whole 'Nother Story

This page focuses solely on automation of genome annotation database and download files excluding MarkD's amazing GenBank update system. That is much more complicated and better engineered than the simple scripts described here, which have borrowed or otherwise duplicated a few of its concepts. The source for the GenBank update system is in kent/src/hg/makeDb/genbank/ and MarkD has documented it [here].

Automation Scripting Infrastructure

[Perl] has been used for the libraries and scripts here because (let's be honest) Angie likes it. Some of the good reasons for that include Perl's integral support for regexes, hashes, lists/arrays and (to a certain extent) objects. Also, since Perl is interpreted, development and testing/debugging can happen in an extremely tight loop.

All files mentioned in this section are in kent/src/utils/ .

Libs

Several Perl libraries (or "modules") contain shared code, variables and/or define objects that support automation of complex build processes in our compute environment. The infrastructure absolutely depends on smooth functioning of ssh -- you should set up a passkey to use with ssh-agent and ssh-add.

• HgAutomate.pm - routines for querying the available compute power in our clusters and workhorse machines, support for common command line arguments, variables with local paths, and general utility routines for running jobs.
• HgRemoteScript.pm - an object for creating and executing a crash-on-failure script to be executed on a particular machine (e.g. on a cluster hub, workhorse, fileserver or database host).
• HgStepManager.pm - an object for defining and executing sequential steps in a build process. Typically each step will run on a different machine. Also includes support for command line options to select steps to run.

Template for new automation scripts

doTemplate.pl contains the skeleton of a multi-step process. Copy it to a new script file, replace all instances of "Template" and "template" with whatever seems appropriate, chmod a+x the new script, and run it -- it internally forces -debug and verbose until you change that too.

Existing Automation Scripts

Existing automation scripts reside in kent/src/utils/automation/ . The names start with "make" or "do", loosely following this pattern: "make" scripts generate files or database tables that are not standalone tracks (although makeGenomeDb does build a few simple tracks while setting up the database), while "do" scripts perform specific track build processes. "do" scripts are more likely to include cluster runs, but they don't have to.

Each script relies on naming conventions and the existence of certain files. Some scripts require a configuration file and some don't. Each script gives detailed usage information if run with -help.

• makeGenomeDb.pl - creates /cluster/data/$db/ directory structure, fetches mitochondrion sequence from GenBank if specified, makes $db.unmasked.2bit, fakes or checks AGP depending on whether it's included in the assembly, creates $db with several assembly tracks, adds $db to central database (hgcentraltest), and creates templated trackDb/$org/$db/*.html files which require some editing by the developer.
• doRepeatMasker.pl - runs RepeatMasker, loads $db.(chr*_)rmsk, makes $db.rmsk.2bit.
• makeDownloads.pl - makes goldenPath/{bigZips,database(,chromosomes)} and README.txt files (editing required).
• doSameSpeciesLiftOver.pl - runs blat -fastMap, nets, creates and installs liftOver chains.
• doBlastzChainNet.pl - runs the blastz/chain/net process for cross-species or self alignments.
• doHgNearBlastp.pl - runs blastp on protein sequences of one species' known genes vs. other species, loads *BlastTab tables which are not track tables but are used by hgGene and hgNear.
• makePushQSql.pl - creates a .sql file which should be checked, edited and then executed on hgwbeta to create a new push queue (and main push queue entry) for $db. Give Q/A a heads-up before and/or after this.
• doEnsGeneUpdate.pl - fetch a version of Ensembl genes and load into a UCSC database

Automation Wish List

Infrastructure

• Smarter distribution of inputs to cluster run

Scripts/Processes

• Repeat library generation (WindowMasker?)
• simpleRepeat (TRF)
• masking of 2bit sequence with both RepeatMasker and TRF output, distribution to cluster-local storage
• Brian's chained protein alignments
• CpG islands
• genscan
• multiz
• phastCons
• meta-automation of all blastz's, multiz, phastCons?
• meta-automation of all scripts that we always run?

Automation Troubleshooting

• fileserver/machines out of sync
• cluster job dies
• cluster job hangs
• ssh hangs