Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Bio::MAGETAB::Util::BuUserrContributed Perl DocuBio::MAGETAB::Util::Builder(3)

NAME
       Bio::MAGETAB::Util::Builder - A storage class used to track
       Bio::MAGETAB object creation.

SYNOPSIS
	use Bio::MAGETAB::Util::Builder;
	my $builder = Bio::MAGETAB::Util::Builder->new({
	   relaxed_parser => $is_relaxed,
	});

DESCRIPTION
       Creation	of complex Bio::MAGETAB	object heirarchies and DAGs requires a
       mechanism to track the instantiated objects, and	manage any updates.
       This class (and its subclasses) provides	that mechanism.	Builder
       objects are created and included	in Reader object instantiation,	such
       that the	back-end storage engine	populated by a given Reader object may
       be redefined as desired.	This base Builder class	simply tracks objects
       in a hash of hashes; this is sufficient for simple parsing of MAGE-TAB
       documents. See the DBLoader class for an	example	of a Builder subclass
       that can	be used	to populate a Tangram-based relational database
       schema.

ATTRIBUTES
       relaxed_parser
	 A boolean value (default FALSE) indicating whether or not the parse
	 should	take place in "relaxed mode" or	not. The regular parsing mode
	 will throw an exception in cases where	an object is referenced	before
	 it has	been declared (e.g., Protocol REF pointing to a	non-existent
	 Protocol Name). Relaxed parsing mode will silently autogenerate the
	 non-existent objects instead.

       magetab
	 An optional Bio::MAGETAB container object. If none is passed upon
	 Builder object	instantiation, a new Bio::MAGETAB object is created
	 for you. See the Bio::MAGETAB class for details.

       authority
	 An optional authority string to be used in object creation.

       namespace
	 An optional namespace string to be used in object creation.

       database
	 The internal store to use for object lookups. In the base Builder
	 class this is a simple	hash reference,	and it is unlikely that	you
	 will ever want	to change the default. This attribute is used in
	 persistence subclasses	(such as DBLoader) to point at the underlying
	 storage engine.

METHODS
       Each of the Bio::MAGETAB	classes	can be handled by get_*, create_* and
       find_or_create_*	methods.

       get_*
	 Retrieve the desired object from the database.	Takes a	hash reference
	 of attribute values and returns the desired object. This method
	 raises	an exception if	the passed-in attributes do not	match any
	 object	in the database. See "OBJECT IDENTITY",	below, for information
	 on how	objects	are matched in the database.

       create_*
	 Creates a new object using the	passed attribute hash reference	and
	 stores	it in the database.

       find_or_create_*
	 Attempts to find the desired object in	the same way as	the get_*
	 methods, and upon failure creates a new object	and stores it.

       The following mapping should be used to determine the name of the
       desired method:

	Bio::MAGETAB class		    Method base	name
	------------------		    ----------------

	Bio::MAGETAB::ArrayDesign	    array_design
	Bio::MAGETAB::Assay		    assay
	Bio::MAGETAB::Comment		    comment
	Bio::MAGETAB::CompositeElement	    composite_element
	Bio::MAGETAB::Contact		    contact
	Bio::MAGETAB::ControlledTerm	    controlled_term
	Bio::MAGETAB::DataAcquisition	    data_acquisition
	Bio::MAGETAB::DatabaseEntry	    database_entry
	Bio::MAGETAB::DataFile		    data_file
	Bio::MAGETAB::DataMatrix	    data_matrix
	Bio::MAGETAB::Edge		    edge
	Bio::MAGETAB::Extract		    extract
	Bio::MAGETAB::Factor		    factor
	Bio::MAGETAB::FactorValue	    factor_value
	Bio::MAGETAB::Feature		    feature
	Bio::MAGETAB::Investigation	    investigation
	Bio::MAGETAB::LabeledExtract	    labeled_extract
	Bio::MAGETAB::MatrixColumn	    matrix_column
	Bio::MAGETAB::MatrixRow		    matrix_row
	Bio::MAGETAB::Measurement	    measurement
	Bio::MAGETAB::Normalization	    normalization
	Bio::MAGETAB::ParameterValue	    parameter_value
	Bio::MAGETAB::Protocol		    protocol
	Bio::MAGETAB::ProtocolApplication   protocol_application
	Bio::MAGETAB::ProtocolParameter	    protocol_parameter
	Bio::MAGETAB::Publication	    publication
	Bio::MAGETAB::Reporter		    reporter
	Bio::MAGETAB::SDRF		    sdrf
	Bio::MAGETAB::SDRFRow		    sdrf_row
	Bio::MAGETAB::Sample		    sample
	Bio::MAGETAB::Source		    source
	Bio::MAGETAB::TermSource	    term_source

       Example:	a Bio::MAGETAB::DataFile object	can be created using the
       "create_data_file" method.

       In addition to the above, the following method is included to help
       manage objects stored relational	database backends (see the DBLoader
       subclass):

       update
	 Passed	a list of Bio::MAGETAB objects,	this method will attempt to
	 update	those objects in any persistent	storage	engine.	This method
	 doesn't have any effect in the	base Builder class, but	it is very
	 important to the DBLoader subclass. See CAVEATS in the	DBLoader
	 class.

OBJECT IDENTITY
       For most	Bio::MAGETAB classes, identity between objects is fairly
       easily defined. For example, all	Material objects have a	name attribute
       which identifies	it within a given namespace:authority grouping.
       However,	many classes do	not have this simple mechanism.	For example,
       Edge objects have no attributes other than their	input and output
       nodes, and a list of protocol applications. To address this, the
       Builder module includes a set of	identity heuristics defined for	each
       class; in this example, Edge will be identified by examining its	input
       and output nodes. Namespace and authority terms are used	to localize
       objects.

       In theory this should all just work. However, the system	is complex and
       so undoubtedly there will be times when this module behaves other than
       you might expect. Therefore, the	current	set of heuristics is listed
       below for your debugging	delight:

	Bio::MAGETAB class		  Identity depends on:
	------------------		  -------------------
	Bio::MAGETAB::ArrayDesign	  name accession termSource
	Bio::MAGETAB::Assay		  name
	Bio::MAGETAB::Comment		  name value object*
	Bio::MAGETAB::CompositeElement	  name
	Bio::MAGETAB::Contact		  firstName midInitials	lastName
	Bio::MAGETAB::ControlledTerm	  category value termSource accession
	Bio::MAGETAB::DataAcquisition	  name
	Bio::MAGETAB::DatabaseEntry	  accession termSource
	Bio::MAGETAB::DataFile		  uri
	Bio::MAGETAB::DataMatrix	  uri
	Bio::MAGETAB::Edge		  inputNode outputNode
	Bio::MAGETAB::Extract		  name
	Bio::MAGETAB::Factor		  name
	Bio::MAGETAB::FactorValue	  factor term measurement
	Bio::MAGETAB::Feature		  blockCol blockRow col	row array_design*
	Bio::MAGETAB::Investigation	  title
	Bio::MAGETAB::LabeledExtract	  name
	Bio::MAGETAB::MatrixColumn	  columnNumber data_matrix*
	Bio::MAGETAB::MatrixRow		  rowNumber data_matrix*
	Bio::MAGETAB::Measurement	  measurementType value	minValue maxValue unit object*
	Bio::MAGETAB::Normalization	  name
	Bio::MAGETAB::ParameterValue	  parameter protocol_application*
	Bio::MAGETAB::Protocol		  name accession termSource
	Bio::MAGETAB::ProtocolApplication protocol edge*
	Bio::MAGETAB::ProtocolParameter	  name protocol
	Bio::MAGETAB::Publication	  title
	Bio::MAGETAB::Reporter		  name
	Bio::MAGETAB::SDRF		  uri
	Bio::MAGETAB::SDRFRow		  rowNumber sdrf*
	Bio::MAGETAB::Sample		  name
	Bio::MAGETAB::Source		  name
	Bio::MAGETAB::TermSource	  name

       Not all the slots are needed for	an object to be	identified; for
       example,	a Contact object might only have a lastName. Asterisked	(*)
       terms are those which do	not correspond to any attribute	of the
       Bio::MAGETAB class. These are typically "container" objects, i.e. those
       involved	in aggregating the target objects. For example,	the identity
       of a given Comment object is tied up with the "object" to which it has
       been applied. These objects are passed in as part of the	object
       instantiation hash reference, and are discarded prior to	object
       creation. NOTE: These aggregating objects are not processed in any way
       by Builder; you will need to ensure the objects are correctly linked
       together	yourself.

KNOWN BUGS
       The identity of Bio::MAGE::ProtocolApplication objects is based solely
       around the Protocol being applied, and the Edge to which	it is
       attached. Ideally, the protocol application date	would also be
       included, but this can create problems for persistence-based Builder
       subclasses where	the exact serialization	behavior of DateTime objects
       needs to	be defined (see	the DBLoader class). This is a tractable
       problem,	but a fix has been omitted from	this release since the use
       case (the same Protocol applied to a single Edge	multiple times on
       different dates)	seems a	minor one. The workaround is to	split the
       protocol	applications into as many Edges	as are needed.

SEE ALSO
       Bio::MAGETAB Bio::MAGETAB::Util::Reader Bio::MAGETAB::Util::DBLoader

AUTHOR
       Tim F. Rayner <tfrayner@gmail.com>

LICENSE
       This library is released	under version 2	of the GNU General Public
       License (GPL).

perl v5.32.1			  2013-01-13	Bio::MAGETAB::Util::Builder(3)

NAME | SYNOPSIS | DESCRIPTION | ATTRIBUTES | METHODS | OBJECT IDENTITY | KNOWN BUGS | SEE ALSO | AUTHOR | LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Bio::MAGETAB::Util::Builder&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help