Class: VORuby::UCD

Inherits:
Object
  • Object
show all
Defined in:
lib/voruby/ucd/ucd.rb

Overview

Unified Content Descriptors or UCDs constitute a controlled vocabulary used throughout the VO. This class provides some useful methods for dealing with them.

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(options = {}) ⇒ UCD

Create a new UCD resolver. options is a hash with the following keys:

:end_point

the UCD SOAP endpoint to use (default: cdsws.u-strasbg.fr/axis/services/UCD)

:check_availability

whether to try to determine if the sesame service is available or not before each name resolution (default: false)

ucd = UCD.new(
  :end_point => 'ttp://vizier.hia.nrc.ca:8080/axis/services/UCD' # maybe we're in Canada...
  :check_availability => true # and we want to always check the availability of the service
)



20
21
22
23
 
# File 'lib/voruby/ucd/ucd.rb', line 20

def initialize(options={})
  self.end_point = options[:end_point] || 'http://cdsws.u-strasbg.fr/axis/services/UCD'
  self.check_availability = options[:check_availability] || false
end

Instance Attribute Details

#check_availability ⇒ Object

Returns the value of attribute check_availability.



8
9
10
 
# File 'lib/voruby/ucd/ucd.rb', line 8

def check_availability
  @check_availability
end

Class Method Details

.assign(descr, options = {}) ⇒ Object

Convenience class method for #assign.



73
74
75
 
# File 'lib/voruby/ucd/ucd.rb', line 73

def self.assign(descr, options={})
  self.new(options).assign(descr)
end

.explain(ucd, version = '1+', options = {}) ⇒ Object

Convenience class method for #explain.



99
100
101
 
# File 'lib/voruby/ucd/ucd.rb', line 99

def self.explain(ucd, version='1+', options={})
  self.new(options).explain(ucd, version)
end

.translate(ucd, options = {}) ⇒ Object

Convenience class method for #translate.



57
58
59
 
# File 'lib/voruby/ucd/ucd.rb', line 57

def self.translate(ucd, options={})
  self.new(options).translate(ucd)
end

.upgrade(ucd, options = {}) ⇒ Object

Convenience class method for #upgrade.



157
158
159
 
# File 'lib/voruby/ucd/ucd.rb', line 157

def self.upgrade(ucd, options={})
  self.new(options).upgrade(ucd)
end

.valid?(ucd, options = {}) ⇒ Boolean

Convenience class method for #valid?.

Returns:

  • (Boolean) 


144
145
146
 
# File 'lib/voruby/ucd/ucd.rb', line 144

def self.valid?(ucd, options={})
  self.new(options).valid?(ucd)
end

.validate(ucd, options = {}) ⇒ Object

Convenience class method for #validate.



129
130
131
 
# File 'lib/voruby/ucd/ucd.rb', line 129

def self.validate(ucd, options={})
  self.new(options).validate(ucd)
end

Instance Method Details

#assign(descr) ⇒ Object

Given a text description of a parameter (i.e. V magnitude), find a likely corresponding UCD1+. Returns nil if no UCD is found.

ucd.assign('V magnitude')  # => 'phot.mag;em.opt.V'



65
66
67
68
69
70
 
# File 'lib/voruby/ucd/ucd.rb', line 65

def assign(descr)
  raise "UCD resolver at #{self.end_point} is not currently available" if self.check_availability and !self.available?
  
  ucd_plus = @resolver.assign(descr).strip
  ucd_plus.match('Could not find') ? nil : ucd_plus
end

#available? ⇒ Boolean

Checks to see whether the UCD resolver is available. At this point it’s assumed the service is present at the location specified by #end_point. This just checks to see whether sesame reports itself as available or not.

Returns:

  • (Boolean) 


165
166
167
168
169
170
171
 
# File 'lib/voruby/ucd/ucd.rb', line 165

def available?
  # We don't use an XML parser here because (as of 2007-01-04)
  # the validTo tag isn't closed properly, rendering the XML
  # malformed.
  result = @resolver.getAvailability
  result.match(/<available>\s*(.*)\s*<\/available>/)[1] == 'true'
end

#end_point ⇒ Object

The “end-point” or location of the UCD resolver’s webservice.



26
27
28
 
# File 'lib/voruby/ucd/ucd.rb', line 26

def end_point
  @end_point
end

#end_point=(epoint) ⇒ Object

Set the end-point or location of the UCD resolver’s webservice.

ucd.end_point = 'http://vizier.hia.nrc.ca:8080/axis/services/UCD'



32
33
34
35
36
37
38
39
40
41
42
43
 
# File 'lib/voruby/ucd/ucd.rb', line 32

def end_point=(epoint)
  @end_point = epoint
  
  @resolver = SOAP::RPC::Driver.new(@end_point)
  @resolver.add_rpc_method('translate', 'ucd')
  @resolver.add_rpc_method('assign', 'descr')
  @resolver.add_rpc_method('explain', 'ucd')
  @resolver.add_rpc_method('resolveUCD', 'ucd')
  @resolver.add_rpc_method('validate', 'ucd')
  @resolver.add_rpc_method('upgrade','ucd')
  @resolver.add_rpc_method('getAvailability')
end

#explain(ucd, version = '1+') ⇒ Object

Given a UCD, discover a human-readable description. version may be ‘1+’ (the default) for a UCD1+ or ‘1’ for an old-style UCD. Returns nil if the UCD is not recognized.

ucd.explain('ivoa:phot.mag;em.opt.B') # => 'Photometric magnitude / Optical band between 400 and 500 nm'
ucd.explain('PHOT_JHN_V', '1') # => 'Johnson magnitude V (JHN)'



84
85
86
87
88
89
90
91
92
93
94
95
96
 
# File 'lib/voruby/ucd/ucd.rb', line 84

def explain(ucd, version='1+')
  version ||= '1+'
  raise "UCD resolver at #{self.end_point} is not currently available" if self.check_availability and !self.available?
  
  descr = case version
    when '1'
      @resolver.resolveUCD(ucd)
    else
      @resolver.explain(ucd)
    end
    
  (descr.match('Non-standard UCD') or descr.match('Invalid UCD')) ? nil : descr.strip
end

#translate(ucd) ⇒ Object

Translate an old-style UCD1 into it’s newer UCD1+ form. Returns nil if the UCD is untranslatable.

ucd.translate('POS_EQ_RA_MAIN') # => 'pos.eq.ra;meta.main'



49
50
51
52
53
54
 
# File 'lib/voruby/ucd/ucd.rb', line 49

def translate(ucd)
  raise "UCD resolver at #{self.end_point} is not currently available" if self.check_availability and !self.available?
  
  ucd_plus = @resolver.translate(ucd).strip
  ucd_plus.match('Could not translate') ? nil : ucd_plus
end

#upgrade(ucd) ⇒ Object

Find a valid UCD1+ corresponding to a deprecated word.

ucd.upgrade('pos.gal.lat') # => 'pos.galactic.lat'



151
152
153
154
 
# File 'lib/voruby/ucd/ucd.rb', line 151

def upgrade(ucd)
  raise "UCD resolver at #{self.end_point} is not currently available" if self.check_availability and !self.available?
  @resolver.upgrade(ucd).strip
end

#valid?(ucd) ⇒ Boolean

Returns true or false depending on whether a UCD1+ is valid. This is the same checking the code on the object that #validate returns.

ucd.valid?('ivob:phot.mag;em.opt.Z') # => false
ucd.valid?('ivoa:phot.mag;em.opt.B') # => true

Returns:

  • (Boolean) 


139
140
141
 
# File 'lib/voruby/ucd/ucd.rb', line 139

def valid?(ucd)
  self.validate(ucd).code == 0 ? true : false
end

#validate(ucd) ⇒ Object

Validate a specifed UCD1+. Returns an object that responds to a #code method and a human-readable list of of error strings. A code of 0 implies the UCD is valid. Possible combinations arise from bitwise-OR’ing the following:

  • 1: warning indicating use of non-standard namespace (not ivoa:)

  • 2: use of deprecated word

  • 4: use of non-existing word

  • 8: syntax error (extra space or unallowed character)

    result = ucd.validate(‘ivob:phot.mag;em.opt.Z’) puts result.code # => 5 puts result.errors => [“use of non-standard namespace ‘ivob’”, “invalid UCD word ‘em.opt.Z’”]



116
117
118
119
120
121
122
123
124
125
126
 
# File 'lib/voruby/ucd/ucd.rb', line 116

def validate(ucd)
  raise "UCD resolver at #{self.end_point} is not currently available" if self.check_availability and !self.available?
  
  error = @resolver.validate(ucd).strip
  parts = error.split(/\s*\*\*\*\*\s*/)
  
  OpenStruct.new(
    :code => parts.first.to_i,
    :errors => parts[1..-1]
  )
end