Semantic Web

Functions
	chado_generate_var ($table, $values, $base_options=[], $schema_name=NULL)
	chado_expand_var ($object, $type, $to_expand, $table_options=[], $schema_name=NULL)

Detailed Description

This API generates objects containing the full details of a record(s) in chado.

Function Documentation

chado_expand_var()

chado_expand_var	(		$object,
			$type,
			$to_expand,
			$table_options = [],
			$schema_name = NULL
	)

Retrieves fields, or tables that were excluded by default from a variable.

The chado_generate_var() function automatically excludes some fields and tables from the default form of a variable. Fields that are extremely long, such as text fields are automatically excluded to prevent long page loads. Linking tables that have a many-to-one relationship with the record are also excluded. This function allows for custom expansion of the record created by chado_generate_var() by specifyin the field and tables that should be added.

Example Usage:

// Get a chado object to be expanded
$values = array(
  'name' => 'Medtr4g030710'
);
$features = chado_generate_var('feature', $values);
// Expand the feature.residues field
$feature = chado_expand_var($feature, 'field', 'feature.residues');
// Expand the feature properties (featureprop table)
$feature = chado_expand_var($feature, 'table', 'featureprop');

If a field is requested, its value is added where it normally is expected in the record. If a table is requested then a new key/value element is added to the record. The key is the table's name and the value is an array of records (of the same type created by chado_generate_var()). For example, expanding a 'feature' record to include a 'pub' record via the 'feature_pub' table. The following provides a simple example for how the 'feature_pub' table is added.

array(
  'feature_id' => 1
  'name' => 'blah',
  'uniquename' => 'blah',
  ....
  'feature_pub => array(
     [pub object],
     [pub object],
     [pub object],
     [pub object],
  )
)

where [pub object] is a record of a publication as created by chado_generate_var().

If the requested table has multiple foreign keys, such as the 'featureloc' or 'feature_genotype' tables, then an additional level is added to the array where the foreign key column names are added. An example feature record with an expanded featureloc table is shown below:

array(
  'feature_id' => 1
  'name' => 'blah',
  'uniquename' => 'blah',
  ....
  'featureloc => array(
     'srcfeature_id' => array(
       [feature object],
       ...
     )
     'feature_id' => array(
       [feature object],
       ...
     )
  )
)

Parameters

	$object	This must be an object generated using chado_generate_var()
	$type	Indicates what is being expanded. Must be one of 'field', 'foreign_key', 'table', . While field is self-explanitory, it might help to note that 'table' refers to tables that have a foreign key pointing to the current table (ie: featureprop is a table that can be expanded for features) and 'foreign_key' expands a foreign key in the current table that might have been excluded (ie: feature.type_id for features).
	$to_expand	The name of the field/foreign_key/table to be expanded
	$table_options	order_by: An array containing options for the base table. For example, an option of 'order_by' may be used to sort results in the base table if more than one are returned. The options must be compatible with the options accepted by the chado_select_record() function. return_array: Additionally, The option 'return_array' can be provided to force the function to expand tables as an array. Default behavior is to expand a table as single record if only one record exists or to expand as an array if multiple records exist. include_fk: an array of FK relationships to follow. By default, the chado_expand_var function will follow all FK relationships but this may generate more queries then is desired slowing down this function call when there are lots of FK relationships to follow. Provide an array specifying the fields to include. For example, if expanding a property table (e.g. featureprop) and you want the CV and accession but do not want the DB the following array would work: $table_options = array( 'include_fk' => array( 'type_id' => array( 'cv_id' => 1, 'dbxref_id' => 1, ) ) ); The above array will expand the 'type_id' of the property table but only further expand the cv_id and the dbxref_id and will go no further. pager: Use this option if it is desired to return only a subset of results so that they may be shown within a Drupal-style pager. This should be an array with two keys: 'limit' and 'element'. The value of 'limit' should specify the number of records to return and 'element' is a unique integer to differentiate between pagers when more than one appear on a page. The 'element' should start with zero and increment by one for each pager. This only works when type is a 'table'. filter: This options is only used where type=table and allows you to expand only a subset of results based on the given criteria. Criteria should provided as an array of [field name] => [value] similar to the values array provided to chado_generate_var(). For example, when expanding the featureprop table for a feature, you will already get only properties for that feature, this option allows you to further get only properties of a given type by passing in array('type_id' => array('name' => [name of type]))
string	$schema_name	The name of chado schema the variable is in.

Returns

A chado object supplemented with the field/table requested to be expanded. If the type is a table and it has already been expanded no changes is made to the returned object

chado_generate_var()

chado_generate_var	(		$table,
			$values,
			$base_options = [],
			$schema_name = NULL
	)

Generates an object containing the full details of a record(s) in Chado.

The object returned contains key/value pairs where the keys are the fields in the Chado table.

The returned object differs from the array returned by chado_select_record() as all foreign key relationships in the Chado table have been followed and those data are also included. This function automatically excludes some fields and tables. Fields that are extremely long, such as text fields are automatically excluded to prevent long page loads. Linking tables that have a many-to-one relationship with the record are also excluded. Use the chado_expand_var() to manually add in excluded fields and data from linker tables.

Example Usage:

$values = array(
  'name' => 'Medtr4g030710'
);
$feature = chado_generate_var('feature', $values);

The $values array passed to this function can be of the same format used by the chado_select_record() function.

If a field is a foreign key then its value is an object that contains key/value pairs for that record. The following code provides examples for retrieving values associated with the record, either as columns in the original Chado table or as columns in linked records through foreign keys:

// Get the feature name.
$name = $feature->name;
// Get the feature unique name.
$uniquename = $feature->uniquename;
// Get the feature type. Because the type name is obtained via
// a foreign key with the cvterm table, the objects are nested
// and we can follow the foreign key fields to retrieve those values
$type = $feature->type_id->name;
// Get the name of the vocabulary.
$cv = $feature->type_id->cv_id->name;
// Get the vocabulary id.
$cv_id = $feature->type_id->cv_id->cv_id;

This will return an object if there is only one feature with the name Medtr4g030710 or it will return an array of feature objects if more than one feature has that name.

Note to Module Designers: Fields can be excluded by default from these objects by implementing one of the following hooks:

• hook_exclude_field_from_tablename_by_default (where tablename is the name of the table): This hook allows you to add fields to be excluded on a per table basis. Simply implement this hook to return an array of fields to be excluded. The following example will ensure that feature.residues is excluded from a feature object by default:

  mymodule_exclude_field_from_feature_by_default() {
    return array('residues' => TRUE);
  }

• hook_exclude_type_by_default: This hook allows you to exclude fields using conditional. This function should return an array of postgresql types mapped to criteria. If the field types of any table match the criteria then the field is excluded. Tokens available in criteria are >field_value< and >field_name<. The following example will exclude all text fields with a length > 50. Thus if $feature.residues is longer than 50 it will be excluded, otherwise it will be added.

  mymodule_exclude_type_by_default() {
    return array('text' => 'length(>field_value< ) > 50');
  }

Parameters

	$table	The name of the base table to generate a variable for
	$values	A select values array that selects the records you want from the base table (this has the same form as chado_select_record)
	$base_options	An array containing options for the base table. For example, an option of 'order_by' may be used to sort results in the base table if more than one are returned. The options must be compatible with the options accepted by the chado_select_record() function. Additionally, These options are available for this function: -return_array: can be provided to force the function to always return an array. Default behavior is to return a single record if only one record exists or to return an array if multiple records exist. include_fk: an array of FK relationships to follow. By default, the chado_select_record function will follow all FK relationships but this may generate more queries then is desired slowing down this function call when there are lots of FK relationships to follow. Provide an array specifying the fields to include. For example, if expanding a property table (e.g. featureprop) and you want the CV and accession but do not want the DB the following array would work: $table_options = [ 'include_fk' => [ 'type_id' => [ 'cv_id' => 1, 'dbxref_id' => 1, ] ] ); The above array will expand the 'type_id' of the property table but only further expand the cv_id and the dbxref_id and will go no further. pager: Use this option if it is desired to return only a subset of results so that they may be shown within a Drupal-style pager. This should be an array with two keys: 'limit' and 'element'. The value of 'limit' should specify the number of records to return and 'element' is a unique integer to differentiate between pagers when more than one appear on a page. The 'element' should start with zero and increment by one for each pager.
string	$schema_name	The name of the schema to pull the variable from.

Returns

Either an object (if only one record was selected from the base table) or an array of objects (if more than one record was selected from the base table). If the option 'return_array' is provided the function always returns an array.