Manual
The manual covers a few of the more technical aspects of running BioSAVE. To get started, first try the quick start guide and frequently asked questions page.
Keyboard shortcuts
When the sequence view has got focus, the following keyboard commands will move the sequence view left or right by these amounts:| Shortcut | Action |
| → | move 10 places right |
| ← | move 10 places left |
| ⌥ → | move 50 places right |
| ⌥ ← | move 50 places left |
| ⌘ ⌥ → | move 500 places right |
| ⌘ ⌥ ← | move 500 places left |
Annotation offsets
The following options appear at the bottom of every annotation open dialog box:
The drop down menu allows for selection of a plug-in (as described below).
The "Offset" text field allows a number to be entered that describes the offset between the annotation file and the sequence file. Unfortunately, the FASTA format doesn't formally allow any description of the "position" of a sequence. As such, BioSAVE doesn't know where any loaded sequence lies in its broader context (this applies more to DNA than to protein sequences).
The offset can be a positive or negative integer that describes how the annotation is offset from the sequence. Here are two examples of its use:
Example A
Here, the currently loaded sequence is considerably shorter than the annotation to be loaded. Since BioSAVE takes the start of every sequence to be 0, this example requires the annotation to be offset by -15,723,713. When BioSAVE reads in the annotation locations, the sequence position described as 15,723,713 in the file will be displayed at position 0 on screen.
Example B
Here the sequence is much longer than the annotation data. As in example A, BioSAVE takes the start of the sequence (2,583,125) to be position 0. Since the annotation starts at 4,867,976, we want the annotation in BioSAVE terms to begin at 2,284,851 (4,876,976 - 2,583,125). Therefore we need an offset of -2,583,125; BioSAVE will now read a position of 4,876,976 in the annotation file as 2,284,851, which will correctly position the annotation in the sequence.
Other possibilities
If your annotation file begins at position zero (for example), but it needs to appear somewhere further on in the sequence, a positive offset is required to add the appropriate amount to each position.
If your annotation data is "1-based" rather than "0-based" (i.e. starts at one rather than zero), an offset of -1 should be used to correctly align the annotation to the sequence.
Plug-ins
BioSAVE supports any plug-in that can run from the OS X command line and outputs GFF data to stdout.
With the correct shell environment variables and scripting language installations, this can include bash, tcsh, csh, ksh, perl, PHP, python, ruby, C, C++, Objective-C etc. etc. If a program can be run using the command line "./" notation, it can be used as a plugin. In addition to this requirement to be independently executable, BioSAVE needs the plugin to meet three criteria:
- It must output valid GFF format data to stdout. The specification for GFF can be found here.
- The second line of the plug-in code must be of the format: #BioSAVE:Human readable plugin name where "#" is the comment identifier of whichever language is in use (it may be more than one character) and everything after the colon (on that line) is what will be presented as the plug-in name in the open dialog box.
- The script must be placed in the directory ~/Application Support/BioSAVE/ in order for BioSAVE to locate it.
If the plug-in meets the above requirements, it will be loaded into the plug-ins menu when BioSAVE starts and called on demand when the user specifies that a file needs pre-processing with the plug-in in question. At that time, BioSAVE will spawn the plug-in process asynchronously, supplying a single, absolute file path to stdin. This is the path the file specified by the user in the open dialog.
It is conceivable, even likely, that plug-ins will ignore the file path argument, instead retrieving data from a MySQL database or by scraping a web page. This behaviour is perfectly acceptable, so long as that plug-in eventually returns GFF formatted data.
Motif colouring
The motif colouring algorithm in BioSAVE applies only to dynamically adjustable tracks and colours annotation instances depending upon annotation score and the current range specified by the user. The colour is calculated by applying the following alpha channel to the user-selected colour (if higher scores are considered better):
Where R is the current user-specified range of values and score is the score of the annotation in question (NB prior to the calculation, it is verified that the Rmax does not equal Rmin thus avoiding a divide by zero.)
Should you wish to change this "dynamic range" motif colouring scheme, the colouring is defined in Motif.m where the above equation is represented as 1.1-(((fabs(motifCutoffHigh-[[fields objectAtIndex:5] floatValue])/fabs(motifCutoffHigh-motifCutoffLow))*0.9)). Here, motifCutoffHigh and motifCutoffLow indicate the current user-selected threshold values and [[fields objectAtIndex:5] floatValue] is the score of the current annotation. In the instance where lower scores are considered better (hence darker), the latter portion of the equation is not subtracted from 1.1.