API: Made the chado_get functions consistent including adding property support where applicable

tripal_analysis/api/tripal_analysis.api.inc

@@ -46,28 +46,109 @@ function tripal_analysis_unregister_child($modulename) {
 }
 
 /**
- * Get the analysis node same as node_load would but allowing different arguements
+ * Retrieves an chado analysis variable
  *
  * @param $itentifier
  *   an array with the key stating what the identifier is. Supported keys (only on of the
  *   following unique keys is required):
  *    - analysis_id: the chado analysis.analysis_id primary key
  *    - nid: the drupal node.nid primary key
+ *   There are also some specially handled keys. They are:
+ *    - property: An array/object describing the property to select records for. It
+ *      should at least have either a type_name (if unique across cvs) or type_id. Other
+ *      supported keys include: cv_id/cv_name (of the type), value and rank
+ * @param $options
+ *   An array of options. Supported keys include:
+ *     - Any keys supported by chado_generate_var(). See that function definition for
+ *       additional details.
+ *
+ * NOTE: the $identifier parameter can really be any array similar to $values passed into
+ *   chado_select_record(). It should fully specify the stock record to be returned.
+ *
  * @return
  *   the analysis node matching the passed in identifier
+ *
+ * @ingroup tripal_analysis_api
  */
-function chado_get_analysis($identifier) {
+function chado_get_analysis($identifier, $options) {
 
-  // If the analysis_id is passed in then use it to get the nid
-  if (isset($identifier['analysis_id'])) {
-    $identifier['nid'] = chado_get_nid_from_id('analysis', $identifier['analysis_id']);
+  // Set Defaults
+  if (!isset($options['include_fk'])) {
+    // Tells chado_generate_var not to follow any foreign keys
+    $options['include_fk'] = array();
   }
 
-  // Using the nid, get the node
-  if (isset($identifier['nid'])) {
-    return node_load($identifier['nid']);
+  // Error Checking of parameters
+  if (!is_array($identifiers)) {
+    tripal_report_error(
+      'tripal_stock_api',
+      TRIPAL_ERROR,
+      "chado_get_stock: The identifier passed in is expected to be an array with the key
+        matching a column name in the stock table (ie: stock_id or name). You passed in %identifier.",
+      array(
+        '%identifier'=> print_r($identifiers, TRUE)
+      )
+    );
   }
+  elseif (empty($identifiers)) {
+    tripal_report_error(
+      'tripal_stock_api',
+      TRIPAL_ERROR,
+      "chado_get_stock: You did not pass in anything to identify the stock you want. The identifier
+        is expected to be an array with the key matching a column name in the stock table
+        (ie: stock_id or name). You passed in %identifier.",
+      array(
+        '%identifier'=> print_r($identifiers, TRUE)
+      )
+    );
+  }
+
+  // If one of the identifiers is property then use chado_get_record_with_property()
+  if (isset($identifiers['property'])) {
+    $property = $identifiers['property'];
+    unset($identifiers['property']);
+    $analysis = chado_get_record_with_property('analysis', $property, $identifiers, $options);
+  }
+
+  // Else we have a simple case and we can just use chado_generate_var to get the analysis
+  else {
 
-  // If there is neither the nid or analysis_id then return FALSE to indicate we failed
-  return FALSE;
+    // Try to get the analysis
+    $analysis = chado_generate_var(
+      'analysis',
+      $identifiers,
+      $options
+    );
+  }
+
+  // Ensure the analysis is singular. If it's an array then it is not singular
+  if (is_array($analysis)) {
+    tripal_report_error(
+      'tripal_analysis_api',
+      TRIPAL_ERROR,
+      "chado_get_analysis: The identifiers you passed in were not unique. You passed in %identifier.",
+      array(
+        '%identifier'=> print_r($identifiers, TRUE)
+      )
+    );
+  }
+
+  // Report an error if $analysis is FALSE since then chado_generate_var has failed
+  elseif ($analysis === FALSE) {
+    tripal_report_error(
+      'tripal_analysis_api',
+      TRIPAL_ERROR,
+      "chado_get_analysis: chado_generate_var() failed to return a analysis based on the identifiers
+        you passed in. You should check that your identifiers are correct, as well as, look
+        for a chado_generate_var error for additional clues. You passed in %identifier.",
+      array(
+        '%identifier'=> print_r($identifiers, TRUE)
+      )
+    );
+  }
+
+  // Else, as far we know, everything is fine so give them their analysis :)
+  else {
+    return $analysis;
+  }
 }

tripal_cv/api/tripal_cv.api.inc

@@ -22,7 +22,7 @@
  */
 
 /**
- * Retrieves a chado controlled vocabulary object
+ * Retrieves a chado controlled vocabulary variable
  *
  * @param $identifier
  *   An array with the key stating what the identifier is. Supported keys (only on of the
@@ -46,6 +46,12 @@
  */
 function chado_get_cv($identifiers, $options = array()) {
 
+  // Set Defaults
+  if (!isset($options['include_fk'])) {
+    // Tells chado_generate_var not to follow any foreign keys
+    $options['include_fk'] = array();
+  }
+
   // Error Checking of parameters
   if (!is_array($identifiers)) {
     tripal_report_error(
@@ -133,16 +139,20 @@ function cv_get_select_options() {
 }
 
 /**
- * Retrieves a chado controlled vocabulary term object
+ * Retrieves a chado controlled vocabulary term variable
  *
  * @param $identifier
  *   An array with the key stating what the identifier is. Supported keys (only on of the
  *   following unique keys is required):
  *    - cvterm_id: the chado cv.cvterm_id primary key
  *    - name: the chado cv.name field (assume unique)
+ *   There are also some specially handled keys. They are:
  *    - synonym: an array with 'name' => the name of the synonym of the cvterm you want
  *        returned; 'cv_id' => the cv_id of the synonym; 'cv_name' => the name of the cv
  *        of the synonym
+ *    - property: An array/object describing the property to select records for. It
+ *      should at least have either a type_name (if unique across cvs) or type_id. Other
+ *      supported keys include: cv_id/cv_name (of the type), value and rank
  * @param $options
  *   An array of options. Supported keys include:
  *     - Any keys supported by chado_generate_var(). See that function definition for
@@ -160,6 +170,12 @@ function cv_get_select_options() {
  */
 function chado_get_cvterm($identifiers, $options = array()) {
 
+  // Set Defaults
+  if (!isset($options['include_fk'])) {
+    // Tells chado_generate_var to only get the cv
+    $options['include_fk'] = array('cv_id' => TRUE);
+  }
+
   // Error Checking of parameters
   if (!is_array($identifiers)) {
     tripal_report_error(
@@ -218,12 +234,23 @@ function chado_get_cvterm($identifiers, $options = array()) {
     $identifiers = array('cvterm_id' => $synonym[0]->cvterm_id);
   }
 
-  // Try to get the cvterm
-  $cvterm = chado_generate_var(
-    'cvterm',
-    $identifiers,
-    $options
-  );
+  // If one of the identifiers is property then use chado_get_record_with_property()
+  if (isset($identifiers['property'])) {
+    $property = $identifiers['property'];
+    unset($identifiers['property']);
+    $cvterm = chado_get_record_with_property('cvterm', $property, $identifiers, $options);
+  }
+
+  // Else we have a simple case and we can just use chado_generate_var to get the cvterm
+  else {
+
+    // Try to get the cvterm
+    $cvterm = chado_generate_var(
+      'cvterm',
+      $identifiers,
+      $options
+    );
+  }
 
   // Ensure the cvterm is singular. If it's an array then it is not singular
   if (is_array($cvterm)) {

tripal_db/api/tripal_db.api.inc

@@ -14,7 +14,7 @@
  */
 
 /**
- * Retrieves a chado db object
+ * Retrieves a chado db variable
  *
  * Example Usage:
  * @code
@@ -56,6 +56,12 @@
  */
 function chado_get_db($identifiers, $options = array()) {
 
+  // Set Defaults
+  if (!isset($options['include_fk'])) {
+    // Tells chado_generate_var not to follow any foreign keys
+    $options['include_fk'] = array();
+  }
+
   // Error Checking of parameters
   if (!is_array($identifiers)) {
     tripal_report_error(
@@ -143,7 +149,7 @@ function db_get_select_options() {
 }
 
 /**
- * Retrieves a chado database reference object
+ * Retrieves a chado database reference variable
  *
  * Example Usage:
  * @code
@@ -171,10 +177,14 @@ function db_get_select_options() {
  * @endcode
  *
  * @param $identifier
- *   An array with the key stating what the identifier is. Supported keys (only on of the
+ *   An array with the key stating what the identifier is. Supported keys (only one of the
  *   following unique keys is required):
  *    - dbxref_id: the chado dbxref.dbxref_id primary key
  *    - accession: the chado dbxref.accession field (assume unique)
+ *   There are also some specially handled keys. They are:
+ *    - property: An array/object describing the property to select records for. It
+ *      should at least have either a type_name (if unique across cvs) or type_id. Other
+ *      supported keys include: cv_id/cv_name (of the type), value and rank
  * @param $options
  *   An array of options. Supported keys include:
  *     - Any keys supported by chado_generate_var(). See that function definition for
@@ -192,6 +202,12 @@ function db_get_select_options() {
  */
 function chado_get_dbxref($identifiers, $options = array()) {
 
+  // Set Defaults
+  if (!isset($options['include_fk'])) {
+    // Tells chado_generate_var not only expand the db
+    $options['include_fk'] = array('db_id' => TRUE);
+  }
+
   // Error Checking of parameters
   if (!is_array($identifiers)) {
     tripal_report_error(
@@ -217,12 +233,21 @@ function chado_get_dbxref($identifiers, $options = array()) {
     );
   }
 
-  // Try to get the dbxref
-  $dbxref = chado_generate_var(
-    'dbxref',
-    $identifiers,
-    $options
-  );
+  // If one of the identifiers is property then use chado_get_record_with_property()
+  if (isset($identifiers['property'])) {
+    $property = $identifiers['property'];
+    unset($identifiers['property']);
+    $dbxref = chado_get_record_with_property('dbxref', $property, $identifiers, $options);
+  }
+
+  // Else we have a simple case and we can just use chado_generate_var to get the analysis
+  else {
+    $dbxref = chado_generate_var(
+      'dbxref',
+      $identifiers,
+      $options
+    );
+  }
 
   // Ensure the dbxref is singular. If it's an array then it is not singular
   if (is_array($dbxref)) {

tripal_organism/api/tripal_organism.api.inc

@@ -13,13 +13,17 @@
  */
 
 /**
- * Retrieves a chado organism object
+ * Retrieves a chado organism variable
  *
  * @param $identifier
  *   An array with the key stating what the identifier is. Supported keys (only on of the
  *   following unique keys is required):
  *    - organism_id: the chado organism.organism_id primary key
  *    - genus & species: the chado organism.genus field & organism.species field
+ *   There are also some specially handled keys. They are:
+ *    - property: An array/object describing the property to select records for. It
+ *      should at least have either a type_name (if unique across cvs) or type_id. Other
+ *      supported keys include: cv_id/cv_name (of the type), value and rank
  * @param $options
  *   An array of options. Supported keys include:
  *     - Any keys supported by chado_generate_var(). See that function definition for
@@ -37,6 +41,12 @@
  */
 function chado_get_organism($identifiers, $options = array()) {
 
+  // Set Defaults
+  if (!isset($options['include_fk'])) {
+    // Tells chado_generate_var not to follow any foreign keys
+    $options['include_fk'] = array();
+  }
+
   // Error Checking of parameters
   if (!is_array($identifiers)) {
     tripal_report_error(
@@ -62,12 +72,23 @@ function chado_get_organism($identifiers, $options = array()) {
     );
   }
 
-  // Try to get the organism
-  $organism = chado_generate_var(
-    'organism',
-    $identifiers,
-    $options
-  );
+  // If one of the identifiers is property then use chado_get_record_with_property()
+  if (isset($identifiers['property'])) {
+    $property = $identifiers['property'];
+    unset($identifiers['property']);
+    $organism = chado_get_record_with_property('organism', $property, $identifiers, $options);
+  }
+
+  // Else we have a simple case and we can just use chado_generate_var to get the analysis
+  else {
+
+    // Try to get the organism
+    $organism = chado_generate_var(
+      'organism',
+      $identifiers,
+      $options
+    );
+  }
 
   // Ensure the organism is singular. If it's an array then it is not singular
   if (is_array($organism)) {

tripal_stock/api/tripal_stock.api.inc

@@ -13,7 +13,7 @@
  */
 
 /**
- * Retrieves a chado stock object
+ * Retrieves a chado stock variable
  *
  * @param $identifier
  *   An array with the key stating what the identifier is. Supported keys (only one of the
@@ -41,6 +41,12 @@
  */
 function chado_get_stock($identifiers, $options = array()) {
 
+  // Set Defaults
+  if (!isset($options['include_fk'])) {
+    // Tells chado_generate_var to only expand 1 level
+    $options['include_fk'] = array('type_id' => TRUE, 'dbxref_id' => TRUE);
+  }
+
   // Error Checking of parameters
   if (!is_array($identifiers)) {
     tripal_report_error(
@@ -117,7 +123,7 @@ function chado_get_stock($identifiers, $options = array()) {
 }
 
 /**
- * Retrieves a chado stock object
+ * Retrieves a chado stock variable
  *
  * @param $identifier
  *   An array with the key stating what the identifier is. Supported keys include any
@@ -135,6 +141,12 @@ function chado_get_stock($identifiers, $options = array()) {
  */
 function chado_get_multiple_stocks($identifiers, $options = array()) {
 
+  // Set Defaults
+  if (!isset($options['include_fk'])) {
+    // Tells chado_generate_var to only expand 1 level
+    $options['include_fk'] = array('type_id' => TRUE, 'dbxref_id' => TRUE);
+  }
+
   // Error Checking of parameters
   if (!is_array($identifiers)) {
     tripal_report_error(