Class: Bioroebe::Biomart::Dataset

Inherits:
Object
  • Object
show all
Includes:
Bioroebe::Biomart
Defined in:
lib/bioroebe/biomart/dataset.rb

Overview

Bioroebe::Biomart::Dataset

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods included from Bioroebe::Biomart

#request

Constructor Details

#initialize(url, args) ⇒ Dataset

#

initialize

Creates a new Biomart::Dataset object.

arguments hash:

{
  :name         => String,     #
  "name"        => String,     #
  :display_name => {}          #

}
#

Parameters:

  • url (String) —

    The URL location of the biomart server.

  • args (Hash) —

    An arguments hash giving details of the dataset.


38
39
40
41
42
43
44
45
46
47
48
 
# File 'lib/bioroebe/biomart/dataset.rb', line 38

def initialize(url, args)
  @url = url or raise ArgumentError, 'must pass :url'
  unless @url =~ /martservice/
    @url = @url+'/martservice'
  end

  @name         = args['name'] || args[:name]
  @display_name = args['displayName'] || args[:display_name]
  @visible      = ( args["visible"] || args[:visible] ) ? true : false
  reset
end

Instance Attribute Details

#display_name ⇒ Object (readonly)

Returns the value of attribute display_name.


19
20
21
 
# File 'lib/bioroebe/biomart/dataset.rb', line 19

def display_name
  @display_name
end

Instance Method Details

#alive? ⇒ Boolean

#

alive?

Simple heartbeat function to test that a Biomart server is online.

#

Returns:

  • (Boolean) —

    true/false


276
277
278
279
 
# File 'lib/bioroebe/biomart/dataset.rb', line 276

def alive?
  server = Biomart::Server.new(@url)
  return server.alive?
end

#attributes ⇒ Hash

#

attributes

Returns a hash (keyed by the biomart 'internal_name' for the attribute) of all of the Biomart::Attribute objects belonging to this dataset.

#

Returns:

  • (Hash) —

    A hash of Biomart::Attribute objects keyed by 'internal_name'


117
118
119
120
121
122
 
# File 'lib/bioroebe/biomart/dataset.rb', line 117

def attributes
  if @attributes.empty?
    fetch_configuration()
  end
  return @attributes
end

#count(args = {}) ⇒ Object

#

count

Function to perform a Biomart count. Returns an integer value for the result of the count query.

arguments:

{
  :timeout => integer, # set a timeout length for the request (secs) - optional
  :filters => {}       # hash of key-value pairs (filter => search term) - optional
}
#

Parameters:

  • args (Hash) (defaults to: {}) —

    The arguments hash

Raises:

  • Biomart::ArgumentError Raised when un-supported arguments are passed


155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
 
# File 'lib/bioroebe/biomart/dataset.rb', line 155

def count(args = {})
  if args[:federate]
    raise Biomart::ArgumentError, 'You cannot federate a count query.'
  end
  if args[:required_attributes]
    raise Biomart::ArgumentError,
      'The :required_attributes option is not allowed on count queries.'
  end
  result = request(
    :method  => 'post',
    :url     => @url,
    :timeout => args[:timeout],
    :query   => generate_xml(
      :filters    => args[:filters], 
      :attributes => args[:attributes], 
      :count      => "1"
    )
  )
  return result.to_i
end

#filters? ⇒ Hash Also known as: filters

#

filters?

Returns a hash (keyed by the biomart 'internal_name' for the filter) of all of the Biomart::Filter objects belonging to this dataset.

#

Returns:

  • (Hash) —

    A hash of Biomart::Filter objects keyed by 'internal_name'


87
88
89
90
91
92
 
# File 'lib/bioroebe/biomart/dataset.rb', line 87

def filters?
  if @filters.empty?
    fetch_configuration()
  end
  return @filters
end

#generate_xml(args = {}) ⇒ Object

#

generate_xml

Utility function to build the Biomart query XML - used by #count and #search.

#

See Also:


244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
 
# File 'lib/bioroebe/biomart/dataset.rb', line 244

def generate_xml(
    args = {}
  )
  biomart_xml = ''
  xml = Builder::XmlMarkup.new( :target => biomart_xml, :indent => 2 )
  xml.instruct!
  xml.declare!( :DOCTYPE, :Query )
  xml.Query( :virtualSchemaName => "default", :formatter => "TSV", :header => "0", :uniqueRows => "1", :count => args[:count], :datasetConfigVersion => "0.6" ) {
    dataset_xml( xml, self, { :filters => args[:filters], :attributes => args[:attributes] } )
    if args[:federate]
      args[:federate].each { |joined_dataset|
        unless joined_dataset[:dataset].is_a?(Biomart::Dataset)
          raise Biomart::ArgumentError, "You must pass a Biomart::Dataset object to the :federate[:dataset] option."
        end
        dataset_xml(
          xml,
          joined_dataset[:dataset],
          { :filters => joined_dataset[:filters], :attributes => joined_dataset[:attributes] }
        )
      }
    end
  }
  return biomart_xml
end

#list_attributes ⇒ Array

#

list_attributes

Returns an array of the attribute names (biomart 'internal_name') for this dataset.

#

Returns:

  • (Array) —

    An array of attributes (their 'internal_name's)


132
133
134
135
136
137
 
# File 'lib/bioroebe/biomart/dataset.rb', line 132

def list_attributes
  if @attributes.empty?
    fetch_configuration
  end
  return @attributes.keys
end

#list_filters ⇒ Array

#

list_filters

Returns an array of the filter names (biomart 'internal_name') for this dataset.

#

Returns:

  • (Array) —

    An array of filters (their 'internal_name's)


102
103
104
105
106
107
 
# File 'lib/bioroebe/biomart/dataset.rb', line 102

def list_filters
  if @filters.empty?
    fetch_configuration()
  end
  return @filters.keys
end

#name? ⇒ Boolean Also known as: name

#

name?

#

Returns:

  • (Boolean) 

284
285
286
 
# File 'lib/bioroebe/biomart/dataset.rb', line 284

def name?
  @name
end

#reset ⇒ Object

#

reset (reset tag)

#

53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
 
# File 'lib/bioroebe/biomart/dataset.rb', line 53

def reset
  # ======================================================================= #
  # === @filters
  # ======================================================================= #
  @filters     = {}
  # ======================================================================= #
  # === @attributes
  # ======================================================================= #
  @attributes  = {}
  # ======================================================================= #
  # === @importables
  # ======================================================================= #
  @importables = {}
  # ======================================================================= #
  # === @exportables
  # ======================================================================= #
  @exportables = {}
end

#search(args = {}) ⇒ Object

#

Function to perform a Biomart search.

optional arguments:

{
  :process_results     => true/false,   # convert search results to object
  :timeout             => integer,      # set a timeout length for the request (secs)
  :filters             => {},           # hash of key-value pairs (filter => search term)
  :attributes          => [],           # array of attributes to retrieve
  :required_attributes => [],           # array of attributes that are required
  :federate => [
    {
      :dataset    => Biomart::Dataset, # A dataset object to federate with
      :filters    => {},               # hash of key-value pairs (filter => search term)
      :attributes => []                # array of attributes to retrieve
    }
  ]
}

Note, if you do not pass any filters or attributes arguments, the defaults for the dataset shall be used.

Also, using the :required_attributes option - this performs AND logic and will require data to be returned in all of the listed attributes in order for it to be returned.

By default will return a hash with the following:

{
  :headers => [],   # array of headers
  :data    => []    # array of arrays containing search results
}

But with the :process_results option will return an array of hashes, where each hash represents a row of results (keyed by the attribute name).

@param [Hash] args The arguments hash
@return [Hash/Array] Will return a hash by default (of unprocessed
                     data), or will return an array of hashes
@raise Biomart::ArgumentError Raised if incorrect arguments are passed
#

220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
 
# File 'lib/bioroebe/biomart/dataset.rb', line 220

def search(args = {})
  if args[:required_attributes] and !args[:required_attributes].is_a?(Array)
    raise Biomart::ArgumentError, "The :required_attributes option must be passed as an array."
  end
  response = request(
    :method  => 'post',
    :url     => @url,
    :timeout => args[:timeout],
    :query   => generate_xml( process_xml_args(args) )
  )
  result = process_tsv(args, response)
  result = filter_data_rows(args, result) if args[:required_attributes]
  result = conv_results_to_a_of_h(result) if args[:process_results]
  return result
end

#visible? ⇒ Boolean Also known as: visible

#

visible?

#

Returns:

  • (Boolean) 

75
76
77
 
# File 'lib/bioroebe/biomart/dataset.rb', line 75

def visible?
  @visible
end