AnnoTrack Tracking System

Related topics:
A general introduction to this tracking system.
A user documentation.
The download page.
Some adminstration issues

Setting up a new system & adjusting it to your needs¶

The system is flexible enough to be of use for other groups and projects performing genome annotation in a collaborative effort and is therefor provided here. These are notes on how to start a new annotation project with AnnoTrack.

General Redmine installation notes for troubleshooting are here, but all the sourcecode required for AnnoTrack is available here.

Most of the AnnoTrack code is written as a plugin for the Redmine system (rails/vendor/plugins/redmine_annotrack), but since there are some other changes required, which override Redmine's default code, you will need the complete package from this site.

• you will need
  • a database server (e.g. mysql 5)
  • ruby on rails installation
    source and help on the official rails page
    documention for running on MaxOSX (usually pre-installed)
  • a web server (e.g. Apache) when running in production mode, for testing, the Webbrick server supplied with Rails is fine.
• get the AnnoTrack source code and database from this page
  unpack: tar xzvf annotrack.version.tgz

• create your database
  mysql -u<user> -p<password> -h<host> -P<port> -e"create database annotrack"
  mysql -u<user> -p<password> -h<host> -P<port> -Dannotrack < annotrack/database.sql

  The main tables fo the database are outlined in this diagram.

• we have frozen the additional external Rails modules used by the application (gems) into the AnnoTrack rails code (rails/vendor/rails/) so you don't necessarily need to install all of them separately.
• set your environment variables GEM_PATH and RAILS_ENV in your shell or in the file annotrack/rails/config/environment.rb
• adjust the database configurations file in annotrack/rails/config/database.yml with your settings (production and development if desired)
  additional environments can be created (e.g. for multiple organisms) by adding an entry (e.g. "production_housemouse") and a file in environments (e.g. environments/production_housemouse.rb)
• start the server e.g. on port 6223:
  cd annotrack/rails
  ruby scripts/server -edevelopment -p6223 (to use the development setup)
• log in as administrator ("admin"/"admin") to set up some initial values.
  The admin interface from Redmine is at http://localhost:6223/admin, modifications should in particular be made on these pages:
  A. Settings: "Application title", "Welcome text", "Host name"
  B. AnnoTrack settings: "Menu links", "Browsers links", "other settings"
  vendor/plugins/redmine_annotrack/lang/en.yml holds the URL patterns used for browser links.
  C. Flags: define new flags to highlight errors
  D. Users: create & adjust user accounts

• we have stored a gene with two transcript with two flags for demonstration;
  you can see these by clicking on "Transcripts" at the top of the page and then selecting "View all transcripts".
• you can create a new gene-level entry manually at http://localhost:6223/projects/add for testing, in general these will be created by scripts writing directly to the database.

• You can adjust the settings for your system in the central config.pm file.
• We use the scripts/cron_jobs.pl file the run automatic updates of the core annotation, to update the stats given on the fron page (issue and flag counts), please adjust this to your needs
  Some Perl programming knowledge is required to adjust / write parsers to handle the specific data you will be using.
• The following additional perl modules (most of which are part of a standard installation) are required to use the AnnoTrack perl API:
  • Bio::Das::Lite
  • MIME::Lite
  • DBI
  • Getopt::Long
  • UNIVERSAL::require
  • Bio::EnsEMBL::DBSQL::DBAdaptor (when accessing Ensembl-style databases)
• most probably you will have to adjust the source-specific scripts used for data loading and analysis stored in annotrack/perl/modules/annotrack
• further hints:
  • New genes/transcripts, categories and flags would usually be created by script access. There are functions for all this functionality which is documented here
  • This is a basic source adaptor reading data from a tab-delimited file to demonstrate how the modules work.
  • This is an example source adaptor to demonstrate a module reading from a database with DBI.
  • Here is the Perl-doc of the AnnoTrack core module.

• to customize the system for your own set-up there are a number of files you can modify:
  • rails/app/views/layouts/base.rhtml: Start page layout
  • rails/vendor/plugins/redmine_annotrack/lang/en.yml: Names and paths to browsers and project-related links
• we are using a Lucene-based search engine for AnnoTrack, there is a switch option between this and the Redmine-internal search enginge on the Administration/Settings/Annotrack page
• the scripts annotrack/perl/scripts/cron_jobs.pl.example and annotrack/perl/scripts/cron_queries.sh.example should be adjusted with your environment and run regulary (nightly) to update annotation data, update counts and optimize tables.
• many "helper variables" are stored in the tmp_values table. Have a look there if stats etc. are not displayed as expected.

Upgrading

General notes on upgrading existing Redmine installations are here
There will usually be an upgraded AnnoTrack version made available here after a major Redmine upgrade.

Some Screenshots of the application