LaneRuler - automated lane tracking software for electrophoresis gels

Overview

.  Different gel format are supported via a range of command line flags.  The gel has to have at least two marker lanes, where all marker lanes are placed in regular intervals. 

java application.  The application overlays given lane tracking results on top of a given gel image.  The adjustment is done via dragging on the nodes on screen. 

Installation

  Copy this file to an accessible place and run the file from a command prompt.

file to suit your needs. 

files included for more details on installation.

Typical usage

The typical usage of the package is to generate lane tracking results and a lane straightened image when given a gel image.  Depending on whether review and adjustment of result is required, the process flow follows different path.

Lane Tracking

expects the following as input:

• gel image (default name: image.tif): a 16-bit TIFF image of the gel, in which the wells of the gel can be along any of the four edges

will write the following files in the same directory as the gel image.  Please ensure write permission to the folder is available.

• list of node locations (default name: lanes): a text file that list the x, y positions of all the nodes in pixels
• lane straighted version of gel (default name: traces16_auto): a header followed by binary image data of a lane straightened gel
• analysis data file (set name:  LR_data.out): a text file that stores intermediate variables in the analysis for later review
• error file (set name: LR_error.out): a text file where any possible error messages are listed
• empty lane test file (set name: LR_no_grow.out): a text file with two smoothness measure for each lane to help identify empty data lanes
• gel analysis parameters file (set name: LR_LIMS.out): a text file with parameters specific for gel level analysis
• lane striaghted image (optional, use -o <path>): a 8-bit PNG image of the lane straightened version of the gel
• diagnostic image (optional, use -d <path>): a 8-bit PNG of the gel image with lane tracking result overlaid

Please refer to the Option section below or use the "--help" flag for a list of all the options available.

Based on the possible error message, the user can decide if manual review of the results are required.  If not, the output files can be used for subsequent gel analysis appropriate to the type of gel.

Results Review

requires two files as input.  Since the interface make use of a graphical file chooser, there are no specific naming requirements.  The required inputs are:

• gel image: a JEPG, GIF, TIFF, or PNG image of the gel, in which the wells of the gel can be along any of the four edges
• list of node locations: a text file that list the x, y positions of all the nodes in pixels, in the same format as the output file of findlanes
  

.  The output file cannot have the same name as the input file.  An explanation of the available paramters can be found in the Option section, below. 

On the adjustment screen, the nodes can be dragged for adjustment.  Adjusting a marker node will automatically place the adjancent data nodes in equal distance partition until the next marker node.  The adjustment screen has a number of on screen control across the top.  From left to right, they serve the following function:

• "+": zoom in in both x and y direction
• "-": zoom out in both x and y direction
• "RESET": reset the zoom to initial values
• "x": the zoom factor in the x direction, larger values zoom in
• "y": the zoom factor in the y direction, larger values zoom in
• "Transparent Overlay": turns on/off the semi-transparent overlay over the lines being moved
• "Save": write current node positions to output file
• "Revert to Last Save": restore the node positions to when the results were last saved
• "Revert to Initial Results": restore the node positions to as described in input file
• "Done": close this gel image and return to the parameter screen

again.

Lane-Straightened Image Regeneration

create lane-straightened image based on a given set of node positions.  To do this, use the "--readlanes" flag.  Note that the number of zones and lanes have to correspond to the input file.  In such cases, the program expects the following as input:

• gel image (default name: image.tif): a 16-bit TIFF image of the gel, in which the wells of the gel can be along any of the four edges
• list of node locations (use --readlanes <path>, default name: lanes): a text file that list the x, y positions of all the nodes in pixels

will write all the output file except for the list of node positions in the same directory as the gel image.  Please ensure write permission to the folder is available.

Options

findlanes options

• Gel format options:
• --gelspan [GELSPANFACTOR]: Minimum ratio of gel width (across lane dimension) to the image size [0,1] (default=0.75)
• --markeroffset [MARKEROFFSET]: Location of first marker lane (default=0)
• --lastmarkeroffset [LASTMARKEROFFSET]: Offset of last marker lane from the last lane, the location used will be the last valid marker position defined by marker period that is not pass this point (default=0)
• --markerperiod [MARKERPERIOD]: Period between marker lanes (default=5 lanes)
• --numlanes [NUMLANES]: Number of lanes (default=121 lanes)
• --numzones [NUMZONES]: Number of zones (default=10 zones)
• --orientation [WELL_EDGE]: Edge closest to the wells of the image, defining orientation 0=LEFT, 1=TOP 2=RIGHT 3=BOTTOM (default=0)
• Input file structure options:
• --projectdir [PROJECTDIR], -p [PROJECTDIR]: Project directory (default=.)
• --imagepath  [GELIMAGE]: Name of gel image (default=image.tif)
• --readlanes [LANESFILE]: Use lanes file to generate traces16, no lane tracking is done if used. (default file name=lanes)
• Output file structure options:
• --tracespath [TRACESNAME]: Name of the traces file (default=traces16_auto)
• --lanespath  [LANESNAME]: Name of the lanes file (default=lanes)
• Program control options
• --noadjust, -a: Turn off tone adjusting in low contrast zones (default=tone adjusting on)
• --nosmooth, -s: Turn off lane smoothing (default=smoothing on)
• --matchall  -i: Switch to match peaks to all lanes even in zone with marker frequency dominance (default=match only marker lanes in marker dominated zones)
• --nogrowoff: Turn of no grow and contamination detection
• --diagnostic [DIAGNOSTIC], -d [DIAGNOSTIC]: Name of the output diagnostic image (png format)
• --Verbose, -v: Select verbose mode, information output to stderr (default = nonverbose)
• --help: Show this usage information
• Analysis parameters:
• --morphelement [ELEMENT]: Size of the morphological structural element (default=image width/10)
• --peaksizefactor [PEAKCUTOFF]: Minimum fraction of maximum peak size in the zone for a peak to be used (range [0,1]) (default=0.000000) 
  
• --borderroughness [ROUGHNESS]: Minimum roughness of border marker lanes (default=1.800000)
• --bordercorrelation [CORRELATION]: Minimum correlation of border marker lanes to each other (default=0.980000)
• --borderneighbourcorrelation [CORRELATION]: Minimum correlation of border marker lanes to its neighbour (default=0.980000)
• Results checking parameters:
• --anasegments [NUMSEGMENTS]: Number of segments in which the result checking is done. (default=3)
• --markerroughness [ROUGHNESS]: Minimum roughness of marker lanes within any segments (default=0.500000)
• --markercorrelation[CORRELATION]: Minimum correlation between neighbouring marker lanes within any segments (default=0.975000)
• --totalintdata [INTERPOLATED LANES]: Maximum number of interpolated lanes allowed in a zone (default=40)
• --totalintmarker [INTERPOLATED MARKERS]: Maximum number of interpolated markers allowed in a zone (default=15)
• --consecintdata [INTERPOLATED LANES]: Maximum number of consecutive interpolated lanes allowed in a zone (default=5)
• --consecintmarker [INTERPOLATED MARKERS]: Maximum number of consecutive interpolated markers allowed in a zone (default=3)
• --lanespacecheck [LANESPACEFACTOR]: Fraction of the generic lane space used as tolerance for actual lane spacings(default=0.200000)
• --numoutliers [OUTLIER NUMBER]: Maximum number of outliers allowed in the gel (default=10)
• --asymwhisker [WHISKER FACTOR]:  Factor used to calculate cutoff for asymmetry within each zone (default=3.000000)
• --consecasymsoft [CONSECUTIVE ASYMMETRY CUTOFF]: Number of consecutive asymmetric lanes to warrant adjustment (default=5)
• --consecasymhard [CONSECUTIVE ASYMMETRY CUTOFF]: Number of consecutive asymmetric lanes to fail gel (default=5)
• --slopethreshold [SLOPE_THRESHOLD]: Threshold used to determine the thresholded roughness.  (default=1)
• --noisetoFGratio [RATIO]: ratio of noise compared to signal for a point to be identified to have noise (default=0.350000)
• --minfg [INTENSITY]: minimum intensity for the noise to fg ratio to be considered (default=10)
•   --noisespanfactor [FLOAT]: Amount of noise as multiple of lane width identified in a lane to be qualified as noisy (default=1.000000)

LaneRulerUI options

• Path to gel image: the path to the gel image.  The image file can be a TIFF, GIF, JPEG, or PNG, though not necessary with proper extension.  If the path to the input lanes file is entered while this field is empty, this field will be auto-filled with path to a "image.tif" in the same directory as the input lanes file.
• Path to input lanes file: the path to the initial list of node positions.  It is a text file whose format conforms to that output from findlanes.  If the path to the gel image is entered while this field is empty, this field will be auto-filled with path to a "lanes" in the same directory as the input lanes file.
• Path to output lanes file:  the path to which the final node positions will be written.  It is a text file whose format conforms to that output from findlanes.   This cannot be the same as the path to the input lanes file.
• Number of Lanes:  the number of lanes in the gel, used mainly to verify the file with the input node positions
• Marker offset:  the location of first marker lane.  Note that findlanes labels the bottommost lane as the first lane.
  
• Last marker offset: number of lanes the last marker lane is from the last lane. Note that findlanes labels the bottommost lane as the first lane.
• Marker period: period of lanes between marker lanes.  This can also be viewed as the number of lanes between marker lanes + 1.
• Gel edge with well: the edge of the image closest to the wells in the original image.  The image will be rotated such that the well edge is on the left for display purpose.
• Initial X zoom factor:  the initial zoom factor in the x dimension.  Larger values zoom in.
• Initial Y zoom factor:  the initial zoom factor in the y dimension.  Larger values zoom in.
• Size of node marker:  the length, in image pixel, of the side of the square used to denote a node.  If the scale factor is different for x and y, the smaller factor will be used.
• Size of lane overlay:  the height, in image pixel, of the height of the transparent overlay used during node movement.