Adds a new publication to the Chado, along with all properties and database cross-references. If the publication does not already exist in Chado then it is added. If it does exist nothing is done. If the $update parameter is TRUE then the publication is updated if it exists.

Parameters

$pub_details: An associative array containing all of the details about the publication.

$action: This variable will get set to a text value indicating the action that was performed. The values include 'skipped', 'inserted', 'updated' or 'error'.

$do_contact: Optional. Set to TRUE if a contact entry should be added to the Chado contact table for authors of the publication.

$update_if_exists: Optional. If the publication already exists then this function will return without adding a new publication. However, set this value to TRUE to force the function to pudate the publication using the $pub_details that are provided.

Return value

If the publication already exists, is inserted or updated then the publication ID is returned, otherwise FALSE is returned. If the publication already exists and $update_if_exists is not TRUE then the $action variable is set to 'skipped'. If the publication already exists and $update_if_exists is TRUE and if the update was successful then $action is set to 'updated'. Otherwise on successful insert the $action variable is set to 'inserted'. If the function failes then the $action variable is set to 'error'

File

tripal_chado/includes/loaders/tripal_chado.pub_importers.inc, line 973

Management of importers

Code

function tripal_pub_add_publication($pub_details, &$action, $do_contact = FALSE, $update_if_exists = FALSE) {
  $pub_id = 0;

  if (!is_array($pub_details)) {
    return FALSE;
  }

  // before proceeding check to see if the publication already exists. If there is only one match
  // and the $update_if_exists is NOT set then return FALSE
  $pub_ids = chado_publication_exists($pub_details);

  if (count($pub_ids) == 1 and !$update_if_exists) {
    tripal_report_error('tripal_pub', TRIPAL_NOTICE, 
    "There is a publication that is a duplicate of this publication. Cannot continue. It either " .
      "has a matching Dbxref (e.g. PubMed ID), a non-unique citation or matches on the unique  " .
      "constraint set by the Tripal publication module configuration page. \nCitation: %title %dbxref.\nMatching Pub id: %ids", 
    array(
      '%title' => $pub_details['Citation'],
      '%dbxref' => $pub_details['Publication Dbxref'],
      '%ids' => implode(",", $pub_ids),
    )
    );
    $action = 'skipped';
    return FALSE;
  }
  // if we have more than one matching pub then return an error as we don't know which to update even if
  // update_if_exists is set to TRUE
  if (count($pub_ids) > 1) {
    tripal_report_error('tripal_pub', TRIPAL_NOTICE, 
    "There are %num publications that are duplicates of this publication. They either " .
      "have a matching Dbxref (e.g. PubMed ID) or match on the unique constraint set by the Tripal publication module " .
      "configuration page.  \nCitation: %title %dbxref.\nMatching Pub ids: %ids", 
    array(
      '%num' => count($pub_ids),
      '%title' => $pub_details['Citation'],
      '%dbxref' => $pub_details['Publication Dbxref'],
      '%ids' => implode(",", $pub_ids),
    )
    );
    $action = 'skipped';
    return FALSE;
  }
  if (count($pub_ids) == 1 and $update_if_exists) {
    $pub_id = $pub_ids[0];
  }

  // get the publication type (use the first publication type)
  if (array_key_exists('Publication Type', $pub_details)) {
    $pub_type = '';
    if (is_array($pub_details['Publication Type'])) {
      $pub_type = $pub_details['Publication Type'][0];
    }
    else {
      $pub_type = $pub_details['Publication Type'];
    }
    $identifiers = array(
      'name' => $pub_type,
      'cv_id' => array(
        'name' => 'tripal_pub'
      ),
    );
    $pub_type = chado_get_cvterm($identifiers);
  }
  else {
    tripal_report_error('tripal_pub', TRIPAL_ERROR, 
    "The Publication Type is a required property but is missing", array());
    $action = 'error';
    return FALSE;
  }
  if (!$pub_type) {
    tripal_report_error('tripal_pub', TRIPAL_ERROR, "Cannot find publication type: '%type'", 
    array('%type' => $pub_details['Publication Type'][0]));
    $action = 'error';
    return FALSE;
  }

  // the series name field in the pub table is only 255 characters, so we should trim just in case
  $series_name = '';
  if (array_key_exists('Series_Name', $pub_details)) {
    $series_name = substr($pub_details['Series Name'], 0, 255);
  }
  if (array_key_exists('Journal Name', $pub_details)) {
    $series_name = substr($pub_details['Journal Name'], 0, 255);
  }

  // build the values array for inserting or updating
  $values = array(
    'title' => $pub_details['Title'],
    'volume' => (isset($pub_details['Volume'])) ? $pub_details['Volume'] : '',
    'series_name' => $series_name,
    'issue' => (isset($pub_details['Issue'])) ? $pub_details['Issue'] : '',
    'pyear' => (isset($pub_details['Year'])) ? $pub_details['Year'] : '',
    'pages' => (isset($pub_details['Pages'])) ? $pub_details['Pages'] : '',
    'uniquename' => $pub_details['Citation'],
    'type_id' => $pub_type->cvterm_id,
  );

  // if there is no pub_id then we need to do an insert.
  if (!$pub_id) {
    $options = array('statement_name' => 'ins_pub_tivoseispypaunty');
    $pub = chado_insert_record('pub', $values, $options);
    if (!$pub) {
      tripal_report_error('tripal_pub', TRIPAL_ERROR, "Cannot insert the publication with title: %title", 
      array('%title' => $pub_details['Title']));
      $action = 'error';
      return FALSE;
    }
    $pub_id = $pub['pub_id'];
    $action = 'inserted';
  }

  // if there is a pub_id and we've been told to update, then do the update
  if ($pub_id and $update_if_exists) {
    $match = array('pub_id' => $pub_id);
    $options = array('statement_name' => 'up_pub_tivoseispypaunty');
    $success = chado_update_record('pub', $match, $values, $options);
    if (!$success) {
      tripal_report_error('tripal_pub', TRIPAL_ERROR, "Cannot update the publication with title: %title", 
      array('%title' => $pub_details['Title']));
      $action = 'error';
      return FALSE;
    }
    $action = 'updated';
  }

  // before we add any new properties we need to remove those that are there if this
  // is an update.  The only thing we don't want to remove are the 'Publication Dbxref'
  if ($update_if_exists) {
    $sql = "
      DELETE FROM {pubprop}
      WHERE
        pub_id = :pub_id AND
        NOT type_id in (
          SELECT cvterm_id
          FROM {cvterm}
          WHERE name = 'Publication Dbxref'
        )
    ";
    chado_query($sql, array(':pub_id' => $pub_id));
  }

  // iterate through the properties and add them
  foreach ($pub_details as $key => $value) {
    // the pub_details may have the raw search data (e.g. in XML from PubMed.  We'll irgnore this for now
    if ($key == 'raw') {
      continue;
    }

    // get the cvterm by name
    $identifiers = array(
      'name' => $key,
      'cv_id' => array(
        'name' => 'tripal_pub'
      ),
    );
    $cvterm = chado_get_cvterm($identifiers);

    // if we could not find the cvterm by name then try by synonym
    //$cvterm = chado_get_cvterm(array('name' => $key, 'cv_id' => array('name' => 'tripal_pub')));
    if (!$cvterm) {
      $identifiers = array(
        'synonym' => array(
          'name' => $key,
          'cv_name' => 'tripal_pub'
        )
      );
      $cvterm = chado_get_cvterm($identifiers);
    }
    if (!$cvterm) {
      tripal_report_error('tripal_pub', TRIPAL_ERROR, "Cannot find term: '%prop'. Skipping.", array('%prop' => $key));
      continue;
    }

    // skip details that won't be stored as properties
    if ($key == 'Author List') {
      tripal_pub_add_authors($pub_id, $value, $do_contact);
      continue;
    }
    if ($key == 'Title' or $key == 'Volume' or $key == 'Journal Name' or $key == 'Issue' or 
      $key == 'Year' or $key == 'Pages') {
      continue;
    }

    $success = 0;
    if (is_array($value)) {
      foreach ($value as $subkey => $subvalue) {
        // if the key is an integer then this array is a simple list and
        // we will insert using the primary key. Otheriwse, use the new key
        if (is_int($subkey)) {
          $success = chado_insert_property(
          array('table' => 'pub', 'id' => $pub_id), 
          array('type_name' => $key, 'cv_name' => 'tripal_pub', 'value' => $subvalue)
          );
        }
        else {
          $success = chado_insert_property(
          array('table' => 'pub', 'id' => $pub_id), 
          array('type_name' => $subkey, 'cv_name' => 'tripal_pub', 'value' => $subvalue)
          );
        }
      }
    }
    else {
      $success = chado_insert_property(
      array('table' => 'pub', 'id' => $pub_id), 
      array('type_name' => $key, 'cv_name' => 'tripal_pub', 'value' => $value), 
      array('update_if_present' => TRUE)
      );
    }
    if (!$success) {
      tripal_report_error('tripal_pub', TRIPAL_ERROR, "Cannot add property '%prop' to publication. Skipping.", 
      array('%prop' => $key));
      continue;
    }
  }

  return $pub_id;
}