cicada 0.9.0-java

data/lib/cicada/correction/correction.rb

@@ -0,0 +1,363 @@
+#--
+# /* ***** BEGIN LICENSE BLOCK *****
+#  * 
+#  * Copyright (c) 2012 Colin J. Fuller
+#  * 
+#  * Permission is hereby granted, free of charge, to any person obtaining a copy
+#  * of this software and associated documentation files (the Software), to deal
+#  * in the Software without restriction, including without limitation the rights
+#  * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+#  * copies of the Software, and to permit persons to whom the Software is
+#  * furnished to do so, subject to the following conditions:
+#  * 
+#  * The above copyright notice and this permission notice shall be included in
+#  * all copies or substantial portions of the Software.
+#  * 
+#  * THE SOFTWARE IS PROVIDED AS IS, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+#  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+#  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+#  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+#  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+#  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+#  * SOFTWARE.
+#  * 
+#  * ***** END LICENSE BLOCK ***** */
+#++
+
+require 'rexml/document'
+require 'ostruct'
+require 'cicada/mutable_matrix'
+
+require 'facets/enumerable/ewise'
+
+module Cicada
+
+  ##
+  # An error indicating that a position cannot be corrected (probably due to incomplete
+  # coverage in the correction dataset).
+  class UnableToCorrectError < StandardError; end
+
+  ##
+  # Stores data for a standard 3d high-resolution colocalization correction, including
+  # positions for a number of objects used for correction, and local quadratic fits of
+  # aberration near these objects.  Can correct 2d positions based upon this data.
+  # 
+  class Correction
+    
+    # Strings used in XML elements and attributes when writing a correction to an XML format
+    XML_STRINGS = { correction_element: "correction",
+      correction_point_element: "point", 
+      n_points_attr: "n",
+      ref_channel_attr: "reference_channel",
+      corr_channel_attr: "correction_channel",
+      x_pos_attr: "x_position",
+      y_pos_attr: "y_position",
+      z_pos_attr: "z_position",
+      x_param_element: "x_dimension_parameters",
+      y_param_element: "y_dimension_parameters",
+      z_param_element: "z_dimension_parameters",
+      binary_data_element: "serialized_form",
+      encoding_attr: "encoding",
+      encoding_name: "base64"}
+
+    # Number of parameters used for correction (6, as this is the number of parameters 
+    # for a 2d quadratic fit)
+    NUM_CORR_PARAM = 6
+
+    attr_accessor :tre, :correction_x, :correction_y, :correction_z, :reference_channel, :correction_channel, :positions_for_correction, :distance_cutoffs
+
+    ##
+    # Constructs a new correction based on the supplied data 
+    #
+    # @param [Array<MVector>] c_x an array of mutable vectors each of which contains the parameters for
+    #  the interpolating function centered at an image object used for correction in the x direction
+    # @param [Array<MVector>] c_y an array of mutable vectors each of which contains the parameters for
+    #  the interpolating function centered at an image object used for correction in the y direction
+    # @param [Array<MVector>] c_z an array of mutable vectors each of which contains the parameters for
+    #  the interpolating function centered at an image object used for correction in the z direction
+    # @param [MVector] distance_cutoffs a mutable vector containing the distance to the farthest point
+    #  used to generate the interpolating function for each image object
+    # @param [Array<ImageObject>] image_objects the image objects used for correction
+    # @param [Integer] reference_channel  the reference channel relative to which others are corrected
+    # @param [Integer] correction_channel the channel being corrected
+    #
+    def initialize(c_x, c_y, c_z, distance_cutoffs, image_objects, reference_channel, correction_channel)
+
+      @correction_x = c_x
+      @correction_y = c_y
+      @correction_z = c_z
+      @reference_channel = reference_channel
+      @correction_channel = correction_channel
+      @distance_cutoffs = distance_cutoffs
+
+      n_dims = 3
+
+      @positions_for_correction = MMatrix.build(image_objects.size, n_dims) do |r, c|
+
+        image_objects[r].getPositionForChannel(reference_channel).toArray[c]
+
+      end
+
+    end
+
+    ##
+    # Writes the correction to a specified file in XML format.
+    # 
+    # @param [String] fn the filename to which to write the correction
+    # 
+    # @return [void]
+    #
+    def write_to_file(fn)
+      
+      File.open(fn, 'w') do |f|
+
+        f.puts(write_to_xml)
+
+      end
+
+    end
+
+    ##
+    # Writes the correction to a string in XML format
+    # 
+    # @return [String] the correction data encoded as XML
+    #
+    def write_to_xml
+      
+      doc = REXML::Document.new
+
+      ce = doc.add_element XML_STRINGS[:correction_element]
+
+      ce.attributes[XML_STRINGS[:n_points_attr]] = @distance_cutoffs.size
+
+      ce.attributes[XML_STRINGS[:ref_channel_attr]] = @reference_channel
+
+      ce.attributes[XML_STRINGS[:corr_channel_attr]] = @correction_channel
+      
+      @distance_cutoffs.each_with_index do |e, i|
+
+        cp = ce.add_element XML_STRINGS[:correction_point_element]
+
+        cp.attributes[XML_STRINGS[:x_pos_attr]]= @positions_for_correction[i,0]
+        cp.attributes[XML_STRINGS[:y_pos_attr]]= @positions_for_correction[i,1]
+        cp.attributes[XML_STRINGS[:z_pos_attr]]= @positions_for_correction[i,2]
+
+        xp = cp.add_element XML_STRINGS[:x_param_element]
+
+        xp.text = @correction_x[i].to_a.join(", ")
+
+        yp = cp.add_element XML_STRINGS[:y_param_element]
+
+        yp.text = @correction_y[i].to_a.join(", ")
+
+        zp = cp.add_element XML_STRINGS[:z_param_element]
+        
+        zp.text = @correction_z[i].to_a.join(", ")
+        
+      end
+
+      bd = ce.add_element XML_STRINGS[:binary_data_element]
+
+      bd.attributes[XML_STRINGS[:encoding_attr]]= XML_STRINGS[:encoding_name]
+
+      bin_data = Base64.encode64(Marshal.dump(self))
+
+      bd.text = bin_data
+
+      doc_string = ""
+
+      doc.write doc_string, 2
+
+      doc_string
+
+    end
+
+    ##
+    # Reads a correction from a specified file containing an XML-encoded correction.
+    #
+    # @param [String] fn the filename from which to read the correction
+    #
+    # @return [Correction] the correction contained in the file.
+    #
+    def self.read_from_file(fn)
+
+      return nil unless File.exist?(fn)
+      
+      xml_str = ""
+
+      File.open(fn) do |f|
+
+        xml_str = f.read
+
+      end
+
+      read_from_xml(xml_str)
+
+    end
+
+
+    ##
+    # Reads a correction from an XML string.
+    #
+    # @param [String] xml_str the XML string containing the information
+    #
+    # @return [Correction] the correction contained in the string.
+    #
+    def self.read_from_xml(xml_str)
+
+      doc = REXML::Document.new xml_str
+
+      bin_el = doc.root.elements[1, XML_STRINGS[:binary_data_element]]
+
+      Marshal.load(Base64.decode64(bin_el.text))
+
+    end
+
+    
+
+    ##
+    # Calculates the 2d distances from a specified 2d point to the centroid of each of the image objects
+    # used for the correction.
+    #
+    # @param [Numeric] x the x coordinate of the point
+    # @param [Numeric] y the y coordinate of the point
+    #
+    # @return [Vector] the distance from the specified point to each image object.
+    #
+    def calculate_normalized_dists_to_centroids(x,y)
+
+      dists_to_centroids = @positions_for_correction.column(0).map { |x0| (x0-x)**2 }
+
+      dists_to_centroids += @positions_for_correction.column(1).map { |y0| (y0-y)**2 }
+
+      dists_to_centroids = dists_to_centroids.map { |e| Math.sqrt(e) }
+
+      dists_to_centroids.map2(@distance_cutoffs) { |e1, e2| e1/e2 }
+
+    end
+
+    ##
+    # Calculates the weight of each local quadratic fit for correcting a specified point.
+    #
+    # @param (see #calculate_normalized_dists_to_centroids)
+    #
+    # @return [Vector] the weights for each local fit used for correction
+    #
+    def calculate_weights(x, y) 
+
+      dist_ratio = calculate_normalized_dists_to_centroids(x,y)
+
+      dist_ratio_mask = MVector.zero(dist_ratio.size)
+
+      dist_ratio_mask = dist_ratio.map { |e| e <= 1 ? 1 : 0 }
+
+      weights = dist_ratio.map { |e| -3*e**2 + 1 + 2*e**3 }
+
+      weights.map2(dist_ratio_mask) { |e1, e2| e1*e2 }
+
+    end
+
+    ##
+    # Selects the local fits and their associated image objects that are to be used for correcting
+    # a specified point (i.e. those fits with nonzero weight).
+    #
+    # @param (see #calculate_normalized_dists_to_centroids)
+    #
+    # @return [OpenStruct, #cx, #cy, #cz, #x_vec, #y_vec, #weights] an OpenStruct containing the
+    #  selected fits for the x dimension, y dimension, and z dimension; the x and y positions 
+    #  of the selected image objects used for correction; and the weights of the fits
+    #
+    def find_points_for_correction(x,y)
+      
+      weights = calculate_weights(x,y)
+
+      count_weights = weights.count { |e| e > 0 }
+
+      raise UnableToCorrectError, "Incomplete coverage in correction dataset at (x,y) = (#{x}, #{y})." if count_weights == 0
+
+      cx = MMatrix.zero(count_weights, @correction_x[0].size)
+      cy = MMatrix.zero(count_weights, @correction_y[0].size)
+      cz = MMatrix.zero(count_weights, @correction_z[0].size)
+      
+      x_vec = MVector.zero(count_weights)
+      y_vec = MVector.zero(count_weights)
+
+      kept_weights = MVector.zero(count_weights)
+
+      kept_counter = 0
+
+      weights.each_with_index do |w, i|
+
+        if w > 0 then
+
+          cx.replace_row(kept_counter, @correction_x[i])
+          cy.replace_row(kept_counter, @correction_y[i])
+          cz.replace_row(kept_counter, @correction_z[i])
+          
+          x_vec[kept_counter] = x - positions_for_correction[i,0]
+          y_vec[kept_counter] = y - positions_for_correction[i,1]
+
+          kept_weights[kept_counter] = weights[i]
+
+          kept_counter += 1
+
+        end
+
+      end
+
+      OpenStruct.new(cx: cx, 
+                     cy: cy, 
+                     cz: cz, 
+                     x_vec: x_vec, 
+                     y_vec: y_vec,
+                     weights: kept_weights)
+
+    end
+
+    ##
+    # Calculates the correction for a specified position.
+    #
+    # @param (see #calculate_normalized_dists_to_centroids)
+    #
+    # @return [MVector] a mutable vector containing the correction in the x, y, and z dimensions
+    #  for the specified position.
+    # 
+    def correct_position(x, y)
+ 
+      points = find_points_for_correction(x,y)
+
+      x_corr = 0.0
+      y_corr = 0.0
+      z_corr = 0.0
+
+      all_correction_parameters = MMatrix.columns([MVector.unit(points.x_vec.size), 
+                                                  points.x_vec, 
+                                                  points.y_vec, 
+                                                  points.x_vec.map { |e| e**2 }, 
+                                                  points.y_vec.map { |e| e**2 }, 
+                                                  points.x_vec.map2(points.y_vec) { |e1, e2| e1*e2 }])
+
+ 
+      all_correction_parameters.row_size.times do |i|
+
+        x_corr += all_correction_parameters.row(i).inner_product(points.cx.row(i))*points.weights[i]
+        y_corr += all_correction_parameters.row(i).inner_product(points.cy.row(i))*points.weights[i]
+        z_corr += all_correction_parameters.row(i).inner_product(points.cz.row(i))*points.weights[i]
+
+      end
+
+      sum_weights = points.weights.reduce(0.0) { |a,e| a + e }
+
+      x_corr /= sum_weights
+      y_corr /= sum_weights
+      z_corr /= sum_weights
+
+      MVector[x_corr, y_corr, z_corr]
+
+    end
+
+  end
+
+end
+
+

data/lib/cicada/correction/position_corrector.rb

@@ -0,0 +1,501 @@
+#--
+# /* ***** BEGIN LICENSE BLOCK *****
+#  * 
+#  * Copyright (c) 2013 Colin J. Fuller
+#  * 
+#  * Permission is hereby granted, free of charge, to any person obtaining a copy
+#  * of this software and associated documentation files (the Software), to deal
+#  * in the Software without restriction, including without limitation the rights
+#  * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+#  * copies of the Software, and to permit persons to whom the Software is
+#  * furnished to do so, subject to the following conditions:
+#  * 
+#  * The above copyright notice and this permission notice shall be included in
+#  * all copies or substantial portions of the Software.
+#  * 
+#  * THE SOFTWARE IS PROVIDED AS IS, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+#  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+#  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+#  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+#  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+#  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+#  * SOFTWARE.
+#  * 
+#  * ***** END LICENSE BLOCK ***** */
+#++
+
+require 'cicada/mutable_matrix'
+
+require 'cicada/correction/correction'
+
+require 'ostruct'
+
+require 'pqueue'
+
+require 'facets/enumerable/ewise'
+require 'facets/math/mean'
+
+require 'rimageanalysistools/fitting/bisquare_linear_fit'
+require 'rimageanalysistools/thread_queue'
+
+java_import Java::org.apache.commons.math3.linear.ArrayRealVector
+java_import Java::java.util.concurrent.Executors
+
+module Cicada
+
+  ##
+  # Generates and applies aberration corrections.  Used both for standard 3d 
+  # high-resolution colocalization corrections and in-situ corrections.
+  #
+  class PositionCorrector
+
+    # parameters required by the methods in this class
+    REQUIRED_PARAMETERS = [:pixelsize_nm, :z_sectionsize_nm, :num_points, :reference_channel, :channel_to_correct]
+
+    # parmeters used but not required in this class or only required for optional functionality
+    OPTIONAL_PARAMETERS = [:determine_correction, :max_threads, :in_situ_aberr_corr_channel, :inverted_z_axis, :disable_in_situ_corr_constant_offset]
+
+    # Number of parameters used for correction (6, as this is the number of parameters 
+    # for a 2d quadratic fit)
+    NUM_CORR_PARAM = 6
+
+    attr_accessor :parameters, :pixel_to_distance_conversions
+
+    ##
+    # Constructs a new position corrector with the specified parameters
+    #
+    # @param [ParameterDictionary, Hash] p a hash-like object containing the analysis parameters
+    #
+    def initialize(p)
+      @parameters = p
+      @pixel_to_distance_conversions = Vector[p[:pixelsize_nm].to_f, p[:pixelsize_nm].to_f, p[:z_sectionsize_nm].to_f]
+    end
+
+
+    ##
+    # Creates a RealVector (org.apache.commons.math3.linear.RealVector) that is a copy of
+    # the contents of the supplied vector.
+    #
+    # @param [Vector] vec the Vector to convert
+    #
+    # @return [RealVector] the commons math RealVector containing the same elements
+    #
+    def self.convert_to_realvector(vec)
+
+      conv = ArrayRealVector.new(vec.size, 0.0)
+
+      vec.each_with_index do |e, i|
+
+        conv.setEntry(i, e)
+
+      end
+
+      conv
+
+    end
+
+
+    ##
+    # Generates a correction from a specified array of image objects.
+    #
+    # @param [Array<ImageObject>] iobjs the image objects to be used for the correction
+    #
+    # @return [Correction] the correction generated from the input objects
+    #
+    def generate_correction(iobjs)
+      
+      #TODO refactor into smaller chunks
+
+      ref_ch = parameters[:reference_channel].to_i
+      corr_ch = parameters[:channel_to_correct].to_i
+
+      unless parameters[:determine_correction] then
+
+        return Correction.read_from_file(FileInteraction.correction_filename(parameters))
+
+      end
+
+      correction_x = []
+      correction_y = []
+      correction_z = []
+
+      distance_cutoffs = MVector.zero(iobjs.size)
+
+      iobjs.each_with_index do |obj, ind|
+
+        obj_pos = obj.getPositionForChannel(ref_ch)
+        
+        distances_to_objects = iobjs.map { |obj2| obj2.getPositionForChannel(ref_ch).subtract(obj_pos).getNorm }
+               
+        pq = PQueue.new
+
+        np = @parameters[:num_points].to_i
+
+        distances_to_objects.each do |d|
+
+          if pq.size < np + 1 then
+
+            pq.push d
+
+          elsif d < pq.top then
+
+            pq.pop
+            pq.push d
+
+          end
+
+        end
+
+
+        first_exclude = pq.pop
+
+        last_dist = pq.pop
+
+        distance_cutoff = (last_dist + first_exclude)/2.0
+
+        distance_cutoffs[ind] = distance_cutoff
+
+        objs_ind_to_fit = (0...iobjs.size).select { |i| distances_to_objects[i] < distance_cutoff }
+                
+        objs_to_fit = iobjs.values_at(*objs_ind_to_fit)
+
+        diffs_to_fit = MMatrix[*objs_to_fit.map { |e| e.getVectorDifferenceBetweenChannels(ref_ch, corr_ch).toArray }]
+        x_to_fit = objs_to_fit.map { |e| e.getPositionForChannel(ref_ch).getEntry(0) }
+        y_to_fit = objs_to_fit.map { |e| e.getPositionForChannel(ref_ch).getEntry(1) }
+        
+        x = Vector[*x_to_fit.map { |e| e - obj_pos.getEntry(0) }]
+        y = Vector[*y_to_fit.map { |e| e - obj_pos.getEntry(1) }]
+
+        correction_parameters = Matrix.columns([MVector.unit(objs_to_fit.size), x, y, x.map { |e| e**2 }, y.map { |e| e**2 }, x.map2(y) { |ex, ey| ex*ey }])
+
+        cpt = correction_parameters.transpose
+
+        cpt_cp = cpt * correction_parameters
+
+        cpt_cp_lup = cpt_cp.lup
+
+        correction_x << cpt_cp_lup.solve(cpt * diffs_to_fit.column(0))
+        correction_y << cpt_cp_lup.solve(cpt * diffs_to_fit.column(1))
+        correction_z << cpt_cp_lup.solve(cpt * diffs_to_fit.column(2))
+     
+
+      end
+
+      Correction.new(correction_x, correction_y, correction_z, distance_cutoffs, iobjs, ref_ch, corr_ch)
+
+    end
+
+    ##
+    # Changes the scale of a vector from image units to physical distances using distance specified
+    # in the analysis parameters.
+    #
+    # @param [Vector] vec the vector to scale
+    # 
+    # @return [Vector] the vector scaled to physical units (by parameter naming convention, in nm)
+    #
+    def apply_scale(vec)
+
+      vec.map2(@pixel_to_distance_conversions) { |e1, e2| e1*e2 }
+
+    end
+
+    ##
+    # Corrects an array of image objects using the provided correction.
+    #
+    # @param [Correction] c the correction to be used
+    # @param [Array<ImageObject>] iobjs the image objects to be corrected.
+    # 
+    # @return [Array<Numeric>] the corrected scalar difference between
+    #  wavelengths for each image object provided.
+    #
+    def apply_correction(c, iobjs)
+     
+      ref_ch = @parameters[:reference_channel].to_i
+      corr_ch = @parameters[:channel_to_correct].to_i
+
+      vec_diffs = iobjs.map { |e| e.getVectorDifferenceBetweenChannels(ref_ch, corr_ch) }
+
+      vec_diffs.map! { |e| apply_scale(Vector[*e.toArray]) }
+
+      corrected_vec_diffs = []
+
+      if @parameters[:correct_images] then
+
+        iobjs.each do |iobj|
+
+          begin
+
+            corrected_vec_diffs << correct_single_object(c, iobj, ref_ch, corr_ch)
+
+            iobj.setCorrectionSuccessful(true)
+
+          rescue UnableToCorrectError => e
+
+            iobj.setCorrectionSuccessful(false)
+
+          end
+
+        end
+
+        corrected_vec_diffs.map! { |e| apply_scale(e) }
+
+      else 
+
+        corrected_vec_diffs = vec_diffs
+        
+      end
+      
+      print_distance_components(vec_diffs, corrected_vec_diffs)
+
+      corrected_vec_diffs.map { |e| e.norm  } 
+
+    end
+
+    ##
+    # Prints the mean scalar and vector differences both corrected and uncorrected.
+    #
+    # @param [Array<Vector>] vec_diffs an array of the uncorrected vector differences
+    # @param [Array<Vector>] corrected_vec_diffs an array of the corrected vector differences
+    #
+    # @return [void]
+    #
+    def print_distance_components(vec_diffs, corrected_vec_diffs)
+
+      mean_uncorr_vec = [0.0, 0.0, 0.0] 
+
+      vec_diffs.each do |e|
+
+        mean_uncorr_vec = mean_uncorr_vec.ewise + e.to_a
+
+      end
+
+      mean_corr_vec = [0.0, 0.0, 0.0]
+
+      corrected_vec_diffs.each do |e|
+
+        mean_corr_vec = mean_corr_vec.ewise + e.to_a
+
+      end
+
+      mean_uncorr_vec.map! { |e| e / vec_diffs.length }
+
+      mean_corr_vec.map! { |e| e / corrected_vec_diffs.length }
+
+      #TODO - logging
+
+      puts "mean components uncorrected: [#{mean_uncorr_vec.join(', ')}]"
+      puts "mean distance uncorrected: #{Vector[*mean_uncorr_vec].norm}"
+      puts "mean components corrected: [#{mean_corr_vec.join(', ')}]"
+      puts "mean distance corrected: #{Vector[*mean_corr_vec].norm}"
+
+    end
+
+    ##
+    # Corrects a single image object for the two specified channels.
+    #
+    # @param [Correction] c the correction to be used
+    # @param [ImageObject] iobj the object being corrected
+    # @param [Integer] ref_ch the reference channel relative to which the other will be corrected
+    # @param [Integer] corr_ch the channel being corrected
+    #
+    # @return [Vector] the corrected (x,y,z) vector difference between the two channels
+    #
+    def correct_single_object(c, iobj, ref_ch, corr_ch)
+      
+      corr = c.correct_position(iobj.getPositionForChannel(ref_ch).getEntry(0), iobj.getPositionForChannel(corr_ch).getEntry(1))
+
+      if parameters[:invert_z_axis] then
+
+        corr.setEntry(2, -1.0*corr.getEntry(2))
+
+      end
+
+      iobj.applyCorrectionVectorToChannel(corr_ch, PositionCorrector.convert_to_realvector(corr))
+      
+      Vector.elements(iobj.getCorrectedVectorDifferenceBetweenChannels(ref_ch, corr_ch).toArray)
+
+    end
+
+    ##
+    # Generates an in situ aberration correction (using the data specified in a parameter file)
+    #
+    # @return @see #generate_in_situ_correction_from_iobjs
+    #
+    def generate_in_situ_correction
+      
+      iobjs_for_in_situ_corr = FileInteraction.read_in_situ_corr_data(@parameters)
+
+      generate_in_situ_correction_from_iobjs(iobjs_for_in_situ_corr)
+
+    end
+
+    ##
+    # Generates an in situ aberration correction from the supplied image objects.
+    #
+    # @param [Array<ImageObject>] an array containing the image objects from which the in situ
+    #  correction will be generated
+    #
+    # @return [Array< Array<Numeric> >] an array containing the x, y, and z corrections; each
+    #  correction is a 2-element array containing the slope and intercept for the fit in each
+    #  dimension.  The intercept will be zero if disabled in the parameter file.
+    #
+    def generate_in_situ_correction_from_iobjs(iobjs_for_in_situ_corr)
+
+      ref_ch = @parameters[:reference_channel].to_i
+      corr_ch = @parameters[:channel_to_correct].to_i
+      cicada_ch = @parameters[:in_situ_aberr_corr_channel]
+
+      corr_diffs = Matrix.rows(iobjs_for_in_situ_corr.map { |iobj| iobj.getCorrectedVectorDifferenceBetweenChannels(ref_ch, cicada_ch).toArray })
+      expt_diffs = Matrix.rows(iobjs_for_in_situ_corr.map { |iobj| iobj.getCorrectedVectorDifferenceBetweenChannels(ref_ch, corr_ch).toArray })
+
+      bslf = BisquareLinearFit.new
+
+      bslf.disableIntercept if @parameters[:disable_in_situ_corr_constant_offset]
+
+      all_parameters = 0.upto(corr_diffs.column_size - 1).collect do |i|
+
+        bslf.fit_rb(corr_diffs.column(i), expt_diffs.column(i)).toArray
+
+      end
+     
+      all_parameters
+
+    end
+
+    ##
+    # Applies an in situ aberration correction to an array of image objects.
+    #
+    # @param [Enumerable<ImageObject>] iobjs the objects to be corrected
+    # @param [Array< Array<Numeric> >] corr_params the in situ correction parameters (an array
+    #  for each dimension containing the correction's slope and intercept).
+    # 
+    # @return [Array< Array <Numeric> >] an array of the corrected vector distance between
+    #  wavelengths for each image object being corrected.
+    #
+    def apply_in_situ_correction(iobjs, corr_params)
+
+      corr_params = corr_params.transpose
+
+      ref_ch = @parameters[:reference_channel].to_i
+      corr_ch = @parameters[:channel_to_correct].to_i
+      cicada_ch = @parameters[:in_situ_aberr_corr_channel]
+
+      corrected_differences = iobjs.map do |iobj|
+        
+        corr_diff = iobj.getCorrectedVectorDifferenceBetweenChannels(ref_ch, cicada_ch).toArray.to_a
+        expt_diff = iobj.getCorrectedVectorDifferenceBetweenChannels(ref_ch, corr_ch).toArray.to_a
+
+        correction = (corr_diff.ewise * corr_params[0]).ewise + corr_params[1]
+
+        Vector.elements(expt_diff.ewise - correction, false)
+
+      end
+
+      corrected_differences
+          
+    end
+
+    ##
+    # Caluclates the target registration error (TRE) for an array of image objects
+    # to be used for correction.
+    #
+    # @param [Enumerable<ImageObject>] iobjs the objects whose TRE will be calculated
+    # 
+    # @return [Float] the (3d) TRE
+    #
+    def determine_tre(iobjs)
+      
+      ref_ch = @parameters[:reference_channel].to_i
+      corr_ch = @parameters[:channel_to_correct].to_i
+
+      results = []
+
+      max_threads = 1
+
+      if @parameters[:max_threads]
+        max_threads = @parameters[:max_threads].to_i
+      end
+
+      tq = Executors.newFixedThreadPool(max_threads)
+
+      mut = Mutex.new
+
+      iobjs.each_with_index do |iobj, i|
+
+        RImageAnalysisTools::ThreadQueue.new_scope_with_vars(iobj, iobjs, i) do |obj, objs, ii|
+          
+          tq.submit do 
+            
+            puts "Calculating TRE.  Progress: #{ii} of #{objs.length}" if ii.modulo(10) == 0
+
+            temp_objs = objs.select { |e| e != obj }
+
+            c = generate_correction(temp_objs)
+
+            pos = obj.getPositionForChannel(ref_ch)
+            
+            result = OpenStruct.new
+
+            begin
+            
+              corr = c.correct_position(pos.getEntry(0), pos.getEntry(1))
+
+              result.success = true
+
+              tre_vec = Vector[*obj.getVectorDifferenceBetweenChannels(ref_ch, corr_ch).toArray] - corr
+
+              tre_vec = tre_vec.map2(@pixel_to_distance_conversions) { |e1, e2| e1*e2 }
+
+              result.tre = tre_vec.norm
+
+              result.tre_xy = Math.hypot(tre_vec[0], tre_vec[1])
+
+            rescue UnableToCorrectError => e
+
+              result.success = false
+
+            end
+
+            mut.synchronize do
+
+              results << result
+
+            end
+
+            result
+            
+          end
+
+        end
+
+      end
+
+      tq.shutdown
+
+      until tq.isTerminated do
+
+        sleep 0.4
+
+      end
+
+      tre_values = results
+
+      tre_values.select! { |e| e.success }
+
+      tre_3d = Math.mean(tre_values) { |e| e.tre }
+      
+      tre_2d = Math.mean(tre_values) { |e| e.tre_xy }
+
+      #TODO logging
+
+      puts "TRE: #{tre_3d}"
+      puts "X-Y TRE: #{tre_2d}"
+
+      tre_3d
+
+    end
+
+  end
+
+end
+