cicada 0.9.0-java

data/lib/cicada/file_interaction.rb

@@ -0,0 +1,377 @@
+#--
+# /* ***** 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 'ostruct'
+require 'base64'
+require 'rexml/document'
+
+require 'rimageanalysistools'
+require 'rimageanalysistools/get_image'
+
+module Cicada
+
+  ##
+  # Handles the serialization of the ImageObjects for storing them in a file.
+  #
+  # The serialized output will consist of an XML file describing the objects
+  # in human-readable form and including a binary data sectiobn containing the
+  # serialized object.  This binary section is the only thing read back in, so
+  # changing the XML human-readable portion of the file manually will not affect
+  # the data read back in.
+  #
+  class Serialization
+    
+    ##
+    # Converts an array of ImageObjects to an XML-formatted string containing
+    # the serialized data.
+    #
+    # @param [Enumerable<ImageObject>] image_objects an Enumerable list of image objects
+    #
+    # @return [String] a string containing formatted XML and binary representations of the 
+    #  image objects.
+    #
+    def self.serialize_image_objects(image_objects)
+
+      doc = REXML::Document.new
+
+
+      doc.add_element "root"
+
+      image_objects.each do |iobj|
+
+        in_doc = REXML::Document.new iobj.writeToXMLString
+
+        in_doc.root.elements[1, "serialized_form"].text = Base64.encode64(Marshal.dump(iobj))
+
+        doc.root.add in_doc.elements[1,"image_object"]
+
+      end
+
+      output = ""
+
+      doc.write(output, 2)
+
+      output
+
+    end
+
+    ##
+    # Restores an image object from a byte string.
+    #
+    # @param [String] bin_data the bytes representing the image object.  This should be 
+    #  a standard byte string.  The XML files use base64 encoding, and the data should already
+    #  be unencoded.
+    #
+    # @return [ImageObject] the encoded ImageObject
+    #
+    def self.image_object_from_bytes(bin_data)
+
+      Marshal.load(bin_data)
+
+      #j_bytes = bin_data.to_java_bytes
+
+      #oi = Java::java.io.ObjectInputStream.new(Java::java.io.ByteArrayInputStream.new(j_bytes))
+
+      #oi.readObject
+
+    end
+
+    ##
+    # Restores image objects from an XML string containing their serialized representation.
+    # (This uses the base64 encoded binary information in the XML file, not the human readable portion.)
+    #
+    # @param [String] data the XML string
+    #
+    # @return [Array<ImageObject>] the image objects encoded in the string
+    #
+    def self.unserialize_image_objects(data)
+
+      objs = []
+
+      doc = REXML::Document.new data
+
+      doc.elements.each("*/image_object/serialized_form") do |el|
+
+        bin_data = Base64.decode64(el.text)
+
+        objs << image_object_from_bytes(bin_data)
+
+      end
+
+      objs
+
+    end
+
+  end
+
+
+  ##
+  # A collection of methods for interacting with input and output files for cicada.
+  # 
+  class FileInteraction
+
+    # parameters required by the methods in this class
+    REQUIRED_PARAMETERS = [:dirname_set, :basename_set, :mask_relative_dirname, :mask_extra_extension, :data_directory, :correction_date, :output_positions_to_directory]
+
+    # parmeters used but not required in this class or only required for optional functionality
+    OPTIONAL_PARAMETERS = [:in_situ_aberr_corr_basename_set]
+
+    # extension on position data (image object) files.
+    POS_XML_EXTENSION = "_position_data.xml"
+
+    # extension on the correction files
+    CORR_XML_EXTENSION = "_correction.xml"
+
+    # extension on the distance measurement files
+    DIFFS_TXT_EXTENSION = "_diffs.txt"
+
+    # separator used in the parameter file for multiple files, directories, etc.
+    MULTI_NAME_SEP = ","
+
+
+    ##
+    # Loads an image from the specified file.
+    #
+    # @param [String] image_fn the image's filename
+    #
+    # @return [ReadOnlyImage] the image at the specified filename
+    #
+    def self.load_image(image_fn)
+
+      RImageAnalysisTools.get_image(image_fn)
+
+    end
+
+
+    ##
+    # Gets the filename to which / from which image object positions will be written / 
+    # read from a parameter dictionary.
+    # @param [ParameterDictionary, Hash] p a hash-like object specifying the filename for the positions.
+    #
+    # @return [String] the absolute path to the position file.
+    #
+    def self.position_data_filename(p)
+      dir = p[:data_directory]
+      File.expand_path(p[:basename_set].split(MULTI_NAME_SEP)[0] + POS_XML_EXTENSION, dir)
+    end
+
+    ##
+    # Gets the filename of data to use for in situ correction from a parameter dictionary.
+    #
+    # @param [ParameterDictionary, Hash] p a hash-like object specifying the filename for the
+    #  in situ correction data
+    #
+    # @return [String] the absolute path to the in situ correction data file
+    #
+    def self.in_situ_corr_data_filename(p)
+      dir = [:data_directory]
+      File.expand_path(p[:in_situ_aberr_corr_basename_set].split(MULTI_NAME_SEP)[0] + POS_XML_EXTENSION, dir)
+    end
+
+    ##
+    # Checks if the position data file already exists.
+    # 
+    # @param [ParameterDictionary, Hash] p a hash-like object specifying the filename for the positions.
+    #
+    # @return [Boolean] whether the position data file exists.
+    #
+    def self.position_file_exists?(p)
+      File.exist?(FileInteraction.position_data_filename(p))
+    end
+
+    ##
+    # Unserializes image object position data from a specified file using the methods in the Serialization
+    #  class.
+    #
+    # @param [String] fn the name of the data file.
+    #
+    # @return [Array<ImageObject>] the image objects contained in the file.
+    #
+    def self.unserialize_position_data_file(fn)
+
+      data_str = nil
+
+      File.open(fn) do |f|
+        data_str = f.read
+      end
+
+      Serialization.unserialize_image_objects(data_str)
+
+    end
+
+    ##
+    # Reads the image objects associated with an analysis specified by a parameter dictionary.
+    #
+    # @param [ParameterDictionary, Hash] p a hash-like object specifying the filename for the positions.
+    #
+    # @return [Array<ImageObject>] the image objects associated with the analysis
+    #
+    def self.read_position_data(p)
+      
+      fn = FileInteraction.position_data_filename(p)
+
+      FileInteraction.unserialize_position_data_file(fn)
+
+    end
+
+    ##
+    # Reads the image objects for in situ correction associated with an analysis specified by
+    #  a parameter dictionary.
+    #
+    # @param [ParameterDictionary, Hash] p a hash-like object specifying the filename for the
+    #  in situ correction data
+    #
+    # @return [Array<ImageObject>] the image objects for in situ correction associated with the analysis
+    #
+    def self.read_in_situ_corr_data(p)
+
+      fn = FileInteraction.in_situ_corr_data_filename(p)
+
+      FileInteraction.unserialize_position_data_file(fn)
+
+    end
+
+    ##
+    # Lists all the files and masks to be analyzed given a parameter dictionary.
+    #
+    # @param [ParameterDictionary, Hash] p a hash-like object specifying the analysis
+    #
+    # @return [Array<OpenStruct>] an array of objects that respond to #image_fn and #mask_fn, 
+    #  which return each image's filename and its paired mask's filename respectively.
+    #
+    def self.list_files(p)
+
+      dirnames = p[:dirname_set].split(MULTI_NAME_SEP)
+      basenames = p[:basename_set].split(MULTI_NAME_SEP)
+
+      image_sets = []
+
+      dirnames.each do |d|
+
+        mask_dirname = File.join(d, p[:mask_relative_dirname])
+
+        Dir.foreach(d) do |f|
+
+          if basenames.any? { |e| f.match(e) } then
+            
+            im = File.expand_path(f, d)
+            msk = File.expand_path(f + p[:mask_extra_extension], mask_dirname)
+
+            current = OpenStruct.new(image_fn: im, mask_fn: msk)
+            
+            image_sets << current
+
+          end          
+
+        end
+
+      end
+      
+      image_sets
+
+    end
+
+    ##
+    # Writes the provided image objects to file to the location specified in a parameter dictionary.
+    #
+    # @param [Enumerable<ImageObject>] image_objects the objects that will be written to file. 
+    # @param [ParameterDictionary, Hash] p a hash-like object specifying the filename for the data.
+    # 
+    # @return [void]
+    #
+    def self.write_position_data(image_objects, p)
+
+      fn = position_data_filename(p)
+      
+      write_position_data_file(image_objects,fn)
+
+    end
+
+    ##
+    # Writes the provided image objects to file to the location specified.
+    #
+    # @param [Enumerable<ImageObject>] image_objects the objects that will be written to file. 
+    # @param [String] fn the filename of the file to which to write the data
+    # 
+    # @return [void]
+    #
+    def self.write_position_data_file(image_objects, fn)
+
+      File.open(fn, 'w') do |f|
+
+        f.write(Serialization.serialize_image_objects(image_objects))
+
+      end
+
+    end
+
+    ##
+    # Gets the filename for storing/reading the correction based upon the supplied parameter dictionary.
+    #
+    # @param [ParameterDictionary, Hash] p a hash-like object specifying the correction file location.
+    #
+    # @return [String] the filename for the correction file.
+    #
+    def self.correction_filename(p)
+
+      dir = p[:data_directory]
+      fn = p[:correction_date]
+
+      File.expand_path(fn + CORR_XML_EXTENSION, dir)
+
+    end
+
+    ##
+    # Writes an array of distance measurements to file based upon the supplied parameter dictionary.
+    # 
+    # @param [Enumerable<#to_s>] diffs an enumerable list of distance meaurements.
+    # @param [ParameterDictionary, hash] p a hash-like object specifying the file location.
+    #
+    # @return [void]
+    #
+    def self.write_differences(diffs, p)
+
+      dirname = p[:output_positions_to_directory]
+      
+      fn = File.expand_path(p[:basename_set] + DIFFS_TXT_EXTENSION, dirname)
+
+      File.open(fn, 'w') do |f|
+
+        diffs.each do |d|
+
+          f.puts(d.to_s)
+
+        end
+
+      end
+
+    end
+
+  end
+
+end
+
+

data/lib/cicada/fitting/p3d_fitter.rb

@@ -0,0 +1,235 @@
+# /* ***** 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 'rimageanalysistools'
+
+require 'facets/math/mean'
+require 'facets/math/std'
+
+module Cicada
+
+  ##
+  # Interface for a class that fits a set of scalars with associated image object
+  # to some distribution.
+  #
+  class DistributionFitter
+
+    attr_accessor :parameters
+
+    ##
+    # Constructs a new distribution fitter from specified parameters.  Derived
+    # classes should indicate which parameters are used.
+    #
+    # @param [ParameterDictionary, Hash] params a hash-like object containing the parameters
+    #
+    def initialize(params)
+
+      @parameters = params
+
+    end
+
+    ##
+    # Fits the data with associated image objects to the distribution.
+    #
+    # *Abstract*
+    #
+    # @param [Array<ImageObject>] objects the associated image objects
+    # @param [Array<Numeric>] diffs the scalar data being fit (in the same order
+    #  as the image objects)
+    #
+    # @return [Array<Numeric>] the fitted distribution parameters
+    #
+    def fit(objects, diffs)
+      nil
+    end
+    
+  end
+
+  ##
+  # An objective function that calculates the negative log likelihood of supplied data points
+  # being generated from a p3d distribution with specified parameters.
+  #
+  # The data points should be an array of (positive) scalars set using the attribute r.
+  #
+  #
+  class P3DObjectiveFunction
+
+    include Java::edu.stanford.cfuller.imageanalysistools.fitting.ObjectiveFunction
+
+    ##
+    # Constructs an empty P3DObjectiveFunction.
+    #
+    def initialize
+
+      @r = nil
+      @s = nil
+      @min_prob = nil
+      @use_min_prob = false
+      @should_fit_s = true
+
+    end
+
+    attr_accessor :r, :use_min_prob, :should_fit_s
+
+    attr_reader :s, :min_prob
+    
+    ##
+    # Sets a static value for the parameter that is the standard deviation of the generating
+    # Gaussian distribution.  Setting this parameter disables its fitting by the objective function.
+    #
+    # @param [Numeric] s_new the static value for the standard deviation parameter
+    #
+    # @return [void]
+    #
+    def s=(s_new)
+      @s = s_new
+      @should_fit_s = false
+    end
+
+    ##
+    # Sets a minimum probability cutoff for calculating the likelihood.  Could be used for various
+    # robust fitting approaches.
+    #
+    # @param [Numeric] min_prob the minimum allowed probability for any data point.  Probabilities
+    #  smaller than this value will be set to this value.
+    # 
+    # @return [void]
+    #
+    def min_prob=(min_prob)
+
+      @min_prob = min_prob
+      @use_min_prob = true
+
+    end
+
+    ##
+    # Calculates the probability density of the p3d distribution at a given point.
+    #
+    # @param [Numeric] r the distance at which to calculate the probability density
+    # @param [Numeric] m the mean-like parameter of the p3d distribution
+    # @param [Numeric] s the standard-deviation-like parameter of the p3d distribution
+    #
+    # @return [Float] the probability density at the given point
+    #
+    def p3d(r, m, s)
+
+      (Math.sqrt(2.0/Math::PI)*r/(2*m*s))*(Math.exp(-1 * (m-r)**2/(2*s**2)) - Math.exp( -1 * (m+r)**2/(2*s**2)))
+
+    end
+
+    ##
+    # Evaluates the negative log-likelihood of the data given the parameters specified.
+    #
+    # @param [Array<Numeric>] point a 2-element array containing the mean- and standard deviation-like
+    #  parameters.  If a static standard deviation parameter is being used, something should still be
+    #  provided here, but it will be ignored.
+    #
+    # @return [Float] the negative log-likelihood of the data.
+    #
+    def evaluate(point)
+
+      point = point.toArray unless point.is_a? Array
+
+      m = point[0]
+      s = point[1]
+      s = @s unless @should_fit_s
+
+      return Float::MAX if (m < 0 or s < 0)
+
+      r.reduce(0.0) do |sum, ri|
+
+        temp_neg_log_p = -1.0*Math.log( p3d(ri, m, s))
+
+        if (@use_min_prob and temp_neg_log_p > @min_prob) then
+          
+          sum + @min_prob
+
+        else
+
+          sum + temp_neg_log_p
+
+        end
+
+      end
+        
+    end
+
+  end
+  
+
+  ##
+  # A distribution fitter that fits data to a P3D distribution.
+  #
+  class P3DFitter < DistributionFitter
+
+    # parameters required by the methods in this class
+    REQUIRED_PARAMETERS =  []
+
+    # parmeters used but not required in this class or only required for optional functionality
+    OPTIONAL_PARAMETERS = [:robust_p3d_fit_cutoff]
+    
+
+    ##
+    # Fits the P3D mean- and standard-deviation-like parameters to the data.
+    #
+    # @param [Array<ImageObject>] objects the image objects whose distances are being fit
+    # @param [Array<Numeric>] diffs the distances being fit
+    #
+    # @return [Array] a two-element array containing the mean- and standard-deviation-like parameters.
+    #
+    def fit(objects, diffs)
+
+      of = P3DObjectiveFunction.new
+
+      of.r = diffs
+
+      tol = 1e-12
+
+      nmm = Java::edu.stanford.cfuller.imageanalysistools.fitting.NelderMeadMinimizer.new(tol)
+
+      initial_mean = Math.mean(diffs)
+
+      initial_width = Math.std(diffs)
+
+      starting_point = Java::org.apache.commons.math3.linear.ArrayRealVector.new(2, 0.0)
+
+      starting_point.setEntry(0, initial_mean)
+      starting_point.setEntry(1, initial_width)
+
+      if @parameters[:robust_p3d_fit_cutoff] then
+        
+        of.min_prob= @parmaeters[:robust_p3d_fit_cutoff].to_f
+
+      end
+
+      nmm.optimize(of, starting_point).toArray.to_a
+
+    end
+  
+  end
+
+end
+
+
+