unipept 0.7.1 → 0.8.0

data/lib/commands/unipept.rb

@@ -0,0 +1,226 @@
+require 'typhoeus'
+
+require_relative '../formatters'
+require_relative '../configuration'
+require_relative '../batch_order'
+require_relative '../batch_iterator'
+require_relative '../version'
+
+require_relative 'unipept/config'
+require_relative 'unipept/pept2lca'
+require_relative 'unipept/pept2prot'
+require_relative 'unipept/pept2taxa'
+require_relative 'unipept/taxa2lca'
+require_relative 'unipept/taxonomy'
+
+module Unipept
+  class Commands::Unipept
+    def initialize
+      @root_command = create_root_command
+      add_config_command
+      add_pept2taxa_command
+      add_pept2lca_command
+      add_taxa2lca_command
+      add_pept2prot_command
+      add_taxonomy_command
+    end
+
+    def run(args)
+      @root_command.run(args)
+    end
+
+    def create_root_command
+      Cri::Command.new_basic_root.modify do
+        name 'unipept'
+        summary 'Command line interface to Unipept web services.'
+        usage 'unipept subcommand [options]'
+        description <<-EOS
+        The unipept subcommands are command line wrappers around the Unipept web services.
+
+        Subcommands that start with pept expect a list of tryptic peptides as input. Subcommands that start with tax expect a list of NCBI Taxonomy Identifiers as input. Input is passed
+
+        - as separate command line arguments
+
+        - in a text file that is passed as an argument to the -i option
+
+        - to standard input
+
+        The command will give priority to the first way the input is passed, in the order as listed above. Text files and standard input should have one tryptic peptide or one NCBI Taxonomy Identifier per line.
+        EOS
+        flag :v, :version, 'displays the version'
+        flag :q, :quiet, 'disable service messages'
+        option :i, :input, 'read input from file', argument: :required
+        option :o, :output, 'write output to file', argument: :required
+        option :f, :format, "define the output format (available: #{Unipept::Formatter.available.join ', ' }) (default: #{Unipept::Formatter.default})", argument: :required
+
+        # Configuration options
+        option nil, 'host', 'specify the server running the Unipept web service', argument: :required
+
+        run do |opts, _args, cmd|
+          if opts[:version]
+            puts Unipept::VERSION
+          else
+            abort cmd.help
+          end
+        end
+      end
+    end
+
+    def add_config_command
+      @root_command.define_command('config') do
+        summary 'Set configuration options.'
+        usage 'config option [value]'
+        description <<-EOS
+        Sets or shows the value for configuration options. All settings are stored in the .unipeptrc file in the home directory of the user.
+
+        Running the command with a value will set that value for the given option, running it without will show the current value.
+
+        These options are currently supported:
+
+        - host: Set the default host for api calls.
+
+        Example: "unipept config host http://api.unipept.ugent.be" will set the default host to the public unipept server.
+        EOS
+
+        runner Commands::Config
+      end
+    end
+
+    def add_pept2taxa_command
+      @root_command.define_command('pept2taxa') do
+        usage 'pept2taxa [options]'
+        summary 'Fetch taxa of Uniprot records that match tryptic peptides.'
+        description <<-EOS
+        For each tryptic peptide the unipept pept2taxa command retrieves from Unipept the set of taxa from all Uniprot records whose protein sequence contains an exact matches to the tryptic peptide. The command expects a list of tryptic peptides that are passed
+
+        - as separate command line arguments
+
+        - in a text file that is passed as an argument to the -i option
+
+        - to standard input
+
+        The command will give priority to the first way tryptic peptides are passed, in the order as listed above. Text files and standard input should have one tryptic peptide per line.
+
+        The unipept pept2taxa subcommand yields NCBI Taxonomy records as output.
+        EOS
+
+        flag :e, :equate, 'equate isoleucine (I) and leucine (L) when matching peptides'
+        flag :a, :all, 'report all information fields of NCBI Taxonomy records available in Unipept. Note that this may have a performance penalty.'
+        option :s, :select, 'select the information fields to return. Selected fields are passed as a comma separated list of field names. Multiple -s (or --select) options may be used.', argument: :required, multiple: true
+
+        runner Commands::Pept2taxa
+      end
+    end
+
+    def add_pept2lca_command
+      @root_command.define_command('pept2lca') do
+        usage 'pept2lca [options]'
+        summary 'Fetch taxonomic lowest common ancestor of Uniprot records that match tryptic peptides.'
+        description <<-EOS
+        For each tryptic peptide the unipept pept2lca command retrieves from Unipept the lowest common ancestor of the set of taxa from all Uniprot records whose protein sequence contains an exact matches to the tryptic peptide. The lowest common ancestor is based on the topology of the Unipept Taxonomy -- a cleaned up version of the NCBI Taxonomy -- and is itself a record from the NCBI Taxonomy. The command expects a list of tryptic peptides that are passed
+
+         - as separate command line arguments
+
+         - in a text file that is passed as an argument to the -i option
+
+         - to standard input
+
+        The command will give priority to the first way tryptic peptides are passed, in the order as listed above. Text files and standard input should have one tryptic peptide per line.
+
+        The unipept pept2lca subcommand yields an NCBI Taxonomy record as output.
+        EOS
+
+        flag :e, :equate, 'equate isoleucine (I) and leucine (L) when matching peptides'
+        flag :a, :all, 'report all information fields of NCBI Taxonomy records available in Unipept. Note that this may have a performance penalty.'
+        option :s, :select, 'select the information fields to return. Selected fields are passed as a comma separated list of field names. Multiple -s (or --select) options may be used.', argument: :required, multiple: true
+
+        runner Commands::Pept2lca
+      end
+    end
+
+    def add_taxa2lca_command
+      @root_command.define_command('taxa2lca') do
+        usage 'taxa2lca [options]'
+        summary 'Compute taxonomic lowest common ancestor for given list of taxa.'
+        description <<-EOS
+        The unipept taxa2lca command computes the lowest common ancestor of a given list of NCBI Taxonomy Identifiers. The lowest common ancestor is based on the topology of the Unipept Taxonomy -- a cleaned up version of the NCBI Taxonomy -- and is itself a record from the NCBI Taxonomy. The command expects a list of NCBI Taxonomy Identifiers that are passed
+
+         - as separate command line arguments
+
+         - in a text file that is passed as an argument to the -i option
+
+         - to standard input
+
+        The command will give priority to the first way NCBI Taxonomy Identifiers are passed, in the order as listed above. Text files and standard input should have one NCBI Taxonomy Identifier per line.
+
+        The unipept taxonomy subcommand yields NCBI Taxonomy records as output.
+        EOS
+
+        flag :a, :all, 'report all information fields of NCBI Taxonomy records available in Unipept. Note that this may have a performance penalty.'
+        option :s, :select, 'select the information fields to return. Selected fields are passed as a comma separated list of field names. Multiple -s (or --select) options may be used.', argument: :required, multiple: true
+
+        runner Commands::Taxa2lca
+      end
+    end
+
+    def add_pept2prot_command
+      @root_command.define_command('pept2prot') do
+        usage 'pept2prot [options]'
+        summary 'Fetch Uniprot records that match tryptic peptides.'
+        description <<-EOS
+        For each tryptic peptide the unipept pept2prot command retrieves from Unipept all Uniprot records whose protein sequence contains an exact matches to the tryptic peptide. The command expects a list of tryptic peptides that are passed
+
+        - as separate command line arguments
+
+        - in a text file that is passed as an argument to the -i option
+
+        - to standard input
+
+        The command will give priority to the first way tryptic peptides are passed, in the order as listed above. Text files and standard input should have one tryptic peptide per line.
+
+        The unipept pept2prot subcommand yields Uniprot records as output.
+        EOS
+
+        flag :e, :equate, 'equate isoleucine (I) and leucine (L) when matching peptides'
+        flag :a, :all, 'report all information fields of Uniprot records available in Unipept. Note that this may have a performance penalty.'
+        option :s, :select, 'select the information fields to return. Selected fields are passed as a comma separated list of field names. Multiple -s (or --select) options may be used.', argument: :required, multiple: true
+
+        runner Commands::Pept2prot
+      end
+    end
+
+    def add_taxonomy_command
+      @root_command.define_command('taxonomy') do
+        usage 'taxonomy [options]'
+        summary 'Fetch taxonomic information from Unipept Taxonomy.'
+        description <<-EOS
+        The unipept taxonomy command yields information from the Unipept Taxonomy records for a given list of NCBI Taxonomy Identifiers. The Unipept Taxonomy is a cleaned up version of the NCBI Taxonomy, and its records are also records of the NCBI Taxonomy. The command expects a list of NCBI Taxonomy Identifiers that are passed
+
+        - as separate command line arguments
+
+        - in a text file that is passed as an argument to the -i option
+
+        - to standard input
+
+        The command will give priority to the first way NCBI Taxonomy Identifiers are passed, in the order as listed above. Text files and standard input should have one NCBI Taxonomy Identifier per line.
+
+        The unipept taxonomy subcommand yields NCBI Taxonomy records as output.
+        EOS
+
+        flag :a, :all, 'report all information fields of NCBI Taxonomy records available in Unipept. Note that this may have a performance penalty.'
+        option :s, :select, 'select the information fields to return. Selected fields are passed as a comma separated list of field names. Multiple -s (or --select) options may be used.', argument: :required, multiple: true
+
+        runner Commands::Taxonomy
+      end
+    end
+
+    # Invokes the unipept command-line tool with the given arguments.
+    #
+    # @param [Array<String>] args An array of command-line arguments
+    #
+    # @return [void]
+    def self.run(args)
+      new.run(args)
+    end
+  end
+end

data/lib/commands/uniprot.rb

@@ -0,0 +1,69 @@
+require 'typhoeus'
+
+module Unipept::Commands
+  class Uniprot
+    attr_reader :root_command
+    attr_reader :valid_formats
+
+    valid_formats = Set.new %w(fasta txt xml rdf gff sequence)
+    @root_command = Cri::Command.define do
+      name 'uniprot'
+      summary 'Command line interface to Uniprot web services.'
+      usage 'uniprot [options]'
+      description <<-EOS
+      The uniprot command is a command line wrapper around the Uniprot web services. The command expects a list of Uniprot Accession Numbers that are passed
+
+      - as separate command line arguments
+
+      - to standard input
+
+      The command will give priority to the first way Uniprot Accession Numbers are passed, in the order as listed above. The standard input should have one Uniprot Accession Number per line.
+
+      The uniprot command yields just the protein sequences as a default, but can return several formats.
+      EOS
+      required :f, :format, 'specify output format (available: ' + valid_formats.to_a.join(', ') + ') (default: sequence)'
+      flag :h, :help, 'show help for this command' do |_value, cmd|
+        puts cmd.help
+        exit 0
+      end
+      run do |opts, args, _cmd|
+        format = opts.fetch(:format, 'sequence')
+        unless valid_formats.include? format
+          $stderr.puts format + ' is not a valid output format. Available formats are: ' + valid_formats.to_a.join(', ')
+          exit 1
+        end
+        iterator = args.empty? ? $stdin.each_line : args
+        iterator.each do |accession|
+          puts Uniprot.get_uniprot_entry(accession.chomp, format)
+        end
+      end
+    end
+
+    # Invokes the uniprot command-line tool with the given arguments.
+    #
+    # @param [Array<String>] args An array of command-line arguments
+    #
+    # @return [void]
+    def self.run(args)
+      @root_command.run(args)
+    end
+
+    # Fetches a Uniprot record from the uniprot website with the given accession
+    # number in the requested format.
+    #
+    # @param [String] accession The accession number of the record to fetch
+    #
+    # @param [String] format The format of of the record. If the format is 'sequence', the sequence will be returned in as a single line
+    #
+    # @return [String] The requested Uniprot record in the requested format
+    def self.get_uniprot_entry(accession, format)
+      if format == 'sequence'
+        get_uniprot_entry(accession, 'fasta').lines.map(&:chomp)[1..-1].join('')
+      else
+        # other format has been specified, just download and output
+        resp = Typhoeus.get("http://www.uniprot.org/uniprot/#{accession}.#{format}")
+        resp.response_body if resp.success?
+      end
+    end
+  end
+end

data/lib/commands.rb

@@ -0,0 +1,10 @@
+require 'cri'
+
+module Unipept
+  module Commands
+    require_relative 'commands/peptfilter'
+    require_relative 'commands/prot2pept'
+    require_relative 'commands/uniprot'
+    require_relative 'commands/unipept'
+  end
+end

data/lib/configuration.rb

@@ -0,0 +1,45 @@
+require 'yaml'
+
+module Unipept
+  class Configuration
+    attr_reader :config
+    attr_reader :file_name
+
+    # Creates a new config object, based on a given YAML file. If no filename
+    # given, '.unipeptrc' in the home dir of the user will be used.
+    #
+    # If the file doesn't exist, an empty config will be loaded.
+    #
+    # @param [String] file An optional file name of the YAML file to create the
+    # config from
+    def initialize(file = nil)
+      @file_name = file ? file : File.join(Dir.home, '.unipeptrc')
+      if !File.exist? file_name
+        @config = {}
+      else
+        @config = YAML.load_file file_name
+      end
+    end
+
+    # Saves the config to disk. If the file doesn't exist yet, a new one will be
+    # created
+    def save
+      File.open(file_name, 'w') { |f| f.write config.to_yaml }
+    end
+
+    # Deletes a key
+    def delete(key)
+      config.delete(key)
+    end
+
+    # forwards [] to the internal config hash
+    def [](*args)
+      config.[](*args)
+    end
+
+    # forwards =[] to the internal config hash
+    def []=(*args)
+      config.[]=(*args)
+    end
+  end
+end

data/lib/formatters.rb

@@ -0,0 +1,252 @@
+require 'json'
+
+module Unipept
+  class Formatter
+    # The Hash of available formatters
+    #
+    # @return [Hash] A hash of the available formatters
+    def self.formatters
+      @@formatters ||= {}
+    end
+
+    # Returns a new formatter of the given format. If the given format is not available, the
+    # default formatter is returned
+    #
+    # @param [String] format The type of the formatter we want
+    #
+    # @return [Formatter] The requested formatter
+    def self.new_for_format(format)
+      formatters[format].new
+    rescue
+      formatters[default].new
+    end
+
+    # Adds a new formatter to the list of available formats
+    #
+    # @param [Symbol] format The type of the format we want to register
+    def self.register(format)
+      formatters[format.to_s] = self
+    end
+
+    # Returns a list of the available formatters
+    #
+    # @return [Array<String>] The list of available formatters
+    def self.available
+      formatters.keys
+    end
+
+    # @return [String] The type of the default formatter: csv
+    def self.default
+      'csv'
+    end
+
+    # @return [String] The type of the current formatter
+    def type
+      ''
+    end
+
+    # Returns the header row for the given sample_data and fasta_mapper. This
+    # row is output only once at the beginning of the output
+    #
+    # @param [Object] _sample_data The data that we will output after this
+    # header. Can be used to extract the keys.
+    #
+    # @param [Array<Array<String>>] _fasta_mapper Optional mapping between input
+    # data and corresponding fasta header. The data is represented as a list
+    # containing tuples where the first element is the fasta header and second
+    # element is the input data
+    #
+    # @return [String] The header row
+    def header(_sample_data, _fasta_mapper = nil)
+      ''
+    end
+
+    # Converts the given input data and corresponding fasta headers to another
+    # format.
+    #
+    # @param [Array] data The data we wish to convert
+    #
+    # @param [Array<Array<String>>] _fasta_mapper Optional mapping between input
+    # data and corresponding fasta header. The data is represented as a list
+    # containing tuples where the first element is the fasta header and second
+    # element is the input data
+    #
+    # @return [String] The converted input data
+    def format(data, _fasta_mapper = nil)
+      data
+    end
+  end
+
+  class JSONFormatter < Formatter
+    require 'json'
+    register :json
+
+    # @return [String] The type of the current formatter: json
+    def type
+      'json'
+    end
+
+    # Converts the given input data and corresponding fasta headers to JSON.
+    # Currently ignores the fasta_mapper.
+    #
+    # @param [Array] data The data we wish to convert
+    #
+    # @param [Array<Array<String>>] _fasta_mapper Optional mapping between input
+    # data and corresponding fasta header. The data is represented as a list
+    # containing tuples where the first element is the fasta header and second
+    # element is the input data
+    #
+    # @return [String] The input data converted to the JSON format.
+    def format(data, _fasta_mapper = nil)
+      # TODO: add fasta header based on fasta_mapper information
+      data.to_json
+    end
+  end
+
+  class CSVFormatter < Formatter
+    require 'csv'
+    register :csv
+
+    # @return [String] The type of the current formatter: csv
+    def type
+      'csv'
+    end
+
+    # Returns the header row for the given data and fasta_mapper. This row
+    # contains all the keys of the first element of the data, preceded by
+    # 'fasta_header' if a fasta_mapper is given.
+    #
+    # @param [Array] data The data that we will use to extract the keys from.
+    #
+    # @param [Array<Array<String>>] fasta_mapper Optional mapping between input
+    # data and corresponding fasta header. The data is represented as a list
+    # containing tuples where the first element is the fasta header and second
+    # element is the input data If a fasta_mapper is given, the output will be
+    # preceded with 'fasta_header'.
+    #
+    # @return [String] The header row
+    def header(data, fasta_mapper = nil)
+      CSV.generate do |csv|
+        first = data.first
+        keys = fasta_mapper ? ['fasta_header'] : []
+        csv << (keys + first.keys).map(&:to_s) if first
+      end
+    end
+
+    # Converts the given input data and corresponding fasta headers to the csv
+    # format
+    #
+    # @param [Array] data The data we wish to convert
+    #
+    # @param [Array<Array<String>>] fasta_mapper Optional mapping between input
+    # data and corresponding fasta header. The data is represented as a list
+    # containing tuples where the first element is the fasta header and second
+    # element is the input data
+    #
+    # @return [String] The converted input data into the csv format
+    def format(data, fasta_mapper = nil)
+      CSV.generate do |csv|
+        if fasta_mapper
+          format_fasta(csv, data, fasta_mapper)
+        else
+          format_normal(csv, data)
+        end
+      end
+    end
+
+    # Converts the given input data and corresponding fasta headers to the csv
+    # format
+    #
+    # @param [CSV] csv object we write the csv output to
+    #
+    # @param [Array] data The data we wish to convert
+    #
+    # @return [String] The converted input data into the csv format
+    def format_normal(csv, data)
+      data.each do |o|
+        csv << o.values.map { |v| v == ''  ? nil : v }
+      end
+    end
+
+    # Converts the given input data and corresponding fasta headers to the csv
+    # format
+    #
+    # @param [CSV] csv object we write the csv output to
+    #
+    # @param [Array] data The data we wish to convert
+    #
+    # @param [Array<Array<String>>] fasta_mapper Optional mapping between input
+    # data and corresponding fasta header. The data is represented as a list
+    # containing tuples where the first element is the fasta header and second
+    # element is the input data
+    #
+    # @return [String] The converted input data into the csv format
+    def format_fasta(csv, data, fasta_mapper)
+      data_dict = group_by_first_key(data)
+      fasta_mapper.each do |fasta_header, key|
+        next if data_dict[key].nil?
+
+        data_dict[key].each do |r|
+          csv << ([fasta_header] + r.values).map { |v| v == '' ? nil : v }
+        end
+      end
+    end
+
+    # Groups the data by the first key of each element, for example
+    # [{key1: v1, key2: v2},{key1: v1, key2: v3},{key1: v4, key2: v2}]
+    # to {v1 => [{key1: v1, key2: v2},{key1: v1, key2: v3}], v4 => [{key1: v4, key2: v2}]]
+    #
+    # @param [Array<Hash>] data The data we wish to Groups
+    #
+    # @return [Hash] The input data grouped by the first key
+    def group_by_first_key(data)
+      data.group_by { |el| el.values.first.to_s }
+    end
+  end
+
+  class XMLFormatter < Formatter
+    # Monkey patch (do as to_xml, but saner)
+
+    class ::Object
+      def to_xml(name = nil)
+        name ? %(<#{name}>#{self}</#{name}>) : to_s
+      end
+    end
+
+    class ::Array
+      def to_xml(array_name = :array, _item_name = :item)
+        %(<#{array_name} size="#{size}">) + map { |n|n.to_xml(:item) }.join + "</#{array_name}>"
+      end
+    end
+
+    class ::Hash
+      def to_xml(name = nil)
+        data = to_a.map { |k, v|v.to_xml(k) }.join
+        name ? "<#{name}>#{data}</#{name}>" : data
+      end
+    end
+
+    register :xml
+
+    # @return [String] The type of the current formatter: xml
+    def type
+      'xml'
+    end
+
+    # Converts the given input data and corresponding fasta headers to XML.
+    # Currently ignores the fasta_mapper.
+    #
+    # @param [Array] data The data we wish to convert
+    #
+    # @param [Array<Array<String>>] _fasta_mapper Optional mapping between input
+    # data and corresponding fasta header. The data is represented as a list
+    # containing tuples where the first element is the fasta header and second
+    # element is the input data
+    #
+    # @return [String] The input data converted to the XML format.
+    def format(data, _fasta_mapper = nil)
+      # TODO: add fasta header based on fasta_mapper information
+      data.to_xml
+    end
+  end
+end

data/lib/version.rb

@@ -0,0 +1,3 @@
+module Unipept
+  VERSION = File.read(File.join(File.dirname(__FILE__), '..', 'VERSION')).chomp
+end