biointerchange 1.0.0 → 1.0.1

data/lib/biointerchange/core.rb

@@ -7,15 +7,30 @@ module BioInterchange
 
   ### Global behaviour settings, which can be altered programmatically or via the CLI:
 
-  # If true, then RDF::Graph's "insert" function will be overwritten so that it
-  # immediately outputs N-Triples. This reduces memory requirements (since no RDF
-  # graph is kept in memory) and performance (since no looping through an RDF graph
-  # is necessary).
-  @@skip_rdf_graph = true
-  def self.skip_rdf_graph
-    @@skip_rdf_graph
+  # If true, then RDF::Graph's & co will be used. Should only be applied for
+  # performance comparisons between the "standard" Ruby gem implementation and
+  # BioInterchange's optimized RDF handling.
+  @@evaluation = false
+  def self.evaluation
+    @@evaluation
   end
 
+  # BioInterchange can output RDF in two formats: Turtle (default) and N-Triples.
+  # The two corresponding Ruby constants for these two output formats are:
+  #   Turtle:    `:turtle`
+  #   N-Triples: `:ntriples`
+  @@format = :turtle
+  def self.format
+    @@format
+  end
+
+  # Default URI prefix that is used when RDFizing data:
+  @@default_uri_prefix = ''
+
+  # If input/rdf options permit batching, but no batchsize has been provided by
+  # the user, then use this default batch size.
+  @@default_batch_size = 100
+
   # Custom Exceptions and Errors
   require 'biointerchange/exceptions'
 
@@ -23,6 +38,7 @@ module BioInterchange
   require 'biointerchange/cdao'
   require 'biointerchange/faldo'
   require 'biointerchange/gff3o'
+  require 'biointerchange/gfvo'
   require 'biointerchange/goxref'
   require 'biointerchange/gvf1o'
   require 'biointerchange/sio'
@@ -61,6 +77,9 @@ module BioInterchange
 
   ### GFF3 ###
 
+  # Helper class for dealing with genomic locations
+  require 'biointerchange/genomics/locations'
+
   # Reader
   require 'biointerchange/genomics/gff3_reader'
 
@@ -68,6 +87,7 @@ module BioInterchange
   require 'biointerchange/genomics/gff3_pragmas'
   require 'biointerchange/genomics/gff3_feature_set'
   require 'biointerchange/genomics/gff3_feature'
+  require 'biointerchange/genomics/gff3_feature_sequence.rb'
 
   # Writer
   require 'biointerchange/genomics/gff3_rdf_ntriples'
@@ -107,21 +127,28 @@ module BioInterchange
 
   def self.cli
     begin
-      opt = Getopt::Long.getopts(
+      opts = [
         ["--help", "-h", Getopt::BOOLEAN],
         ["--debug", "-d", Getopt::BOOLEAN],                     # set debug mode => print stack traces
-        ["--no_rdf_graph_optimization", "-n", Getopt::BOOLEAN], # set self.skip_rdf_graph to false
         ["--batchsize", "-b", Getopt::OPTIONAL],                # batchsize for readers/writers that support +postpone?+
+        ["--ntriples", "-n", Getopt::BOOLEAN],                  # produce N-Triples instead of Turtle
+        ["--evaluation", "-z", Getopt::BOOLEAN],                # use RDF gem implementation for mem/speed comparison
+        ["--uri", "-u", Getopt::OPTIONAL],                      # URI prefix to use when serializing RDF
         ["--input", "-i", Getopt::REQUIRED],                    # input file format
         ["--rdf", "-r", Getopt::REQUIRED],                      # output file format
-        ["--annotate_name", Getopt::OPTIONAL],                  # name of resource/tool/person
-        ["--annotate_name_id", Getopt::OPTIONAL],               # uri of resource/tool/person
-        ["--annotate_date", Getopt::OPTIONAL],                  # date of processing/annotation
-        ["--annotate_version", Getopt::OPTIONAL],               # version number of resource
         ["--file", "-f", Getopt::OPTIONAL],                     # file to read, will read from STDIN if not supplied
         ["--out", "-o", Getopt::OPTIONAL],                      # output file, will out to STDOUT if not supplied
         ["--version", "-v", Getopt::BOOLEAN]                    # output the version number of the gem and exit
-      )
+      ]
+      reader_writer_pairs = Registry.reader_writer_pairs
+      reader_writer_pairs.each_index { |reader_writer_pair_index|
+        reader_id, writer_id = reader_writer_pairs[reader_writer_pair_index]
+        Registry.options_help(reader_id).each { |option_description|
+          option, description = option_description
+          opts |= [ [ "--annotate_#{option.sub(/\s.*$/, '')}", Getopt::OPTIONAL ] ]
+        }
+      }
+      opt = Getopt::Long.getopts(*opts)
       
       if opt['help'] or not (opt['input'] and opt['rdf'] or opt['version']) then
         puts "Usage: ruby #{$0} -i <format> -r <format> [options]"
@@ -137,18 +164,23 @@ module BioInterchange
         }
         puts ''
         puts 'I/O options:'
+        puts '  -f <file> / --file <file>          : file to read; STDIN used if not supplied'
+        puts '  -o <file> / --out <file>           : output file; STDOUT used if not supplied'
+        puts '  -n / --ntriples                    : output RDF N-Triples (instead of RDF Turtle)'
+        puts '  -u <uri> / --uri <prefix>          : URI prefix to use'
+        puts "                                       (default: #{@@default_uri_prefix})"
         puts '  -b <size>/--batchsize <size>       : process input in batches of the given size'
-        puts '                                      (if supported, see below for valid input/rdf pairs)'
-        puts '  -f <file>/--file <file>            : file to read; STDIN used if not supplied'
-        puts '  -o <file>/--out <file>             : output file; STDOUT used if not supplied'
+        puts '                                      (if supported, see below for valid input/rdf pairs;'
+        puts "                                       if supported, but not set, default value is #{@@default_batch_size})"
         puts ''
         puts 'Other options:'
         puts '  -v / --version                     : print the Gem\'s version number and exit'
         puts '  -d / --debug                       : turn on debugging output (for stacktraces)'
+        puts '  -z / --evaluation                  : use \'RDF\' gem implementation (slow & memory intensive,'
+        puts '                                       only included for performance evaluation comparisons)'
         puts '  -h  --help                         : this message'
         puts ''
-        puts 'Input-/RDF-format specific options:'
-        reader_writer_pairs = Registry.reader_writer_pairs
+        puts 'Input-/output-format specific options:'
         reader_writer_pairs.each_index { |reader_writer_pair_index|
           reader_id, writer_id = reader_writer_pairs[reader_writer_pair_index]
           puts "  Input format  : #{reader_id}"
@@ -171,14 +203,21 @@ module BioInterchange
 
       # Turn off optimization, if requested. This will generate an RDF graph in memory and
       # at least double memory requirements and runtime.
-      @@skip_rdf_graph = false if opt['no_rdf_graph_optimization']
+      @@evaluation = true if opt['evaluation']
+
+      # Switch to N-Triples output:
+      @@format = :ntriples if opt['ntriples']
 
       # Check if the input/rdf options are supported:
       unsupported_combination unless Registry.is_supported?(opt['input'], opt['rdf'])
       
+      # If a batchsize is given, then use it. Otherwise, check if the input/rdf combination
+      # supports batching and set a default batch value.
       if opt['batchsize'] then
         batching_not_supported unless Registry.is_supporting_batch_processing?(opt['input'], opt['rdf'])
         wrong_type('batchsize', 'a positive integer') unless opt['batchsize'].match(/^[1-9][0-9]*$/)
+      elsif Registry.is_supporting_batch_processing?(opt['input'], opt['rdf']) then
+        opt['batchsize'] = @@default_batch_size
       end
 
       # Create a parameter map that can be passed along to Reader implementations:
@@ -214,9 +253,12 @@ module BioInterchange
       
       begin
         model = reader.deserialize(input_source)
-        writer.serialize(model)
+        writer.serialize(model, opt['uri'])
       end while reader.postponed?
 
+    rescue Interrupt
+      # The user hit Ctrl-C, which is okay and does not need error reporting.
+      exit 0
     rescue ArgumentError => e
       $stderr.puts e.message
       $stderr.puts e.backtrace if opt['debug']
@@ -259,10 +301,6 @@ module BioInterchange
 
 private
 
-  def self.batching_not_supported
-    raise ArgumentError, 'Batching is not supported for this input/output format combination.'
-  end
-
   def self.unsupported_combination
     raise ArgumentError, 'This input/output format combination is not supported.'
   end
@@ -273,36 +311,3 @@ private
 
 end
 
-# Overwrite RDF::Graph implementation, in case we do not want to keep
-# the complete graph in memory. If the implementing writer does not
-# set an output stream via +fast_ostream+, then fall back to the original
-# implementation.
-module RDF
-
-class Graph
-  # DO NOT keep old insert implementation due to infinite recursion caused by module loading dependencies!
-  # alias_method :graph_building_insert, :insert
-
-  # Set an output stream for writing in +insert+.
-  #
-  # +ostream+:: Output stream that is populated by +insert+, if optimization can be carried out.
-  def fast_ostream(ostream)
-    @ostream = ostream
-  end
-
-  # Alternative implementation to +insert+, which can immediately output N-Triples instead
-  # of building an in-memory graph first.
-  #
-  # +statement+:: RDF statement that should be serialized.
-  def insert(statement)
-    if BioInterchange::skip_rdf_graph and @ostream then
-      @ostream.puts(statement.to_ntriples)
-    else
-      insert_statement(statement)
-    end
-  end
-
-end
-
-end
-

data/lib/biointerchange/faldo.rb

@@ -3,7 +3,43 @@ module BioInterchange
 
 class FALDO
 
-  # This denotes that a feature is in between two other positions that are both known exactly and next to eaxh other. An example is an restriction enzyme cutting site. The cut is after one nucleotide and before the next i.e. in between
+  # Used to describe a location that consists out of a number of Regions but where the order is not known. e.g. the odly named order keyword in a INSDC fle.
+  # (http://biohackathon.org/resource/faldo#BagOfRegions)
+  def self.BagOfRegions
+    return RDF::URI.new('http://biohackathon.org/resource/faldo#BagOfRegions')
+  end
+
+  # Sometimes a location of a feature is defined by a collection of regions e.g. INSDC join and order. One should always try to model the semantics more accuratly these are fallback options to encode legacy data.
+  # (http://biohackathon.org/resource/faldo#CollectionOfRegions)
+  def self.CollectionOfRegions
+    return RDF::URI.new('http://biohackathon.org/resource/faldo#CollectionOfRegions')
+  end
+
+  # The position is on the forward (positive, 5' to 3') strand. Shown as a '+' in GFF3 and GTF.
+  # (http://biohackathon.org/resource/faldo#ForwardStrandPosition)
+  def self.Positive_strand
+    return RDF::URI.new('http://biohackathon.org/resource/faldo#ForwardStrandPosition')
+  end
+
+  # Part of the coordinate system denoting on which strand the feature can be found. If you do not yet know which stand the feature is on, you should tag the position with just this class. If you know more you should use one of the subclasses. This means a region descibred with a '.' in GFF3. A GFF3 unstranded position does not have this type in FALDO -- those are just a 'position'.
+  # (http://biohackathon.org/resource/faldo#StrandedPosition)
+  def self.Stranded_position
+    return RDF::URI.new('http://biohackathon.org/resource/faldo#StrandedPosition')
+  end
+
+  # The 'both strands position' means that the region spans both strands instead of one. In GFF3 displayed as 0. This does not mean that the position is one or the other strand, but that is best described as being on both.
+  # (http://biohackathon.org/resource/faldo#BothStrandsPosition)
+  def self.Both_strands
+    return RDF::URI.new('http://biohackathon.org/resource/faldo#BothStrandsPosition')
+  end
+
+  # The position is on the reverse (complement, 3' to 5') strand of the sequence. Shown as '-' in GTF and GFF3.
+  # (http://biohackathon.org/resource/faldo#ReverseStrandPosition)
+  def self.Negative_strand
+    return RDF::URI.new('http://biohackathon.org/resource/faldo#ReverseStrandPosition')
+  end
+
+  # This denotes that a feature is in between two other positions that are both known exactly and next to each other. An example is a restriction enzyme cutting site. The cut is after one nucleotide position and before another nucleotide position (hence, in between).
   # (http://biohackathon.org/resource/faldo#InBetweenPosition)
   def self.In_between_positions
     return RDF::URI.new('http://biohackathon.org/resource/faldo#InBetweenPosition')
@@ -21,58 +57,100 @@ class FALDO
     return RDF::URI.new('http://biohackathon.org/resource/faldo#ExactPosition')
   end
 
-  # The position must be one of the more detailed Positions listed by the location predicate.
+  # This used to indicate that the feature is found before the exact position. Use to indicate, for example, a cleavage site. The cleavage happens between two amino acids before one and after the other.
+  # (http://biohackathon.org/resource/faldo#before)
+  def self.before
+    return RDF::URI.new('http://biohackathon.org/resource/faldo#before')
+  end
+
+  # This predicate is used when you want to describe a non-inclusive range. Only used in the in between position to say it is after a nucleotide, but before the next one.
+  # (http://biohackathon.org/resource/faldo#after)
+  def self.after
+    return RDF::URI.new('http://biohackathon.org/resource/faldo#after')
+  end
+
+  # The position must be one of the more detailed positions listed by the location predicate.
   # (http://biohackathon.org/resource/faldo#OneOfPosition)
   def self.One_of_positions
     return RDF::URI.new('http://biohackathon.org/resource/faldo#OneOfPosition')
   end
 
-  # Use when you have an idea of the range in which you can find the position but can not be sure.
+  # Use when you have an idea of the range in which you can find the position, but you cannot be sure about the exact position.
   # (http://biohackathon.org/resource/faldo#InRangePosition)
   def self.Indeterminate_position_within_a_range
     return RDF::URI.new('http://biohackathon.org/resource/faldo#InRangePosition')
   end
 
-  # Part of the coordinate system is on which strand the feature can be found. If you do not yet know which stand the feature is on you should tag the position with just this class. If you know more you should use one of the subclasses. This means a region descibred with a '.' in GFF3. An GFF3 Unstranded position does not have this type in FALDO those are just a Position.
-  # (http://biohackathon.org/resource/faldo#StrandedPosition)
-  def self.Stranded_position
-    return RDF::URI.new('http://biohackathon.org/resource/faldo#StrandedPosition')
-  end
-
   # Use this class to indicate that you lack exact position data.
   # (http://biohackathon.org/resource/faldo#FuzzyPosition)
   def self.Fuzzy_position
     return RDF::URI.new('http://biohackathon.org/resource/faldo#FuzzyPosition')
   end
 
-  # The position is on the forward (positive) strand. Shown as a '+' in GFF3 and GTF
-  # (http://biohackathon.org/resource/faldo#ForwardStrandPosition)
-  def self.Positive_strand
-    return RDF::URI.new('http://biohackathon.org/resource/faldo#ForwardStrandPosition')
+  # The inclusive begin position of a position. Also known as start.
+  # (http://biohackathon.org/resource/faldo#begin)
+  def self.begin
+    return RDF::URI.new('http://biohackathon.org/resource/faldo#begin')
   end
 
-  # The both strands position mean that the region spans both strands instead of one. In GGF3 displayed as 0. This does not mean that the position is one or the other strand but is best described as being on both.
-  # (http://biohackathon.org/resource/faldo#BothStrandsPosition)
-  def self.Both_strands
-    return RDF::URI.new('http://biohackathon.org/resource/faldo#BothStrandsPosition')
+  # The inclusive end of the position.
+  # (http://biohackathon.org/resource/faldo#end)
+  def self.end
+    return RDF::URI.new('http://biohackathon.org/resource/faldo#end')
   end
 
-  # The position is on the reverse (complement) strand of the sequence. Shown as '-' in GTF and GFF3
-  # (http://biohackathon.org/resource/faldo#ReverseStrandPosition)
-  def self.Negative_strand
-    return RDF::URI.new('http://biohackathon.org/resource/faldo#ReverseStrandPosition')
-  end
-
-  # A region describes an length of sequence with a start and end position that represents a feature on a Sequence. i.e. a gene
+  # A region describes a length of sequence -- with a start position and end position -- that represents a feature on a Sequence. i.e. a gene
   # (http://biohackathon.org/resource/faldo#Region)
   def self.Region
     return RDF::URI.new('http://biohackathon.org/resource/faldo#Region')
   end
 
+  # A position on the first amino acid or nucleotide of a sequence has the value 1, i.e. Python style array indexing as opposed to Java/C indexes.
+  # (http://biohackathon.org/resource/faldo#position)
+  def self.position
+    return RDF::URI.new('http://biohackathon.org/resource/faldo#position')
+  end
+
+  # The reference is the resource that determines where the position value offsets into. For example, it points to a contig or a genome assembly.
+  # (http://biohackathon.org/resource/faldo#reference)
+  def self.reference
+    return RDF::URI.new('http://biohackathon.org/resource/faldo#reference')
+  end
+
+  # As an ordered list of regions (but the list might not be complete)
+  # (http://biohackathon.org/resource/faldo#ListOfRegions)
+  def self.ListOfRegions
+    return RDF::URI.new('http://biohackathon.org/resource/faldo#ListOfRegions')
+  end
+
+  # This is the link between the concept whose location you are annotating the and its range or position. For example, when annotating the region that describes an exon, the exon would be the subject and the region would be the object of the triple or: 'active site' 'location' [is] 'position 3'.
+  # (http://biohackathon.org/resource/faldo#location)
+  def self.location
+    return RDF::URI.new('http://biohackathon.org/resource/faldo#location')
+  end
+
   # Determines whether the given URI is an object property.
   #
   # +uri+:: URI that is tested for being an object property
   def self.is_object_property?(uri)
+    if uri == RDF::URI.new('http://biohackathon.org/resource/faldo#before') then
+      return true
+    end
+    if uri == RDF::URI.new('http://biohackathon.org/resource/faldo#after') then
+      return true
+    end
+    if uri == RDF::URI.new('http://biohackathon.org/resource/faldo#begin') then
+      return true
+    end
+    if uri == RDF::URI.new('http://biohackathon.org/resource/faldo#end') then
+      return true
+    end
+    if uri == RDF::URI.new('http://biohackathon.org/resource/faldo#reference') then
+      return true
+    end
+    if uri == RDF::URI.new('http://biohackathon.org/resource/faldo#location') then
+      return true
+    end
     return false
   end
 
@@ -80,6 +158,9 @@ class FALDO
   #
   # +uri+:: URI that is tested for being a datatype property
   def self.is_datatype_property?(uri)
+    if uri == RDF::URI.new('http://biohackathon.org/resource/faldo#position') then
+      return true
+    end
     return false
   end
 
@@ -87,39 +168,48 @@ class FALDO
   #
   # +uri+:: URI that is tested for being a class
   def self.is_class?(uri)
-    if uri == RDF::URI.new('http://biohackathon.org/resource/faldo#InBetweenPosition') then
+    if uri == RDF::URI.new('http://biohackathon.org/resource/faldo#BagOfRegions') then
       return true
     end
-    if uri == RDF::URI.new('http://biohackathon.org/resource/faldo#Position') then
+    if uri == RDF::URI.new('http://biohackathon.org/resource/faldo#CollectionOfRegions') then
       return true
     end
-    if uri == RDF::URI.new('http://biohackathon.org/resource/faldo#ExactPosition') then
+    if uri == RDF::URI.new('http://biohackathon.org/resource/faldo#ForwardStrandPosition') then
       return true
     end
-    if uri == RDF::URI.new('http://biohackathon.org/resource/faldo#OneOfPosition') then
+    if uri == RDF::URI.new('http://biohackathon.org/resource/faldo#StrandedPosition') then
       return true
     end
-    if uri == RDF::URI.new('http://biohackathon.org/resource/faldo#InRangePosition') then
+    if uri == RDF::URI.new('http://biohackathon.org/resource/faldo#BothStrandsPosition') then
       return true
     end
-    if uri == RDF::URI.new('http://biohackathon.org/resource/faldo#StrandedPosition') then
+    if uri == RDF::URI.new('http://biohackathon.org/resource/faldo#ReverseStrandPosition') then
       return true
     end
-    if uri == RDF::URI.new('http://biohackathon.org/resource/faldo#FuzzyPosition') then
+    if uri == RDF::URI.new('http://biohackathon.org/resource/faldo#InBetweenPosition') then
       return true
     end
-    if uri == RDF::URI.new('http://biohackathon.org/resource/faldo#ForwardStrandPosition') then
+    if uri == RDF::URI.new('http://biohackathon.org/resource/faldo#Position') then
       return true
     end
-    if uri == RDF::URI.new('http://biohackathon.org/resource/faldo#BothStrandsPosition') then
+    if uri == RDF::URI.new('http://biohackathon.org/resource/faldo#ExactPosition') then
       return true
     end
-    if uri == RDF::URI.new('http://biohackathon.org/resource/faldo#ReverseStrandPosition') then
+    if uri == RDF::URI.new('http://biohackathon.org/resource/faldo#OneOfPosition') then
+      return true
+    end
+    if uri == RDF::URI.new('http://biohackathon.org/resource/faldo#InRangePosition') then
+      return true
+    end
+    if uri == RDF::URI.new('http://biohackathon.org/resource/faldo#FuzzyPosition') then
       return true
     end
     if uri == RDF::URI.new('http://biohackathon.org/resource/faldo#Region') then
       return true
     end
+    if uri == RDF::URI.new('http://biohackathon.org/resource/faldo#ListOfRegions') then
+      return true
+    end
     return false
   end
 
@@ -153,7 +243,7 @@ class FALDO
   end
 
 private
-  @@parent_properties = { RDF::URI.new('http://biohackathon.org/resource/faldo#OneOfPosition') => RDF::URI.new('http://biohackathon.org/resource/faldo#FuzzyPosition') , RDF::URI.new('http://biohackathon.org/resource/faldo#StrandedPosition') => RDF::URI.new('http://biohackathon.org/resource/faldo#Position') , RDF::URI.new('http://biohackathon.org/resource/faldo#FuzzyPosition') => RDF::URI.new('http://biohackathon.org/resource/faldo#Position') , RDF::URI.new('http://biohackathon.org/resource/faldo#ForwardStrandPosition') => RDF::URI.new('http://biohackathon.org/resource/faldo#StrandedPosition') , RDF::URI.new('http://biohackathon.org/resource/faldo#BothStrandsPosition') => RDF::URI.new('http://biohackathon.org/resource/faldo#StrandedPosition') , RDF::URI.new('http://biohackathon.org/resource/faldo#ReverseStrandPosition') => RDF::URI.new('http://biohackathon.org/resource/faldo#StrandedPosition') }
+  @@parent_properties = { RDF::URI.new('http://biohackathon.org/resource/faldo#BagOfRegions') => RDF::URI.new('http://biohackathon.org/resource/faldo#CollectionOfRegions') , RDF::URI.new('http://biohackathon.org/resource/faldo#ForwardStrandPosition') => RDF::URI.new('http://biohackathon.org/resource/faldo#StrandedPosition') , RDF::URI.new('http://biohackathon.org/resource/faldo#StrandedPosition') => RDF::URI.new('http://biohackathon.org/resource/faldo#Position') , RDF::URI.new('http://biohackathon.org/resource/faldo#BothStrandsPosition') => RDF::URI.new('http://biohackathon.org/resource/faldo#StrandedPosition') , RDF::URI.new('http://biohackathon.org/resource/faldo#ReverseStrandPosition') => RDF::URI.new('http://biohackathon.org/resource/faldo#StrandedPosition') , RDF::URI.new('http://biohackathon.org/resource/faldo#OneOfPosition') => RDF::URI.new('http://biohackathon.org/resource/faldo#FuzzyPosition') , RDF::URI.new('http://biohackathon.org/resource/faldo#FuzzyPosition') => RDF::URI.new('http://biohackathon.org/resource/faldo#Position') , RDF::URI.new('http://biohackathon.org/resource/faldo#ListOfRegions') => RDF::URI.new('http://biohackathon.org/resource/faldo#CollectionOfRegions') }
 
 end