Insert a property for a given base table.

By default if the property already exists a new property is added with the next available rank. If the option 'update_if_present' is specified then the record will be updated if it exists rather than adding a new property.

Parameters

$record: An associative array used to identify the record to which the property should be assigned. The following keys must be used: -table: The base table for which the property should be inserted. Thus to insert a property for a feature the base_table=feature and property is inserted into featureprop. -id: The primary key value of the base table. The property will be associated with the record that matches this id.

$property: An associative array used to specify the property to be added. It can contain the following keys. The keys must be specified to uniquely identify the term to be applied. If the options identify more than one CV term then an error will occur. -type_name: The cvterm name to be selected. -type_id: The cvterm_id of the term to be selected. -cv_id: The cv_id of the CV that contains the term. -cv_name: The name of the CV that contains the term. -value: The specific value for the property. -rank: The specific rank for the property.

$options: An associative array containing the following keys: -update_if_present: A boolean indicating whether an existing record should be updated. If the property already exists and this value is not specified or is zero then a new property will be added with the next largest rank. -force_rank: If the specified rank is already used by another property recrod for the same base_id, then set force_rank to TRUE to require that only the specified rank can be used. Otherwise, the next available rank will be used. If 'update_if_present' is FALSE and 'force_rank' is set then an error will occur.

Return value

Return TRUE if successful and FALSE otherwise.

Related topics

File

tripal_chado/api/tripal_chado.property.api.inc, line 161

Provides an application programming interface (API) to manage data withing the Chado database.

Code

function chado_insert_property($record, $property, $options = array()) {

  $base_table = array_key_exists('table', $record) ? $record['table'] : '';
  $base_id = array_key_exists('id', $record) ? $record['id'] : '';

  $type_name = array_key_exists('type_name', $property) ? $property['type_name'] : '';
  $type_id = array_key_exists('type_id', $property) ? $property['type_id'] : '';
  $cv_name = array_key_exists('cv_name', $property) ? $property['cv_name'] : '';
  $cv_id = array_key_exists('cv_id', $property) ? $property['cv_id'] : '';
  $value = array_key_exists('value', $property) ? $property['value'] : '';
  $rank = array_key_exists('rank', $property) ? $property['rank'] : 0;
  $cvalue_id = array_key_exists('cvalue_id', $property) ? $property['cvalue_id'] : '';

  $update_if_present = array_key_exists('update_if_present', $options) ? $options['update_if_present'] : FALSE;
  $force_rank = array_key_exists('force_rank', $options) ? $options['force_rank'] : FALSE;

  // First see if the property is already assigned to the record. I
  $props = chado_get_property($record, $property);
  if (!is_array($props)) {
    if ($props) {
      $props = array($props);
    }
    else {
      $props = array();
    }
  }
  if (count($props) > 0) {
    // The property is already assigned, so, see if we should update it.
    if ($update_if_present) {
      return chado_update_property($record, $property);
    }
    else {
      if (!$force_rank) {
        // Iterate through the properties returned and check to see if the
        // property with this value already exists if not, get the largest rank
        // and insert the same property but with this new value.
        foreach ($props as $prop) {
          if ($prop->rank > $rank) {
            $rank = $prop->rank;
          }
          if (strcmp($prop->value, $value) == 0) {
            return TRUE;
          }
        }
        // Now add 1 to the rank.
        $rank++;
      }
      else {
        tripal_report_error('tripal_chado', TRIPAL_ERROR, "chado_insert_property: " .
          "The property is already assigned to the record with the following " .
          "rank.  And, because the 'force_rank' option is used, the property " .
          "cannot be added: %property.", 
        array('%property' => print_r($property, TRUE)));
        return FALSE;
      }
    }
  }

  // Build the values array for checking if the CVterm exists and for
  // inserting the term as a property.
  $values = array();
  if ($cv_id) {
    $values['cv_id'] = $cv_id;
  }
  if ($cv_name) {
    $values['cv_id'] = array(
      'name' => $cv_name,
    );
  }
  if ($type_name) {
    $values['name'] = $type_name;
  }
  if ($type_id) {
    $values['cvterm_id'] = $type_id;
  }

  // Make sure the CV term exists.
  $options = array();
  $term = chado_select_record('cvterm', array('cvterm_id'), $values, $options);
  if (!$term or count($term) == 0) {
    tripal_report_error('tripal_chado', TRIPAL_ERROR, "chado_insert_property: " .
      "Cannot find the term described by: %property.", 
    array('%property' => print_r($property, TRUE)));
    return FALSE;
  }
  if (count($term) > 1) {
    tripal_report_error('tripal_chado', TRIPAL_ERROR, "chado_insert_property: " .
      "Multiple terms found. Cannot add the property. Property was described " .
      "by: %property.", 
    array('%property' => print_r($property, TRUE)));
    return FALSE;
  }


  // Check that the cvalue property exists.
  if ($cvalue_id) {
    $term = chado_select_record('cvterm', array('cvterm_id'), array('cvterm_id' => $cvalue_id), $options);
    if (!$term or count($term) == 0) {
      tripal_report_error('tripal_chado', TRIPAL_ERROR, "chado_insert_property: " .
        "Cannot find the term for the property value described by: %property.", 
      array('%property' => print_r($property, TRUE)));
      return FALSE;
    }
    $values['cvalue'] = $cvalue_id;
  }


  // Get the foreign key for this property table.
  $table_desc = chado_get_schema($base_table . 'prop');
  $fkcol = key($table_desc['foreign keys'][$base_table]['columns']);

  // Add the property to the record.
  $values = array(
    $fkcol => $base_id,
    'type_id' => $values,
    'value' => $value,
    'rank' => $rank,
  );
  $result = chado_insert_record($base_table . 'prop', $values);
  return $result;
}