tripal/base/tripal_cv/trees.php

<?php

/**
*
* @ingroup tripal_cv
*/
function tripal_cv_show_browser() {
  
   $content = drupal_get_form('tripal_cv_list_form');
   $content .= "
      <div id=\"cv_browser\"></div>
   ";
   return $content;
}


/**
 * Generates JSON used for generating an exapandable tree of terms from
 * a controlled vocabulary that has associated counts. 
 *
 * The progammer must first create a materialized view that
 * will generate count data for a given controlled vocabulary.  For example, the Tripal
 * Analysis GO creates a materialized view for counting Gene Ontology assignments
 * to features.  This view is created on install of the module and is named
 * 'go_count_analysis'.
 *
 * Second, the progammer must add an HTML 'div' box to the desired page
 * with a class name of 'tripal_cv_tree', and an id of the following format:
 *
 *  tripal_[module_name]_cv_tree_[unique id]
 *
 * where [module_name] is the name of the tripal module (e.g. tripal_analyisis_go)
 * and [unique id] is some unique identifier that the contolling module 
 * recognizes. This string is the $tree_id variable passed as the first argument
 * to the function.  For example, the Tripal GO Analysis module generates 
 * tree ids of the form:
 * 
 *  tripal_analysis_go_cv_tree_10_2_bp
 * 
 * In this case the module that will manage this tree is identified as 'tripal_analysis_go' and within
 * the [unique id] portion contains the
 * organism_id (e.g. 10), analysis_id (e.g. 2) and tree type (bp = biological process). 
 *
 * Second, the programmer must then define a hook in the controlling module for setting
 * some options used to build the chart.  The hook has the form:  hook_cv_tree($tree_id).
 * This hook should accept the full $tree_id as the single parameter.  For the Tripal
 * Analysis GO module the hook is named:  tripal_analysis_go_cv_tree.  
 *
 * The array returned by this hook must have the following fields: 
 *  - cv_id 
 *      the cv_id for the controlled vocabulary
 *  - count_mview
 *      the name of the materialized view that contains the count data
 *      this materialized view must have at least two columns, one with the cvterm_id
 *      for each term and a second column containing the counts. The tree will only
 *      be expanded to include child terms that have counts.
 *  - cvterm_id_column
 *      the column name in the materialized view that contains
 *      the cvterm_ids
 *  - count_column
 *      the column name in the materialized view that contains the
 *      counts
 *  - filter
 *      an SQL compatible WHERE clause string (whithout the word 'WHERE')
 *      that can be used for filtering the records in the materialized view.
 *  - label
 *      the title for the tree
 *
 * Example from the tripal_analysis_go module:
 * @code
 *  function tripal_analysis_go_cv_tree($tree_id){
 * 
 *   $organism_id = preg_replace("/^tripal_analysis_go_cv_tree_(\d+)-(\d+)_(bp|cc|mf)$/","$1",$tree_id);
 *   $analysis_id = preg_replace("/^tripal_analysis_go_cv_tree_(\d+)-(\d+)_(bp|cc|mf)$/","$2",$tree_id);
 *   $type        = preg_replace("/^tripal_analysis_go_cv_tree_(\d+)-(\d+)_(bp|cc|mf)$/","$3",$tree_id);
 * 
 *   if(strcmp($type,'mf')==0){
 *      $class = 'molecular_function';
 *   }
 *   if(strcmp($type,'cc')==0){
 *      $class = 'cellular_component';
 *   }
 *   if(strcmp($type,'bp')==0){
 *      $class = 'biological_process';
 *   }
 * 
 *   $options = array(
 *      cv_id            => tripal_cv_get_cv_id($class),
 *      count_mview      => 'go_count_analysis',
 *      cvterm_id_column => 'cvterm_id',
 *      count_column     => 'feature_count',
 *      filter           => "CNT.organism_id = $organism_id AND CNT.analysis_id = $analysis_id",
 *      label            => 'Features',
 *   );
 *   return $options;
 * }
 *
 * @endcode
 *
 * @param $tree_id
 *   The unique identifier for the tree
 *
 * @return
 *   JSON array needed for the jsTree package for generating expandable trees.
 *
 * With these three components (materialized view, a 'div' box with proper CSS class and ID, and a hook_cv_tree)
 * a tree will be created on the page.  There is no need to call this function directly.
 *
 * @ingroup tripal_cv
 */
function tripal_cv_tree($tree_id){
  // parse out the tripal module name from the chart_id to find out 
  // which Tripal "hook" to call:
  $tripal_mod = preg_replace("/^(tripal_.+?)_cv_tree_(.+)$/","$1",$tree_id);
  if($tripal_mod){
     $callback = $tripal_mod . "_cv_tree";

     // now call the function in the module responsible for the tree.  This 
     // should call the tripal_cv_init_cv with the proper parameters set for
     // getting the cv_id of the vocabulary to use
     $opt = call_user_func_array($callback,array($tree_id));

     // we only need to return the cv_id for this function call.
     $json_array[] = $opt[cv_id];
  }
  $json_array[] = $tree_id;
  return drupal_json($json_array);
}


/**
*
* @ingroup tripal_cv
*/
function tripal_cv_update_tree() {
   $content = array();
   $ontology = 'sequence';

   # get the id of the term to look up
   $cv = check_plain($_REQUEST['cv']);
   $term = check_plain($_REQUEST['term']);
   $tree_id = check_plain($_REQUEST['tree_id']);

   # get the options needed for this tree from the tripal module that 
   # wants to create the tree
   $tripal_mod = preg_replace("/^(tripal_.+?)_cv_tree_(.+)$/","$1",$tree_id);
   if($tripal_mod){
      $callback = $tripal_mod . "_cv_tree";
      $opt = call_user_func_array($callback,array($tree_id));
   }

   # get the CV root terms
   if(strcmp($term,'root')==0){
      if(!$cv){
        $cv = $opt[cv_id];
      }
      $content = tripal_cv_init_tree($cv,$opt[count_mview],
         $opt[cvterm_id_column],$opt[count_column],$opt[filter],$opt[label]);
   } 
   # get the children terms
   else {
      $content = tripal_cv_get_term_children($term,$opt[count_mview],
         $opt[cvterm_id_column],$opt[count_column],$opt[filter],$opt[label]);
   }
   drupal_json($content);
}
/**
* Generates JSON needed for jsTree Root-level Branches
*
* This function returns the JSON array for the jsTree 
*    jQuery code that builds a tree for browsing the ontology.  This function
*    should be called to generate the root level branches of the tree.
*
* @ingroup tripal_cv
*/
function tripal_cv_init_tree($cv_id,$cnt_table = null, $fk_column = null,
   $cnt_column = null, $filter = null, $label = null) {

   // get the list of root terms for the provided CV
   $sql = "
      SELECT *
      FROM {cv_root_mview} CRM
      WHERE cv_id = %d
   ";
   $previous_db = tripal_db_set_active('chado');
   $results = db_query($sql,$cv_id);
   tripal_db_set_active($previous_db); 

   // prepare the SQL statement that will allow us to pull out count 
   // information for each term in the tree.
   if($cnt_table){
      if(!$filter){
         $filter = '(1=1)'; 
      }
      $cnt_sql = "
         SELECT CVT.name, CVT.cvterm_id, CNT.$cnt_column as num_items
         FROM {$cnt_table} CNT 
          INNER JOIN cvterm CVT on CNT.$fk_column = CVT.cvterm_id 
         WHERE $filter AND CVT.cvterm_id = %d
         ORDER BY $cnt_column desc
      ";
   }
 
   while ($term = db_fetch_object($results)) {
      $name = $term->name;
      $count = 0;
      if($cnt_table){
         $previous_db = tripal_db_set_active('chado');
         $cnt_results = db_query($cnt_sql,$term->cvterm_id);
         tripal_db_set_active($previous_db); 
         while($cnt = db_fetch_object($cnt_results)){
            $count += $cnt->cnt;
         }
         if($count > 0){
            $name .= " ($count $label(s))";
         }
      } 
      $content[] = array(
           'attributes' => array (
           'id' => $term->cvterm_id,
        ),
        state => 'closed',
        data => $name,
        children => array (),
      );
   }

   return $content;

}
/**
*  Generates SON needed for jsTree -expanding a term to view children
*
*  This function returns the JSON array for the jsTree 
*    jQuery code when expanding a term to view it's children.
*
* @ingroup tripal_cv_api
*/
function tripal_cv_get_term_children($cvterm_id,$cnt_table = null, 
   $fk_column = null,$cnt_column = null, $filter = null, $label = null) {
   # get the children for the term provided
   $sql = "
      SELECT CVTR.cvterm_relationship_id,CVTR.subject_id,
         CVT1.name as subject_name, CVT3.name as type_name, CVTR.type_id, 
         CVT2.name as object_name,CVTR.object_id 
      FROM {cvterm_relationship} CVTR
         INNER JOIN CVTerm CVT1 on CVTR.subject_id = CVT1.cvterm_id
         INNER JOIN CVTerm CVT2 on CVTR.object_id = CVT2.cvterm_id
         INNER JOIN CVTerm CVT3 on CVTR.type_id = CVT3.cvterm_id
         INNER JOIN CV on CV.cv_id = CVT1.cv_id
      WHERE CVTR.object_id = %d
      ORDER BY CVT1.name
   ";
   $previous_db = tripal_db_set_active('chado');
   $results = db_query($sql,$cvterm_id);
   tripal_db_set_active($previous_db);


   // prepare the SQL statement that will allow us to pull out count 
   // information for each term in the tree.
   if($cnt_table){
      if(!$filter){
         $filter = '(1=1)'; 
      }
      $cnt_sql = "
         SELECT CVT.name, CVT.cvterm_id, CNT.$cnt_column as num_items
         FROM {$cnt_table} CNT 
          INNER JOIN cvterm CVT on CNT.$fk_column = CVT.cvterm_id 
         WHERE $filter AND CVT.cvterm_id = %d
         ORDER BY $cnt_column desc
      ";
   }
   // populate the JSON content array
   while ($term = db_fetch_object($results)) {
      // count the number of items per term if requested
      $name = $term->subject_name;
      $count = 0;
      if($cnt_table){
         $previous_db = tripal_db_set_active('chado');
         $cnt_results = db_query($cnt_sql,$term->subject_id);
         tripal_db_set_active($previous_db); 
         while($cnt = db_fetch_object($cnt_results)){
            $count += $cnt->num_items;
         }
         if($count > 0){
            $name .= " (".number_format($count)." $label)";
            // check if we have any children if so then set the value
            $previous_db = tripal_db_set_active('chado');
            $children = db_fetch_object(db_query($sql,$term->subject_id));
            tripal_db_set_active($previous_db);
            $state = 'leaf';
            if($children){
               $state = 'closed';
            }
            $content[] = array(
               'attributes' => array (
                  'id' => $term->subject_id,
               ),
               state => $state,
               data => $name,
               children => array(),
            );
         }
      } else {
         // check if we have any children if so then set the value
         $previous_db = tripal_db_set_active('chado');
         $children = db_fetch_object(db_query($sql,$term->subject_id));
         tripal_db_set_active($previous_db);
         $state = 'leaf';
         if($children){
            $state = 'closed';
         }
         $content[] = array(
            'attributes' => array (
               'id' => $term->subject_id,
            ),
            state => $state,
            data => $name,
            children => array(),
         );
      }
   }
   $content[] = $cnt_sql;
   return $content;
}
/**
* 
* @ingroup tripal_cv
*/
function tripal_cv_init_browser($cv_id) {

   $content = "
        <div id=\"tripal_cv_cvterm_info_box\">
           <a href=\"#\" onclick=\"$('#tripal_cv_cvterm_info_box').hide()\" style=\"float: right\">Close [X]</a>
           <h3>Term Information</h3>
           <div id=\"tripal_cv_cvterm_info\"></div>
        </div>
        <div id=\"tripal_ajaxLoading\" style=\"display:none\">
           <div id=\"loadingText\">Loading...</div>
           <img src=\"$url\">
        </div> 
         <h3>Tree Browser</h3>
        <div id=\"browser\"</div></div>
   ";

   drupal_json(array('update' => "$content"));
}
/**
*
* @ingroup tripal_cv
*/
function tripal_cv_cvterm_info($cvterm_id){

   # get the id of the term to look up
   $cv = check_plain($_REQUEST['cv']);
   $tree_id = check_plain($_REQUEST['tree_id']);

   // first get any additional information to add to the cvterm
   if(strcmp($tree_id,'undefined')!=0){
      $tripal_mod = preg_replace("/^(tripal_.+?)_cv_tree_(.+)$/","$1",$tree_id);
      if($tripal_mod){
         $callback = $tripal_mod . "_cvterm_add";
         $opt = call_user_func_array($callback,array($cvterm_id,$tree_id));
      }
   }

   $sql = "
      SELECT CVT.name as cvtermname, CVT.definition, CV.name as cvname,
         DBX.accession,DB.urlprefix,DB.db_id,DB.name as dbname
      FROM {CVTerm} CVT
        INNER JOIN CV on CVT.cv_id = CV.cv_id
        INNER JOIN dbxref DBX on CVT.dbxref_id = DBX.dbxref_id
        INNER JOIN DB on DBX.db_id = DB.db_id
      WHERE CVT.cvterm_id = %d
   ";
   $previous_db = tripal_db_set_active('chado');
   $cvterm = db_fetch_object(db_query($sql,$cvterm_id));
   tripal_db_set_active($previous_db);
   $sql = "
      SELECT CVTS.synonym, CVT.name as cvname
      FROM {cvtermsynonym} CVTS
        INNER JOIN cvterm CVT on CVTS.type_id = CVT.cvterm_id
      WHERE CVTS.cvterm_id = %d
    
   ";
   $previous_db = tripal_db_set_active('chado');
   $results = db_query($sql,$cvterm_id);
   tripal_db_set_active($previous_db);
   while($synonym = db_fetch_object($results)){
      $synonym_rows .= "<b>$synonym->cvname:</b>  $synonym->synonym<br>";
   }
   $accession = $cvterm->accession;
   if($cvterm->urlprefix){
      $accession = "<a href=\"$cvterm->urlprefix$cvterm->accession\">$cvterm->accession</a>";
   }
   $content = "
      <div id=\"cvterm\">
      <table>
        <tr><th>Term</th><td>$cvterm->cvtermname</td></tr>
        <tr><th>Accession</th><td>$accession</td></tr>
        <tr><th>Ontology</th><td>$cvterm->cvname</td></tr>
        <tr><th>Definition</th><td>$cvterm->definition</td></tr>
        <tr><th>Synonyms</th><td>$synonym_rows</td></tr>
        <tr><th>Internal ID</th><td>$cvterm_id</td></tr> 
   ";

   // now add in any additional options from a hook
   if($opt){
      foreach ($opt as $key=>$value){
         $content .= "<tr><th>$key</th><td>$value</td>";
      }
   }

   // close out the information table
   $content .= "
      </table>
      </div>
   ";
   drupal_json(array('update' => $content));
}
/**
*
* @ingroup tripal_cv
*/
function tripal_cv_list_form($form_state) {

   // get a list of db from chado for user to choose
    $sql = "
      SELECT DISTINCT CV.name,CV.cv_id
      FROM {cvterm_relationship} CVTR
         INNER JOIN cvterm CVT on CVTR.object_id = CVT.cvterm_id
         INNER JOIN CV on CV.cv_id = CVT.cv_id
   ";
   $previous_db = tripal_db_set_active('chado');  // use chado database
   $results = db_query ($sql);
   tripal_db_set_active($previous_db);
   $blastdbs = array();
   $cvs[''] = '';
   while ($cv = db_fetch_object($results)){
      $cvs[$cv->cv_id] = $cv->name;
   }

   $form['db_options'] = array(
      '#type' => 'value',
      '#value' => $cvs
   );        
   $form['cv_list'] = array(
      '#title' => t('CVs with relationships'),
      '#type' => 'select',
      '#description' => t('Choose the controlled vocabulary to browse'),
      '#options' => $form['db_options']['#value'],
      '#attributes' => array(
         'onChange' => "return tripal_cv_init_browser(this)",
      )
   );
   return $form;
}