Metacat

# = Ruby Ecoinformatics Library

# == What is it?

# A tool for accessing ecological datasets and their metadata in ruby.

# It's a way to do this:

#    squery = '<pathquery version="1.2">...</pathquery>' # looks for all pisco-subtidal data

#    Metacat.new('http://data.piscoweb.org/catalog/metacat') do |metacat|

#     eml_docs = metacat.find(:squery => squery)

#     eml_docs.each do |eml|

#       puts eml.docid

#       eml.data_tables.each do |data_table|

#         puts "\t --#{data_table.entity_name}"

#       end

#     end

#    end

# Spits out :

#    pisco_subtidal.40.1

#             --quad_taxon_lookup_table.csv

#             --pisco_quad_data.csv

#    pisco_subtidal.12.4

#             --fish_taxon_lookup_table.csv

#             --pisco_fish_data.csv

#    pisco_subtidal.21.7

#             --swath_taxon_lookup_table.csv

#             --pisco_swath_data.csv

#    pisco_subtidal.30.2

#             --upc_taxon_lookup_table.csv

#             --pisco_upc_data.csv

# For now, this library is for dealing with EML metadata and data coming out of

# the Metacat data catalog (http://knb.ecoinformatics.org/software/metacat).

# The Metacat client class will generally return Eml objects representing their

# corresponding EML document. This object can then be used to access document-wide

# metadata. Furthermore, each Eml object contains DataTable objects representing

# their corresponding DataTable elements. For now, Eml and DataTable are mostly

# a wrapper for a REXML:Document DOM representation of the XML data. In the future

# they may contain more functionality.

#

# One very important feature of classes Metacat and DataTable is the ability to

# read plain-text data tables by passing a block(closure) that handles fragments

# of the file. This way data can be read without the costs of loading a huge dataset

# directly into RAM.

# == Status

# The Metacat client library is very usable and I'm happy with the current documentation

#

# The Eml and even worse, DataTable classes are minimally functional. They also still

# contain fragments of the original application that inspired them which should be removed

# as they are not generally applicable. Documentation is also not up to par.

#

# I would recommend using the REXML:Document contained within both Eml and DataTable

# where their methods are lacking to access metadata attributes. DataTable.read() is 

# in a usable state and handles blocks the same way as Metacat.read.

#

# Where documentation is lacking check the unit tests under ./tests. These sometimes

# give a clearer picture of intended usage.

#

# == Examples

# See classes Metacat, Eml, and DataTable for more examples

# == Author

# Chad Burt

#

# Marine Science Institude

#

# University of California, Santa Barbara

#

# chad@underbluewaters.net