recommender.module in Recommender API 7.5

Providing generic recommender system algorithms.

File

recommender.module

<?php

/**
 * @file
 * Providing generic recommender system algorithms.
 */
define('TOP_N_LIMIT', 100);

///////////////////////    Helper functions    /////////////////////

/**
 * Remove recommenders. Usually used in calling module's hook_uninstall()
 * @param $apps the application name to be removed.
 * @return null
 */
function recommender_purge($recommenders) {
  if (func_num_args() > 1) {
    $recommenders = func_get_args();

    // if used as recommender_purge('app1', 'app2', ...);
  }
  else {
    if (!is_array($recommenders)) {
      $recommenders = array(
        $recommenders,
      );

      // if used as recommender_purge('app');
    }
  }

  // finally, used as recommender_purge(array('app1', 'app2', ...);
  foreach ($recommenders as $recommender) {
    db_query("DELETE FROM {recommender_preference} WHERE recommender=:recommender", array(
      ':recommender' => $recommender,
    ));
    db_query("DELETE FROM {recommender_similarity} WHERE recommender=:recommender", array(
      ':recommender' => $recommender,
    ));
    db_query("DELETE FROM {recommender_prediction} WHERE recommender=:recommender", array(
      ':recommender' => $recommender,
    ));
  }
}

/**
 * Return a list of items that are top similar with $id
 * @param $app_name The $app_name for the depending modules
 * @param $id usually the $node_id of the target item.
 * @param $top_n how many similar items to return
 * @param $test_func optional function to test whether an item satisfy some conditions
 * @return an array of the most similar items to $id.
 */

//function recommender_top_similarity($app_name, $id, $top_n, $test_func=NULL) {

//  return _recommender_generic_top($app_name, $id, $top_n, '{recommender_similarity}', $test_func);

//}

/**
 * Return a list of items that are top prediction for $id
 * @param $app_name The $app_name for the depending modules
 * @param $id usually the $node_id of the target item.
 * @param $top_n how many predictions to return
 * @param $test_func optional function to test whether an item satisfy some conditions
 * @return an array of the most similar items to $id.
 */

//function recommender_top_prediction($app_name, $id, $top_n, $test_func=NULL) {

//  return _recommender_generic_top($app_name, $id, $top_n, '{recommender_prediction}', $test_func);

//}

//function _recommender_generic_top($recommender, $id, $top_n, $table, $test_func=NULL) {

//  $list = array();
//  $result = db_query_range("SELECT target_id id, score FROM $table WHERE recommender=:recommender AND source_id=:entity_id
//    ORDER BY score DESC, updated DESC, target_id ASC", 0, TOP_N_LIMIT, array(':recommender' => $recommender, ':entity_id' => $id));
//
//  while (($item = $result->fetchAssoc()) && count($list) < $top_n) {
//    if ($test_func===NULL || call_user_func($test_func, $item)) {
//      $list[] = $item;
//    }
//  }
//  return $list;

//}
function recommender_create_record($recommender, $description = NULL, $override = array()) {
  $all_recommender_info = module_invoke_all('recommender_info');

  //var_dump($all_recommender_info);
  if (isset($all_recommender_info[$recommender])) {
    $recommender_info = $all_recommender_info[$recommender];
  }
  else {
    return FALSE;
  }
  if (!isset($recommender_info['title']) || !isset($recommender_info['algorithm'])) {
    return FALSE;
  }
  if ($description == NULL) {
    $description = t('Compute recommendations: !recommender', array(
      '!recommender' => $recommender_info['title'],
    ));
  }
  if (!empty($override)) {
    $recommender_info = array_merge($recommender_info, $override);
  }
  return computing_create_record('recommender', $recommender_info['algorithm'], $description, array(
    'ids1' => $recommender,
    'inputjson' => drupal_json_encode($recommender_info),
  ));
}

/**
 * @param string $type
 *  could be 'preference', 'prediction', 'similarity'
 * @param string $recommender
 *  any recommender name.
 * @param array $rows
 *  an array of values, each value is a tuple of [source_id, target_id, score, updated], where the last 2 columns are optional.
 */
function recommender_insert_rows($type, $recommender, $rows) {
  $table_name = "recommender_{$type}";
  $insert = db_insert($table_name)
    ->fields(array(
    'recommender',
    'source_id',
    'target_id',
    'score',
    'updated',
  ));
  foreach ($rows as $row) {
    $insert
      ->values(array(
      'recommender' => $recommender,
      'source_id' => $row[0],
      'target_id' => $row[1],
      'score' => isset($row[2]) ? $row[2] : 1,
      'updated' => isset($row[3]) ? $row[3] : time(),
    ));
  }
  $insert
    ->execute();
}
function recommender_precompute_mlt($mlt_delta, $nid_list) {
  if (!module_exists('apachesolr_search')) {
    return FALSE;
  }
  $block = apachesolr_search_mlt_block_load($mlt_delta);
  if ($block) {
    $env_id = !empty($block['mlt_env_id']) ? $block['mlt_env_id'] : '';
    try {
      $solr = apachesolr_get_solr($env_id);
      foreach ($nid_list as $nid) {
        $docs = apachesolr_search_mlt_suggestions($block, apachesolr_document_id($nid), $solr);
        if (!empty($docs)) {
          db_delete('recommender_similarity')
            ->condition('source_id', $nid)
            ->condition('recommender', $mlt_delta)
            ->execute();
          $rows = array();
          foreach ($docs as $doc) {

            // attention: here we can't retrieve similarity score because MLT block don't specify that.
            // to retrieve similarity score, use customized query.
            $rows[] = array(
              $nid,
              $doc->entity_id,
            );
          }
          recommender_insert_rows('similarity', $mlt_delta, $rows);
        }

        #var_dump($nid, $docs);
      }
    } catch (Exception $e) {
      watchdog('Apache Solr', nl2br(check_plain($e
        ->getMessage())), NULL, WATCHDOG_ERROR);
    }
  }
}

////////////////////////////       DRUPAL RELATED FUNCTIONS          //////////////////////////

// Implements hook_permission().
function recommender_permission() {
  return array(
    "administer recommender" => array(
      'title' => t('Administer recommender'),
      'description' => t('You need this permission for any Recommender API related operations.'),
    ),
  );
}

// Implements hook_menu().
function recommender_menu() {
  $items = array();
  $items['admin/config/search/recommender'] = array(
    'title' => 'Recommender',
    'description' => 'Configuration and trigger recommender modules',
    'page callback' => 'system_admin_menu_block_page',
    'access arguments' => array(
      'administer site configuration',
    ),
    'file' => 'system.admin.inc',
    'file path' => drupal_get_path('module', 'system'),
  );
  $items['admin/config/search/recommender/admin'] = array(
    'title' => 'Admin',
    'description' => 'Configuration and trigger recommender modules',
    'page callback' => 'drupal_get_form',
    'page arguments' => array(
      'recommender_settings_form',
    ),
    'access arguments' => array(
      'administer recommender',
    ),
    'file' => 'recommender.admin.inc',
  );

  //  $items['recommender/run'] = array(
  //    'title' => 'Running recommender',
  //    'page callback' => 'recommender_run',
  //    'access arguments' => array('administer recommender'),
  //    'type' => MENU_CALLBACK,
  //   );
  return $items;
}
function recommender_cron() {

  // if cron is null, then never run cron for the app.
  // else if recommender never get executed (execution_id=null), then run it.
  // otherwise, run only when last command (c.created) is before current time minus cron.

  /*$rows = db_query("SELECT a.name FROM {recommender_app} a LEFT OUTER JOIN {async_command} c ON a.execution_id = c.id WHERE cron IS NOT NULL AND (a.execution_id IS NULL OR c.created + a.cron < :current)", array(':current' => time()));
    foreach ($rows as $row) {
      recommender_create_command($row->name);
    }*/

  // TODO: use either variables to save cron, or remove cron settings entirely.
}

/**
 * Implements hook_views_api().
 */
function recommender_views_api() {
  return array(
    'api' => 3,
  );
}

/**
 * Provide default views template for helper modules.
 * Helper modules can choose either to use "export views" or use this function to generate default views.
 *
 * @param $view_name
 * @param $view_human_name
 * @param $view_description
 * @param $base_table   either recommender_similarity or recommender_prediction.
 * @param $base_entity_type   usually either 'node' or 'users'
 * @param $base_entity_field  if 'node' then 'title', if 'users' then 'name'
 * @param $argument_type  either 'node' or 'current_user'
 * @param $app_name
 * @return \view
 */
function recommender_default_view_template($view_name, $view_human_name, $view_description, $base_table, $base_entity_type, $base_entity_field, $argument_type, $app_name) {
  $view = new view();
  $view->name = $view_name;
  $view->description = $view_description;
  $view->tag = 'recommendation';
  $view->base_table = $base_table;
  $view->human_name = $view_human_name;
  $view->core = 7;
  $view->api_version = '3.0';
  $view->disabled = TRUE;

  /* Edit this to true to make a default view disabled initially */

  /* Display: Master */
  $handler = $view
    ->new_display('default', 'Master', 'default');
  $handler->display->display_options['title'] = $view_human_name;
  $handler->display->display_options['access']['type'] = 'none';
  $handler->display->display_options['cache']['type'] = 'none';
  $handler->display->display_options['query']['type'] = 'views_query';
  $handler->display->display_options['exposed_form']['type'] = 'basic';
  $handler->display->display_options['pager']['type'] = 'full';
  $handler->display->display_options['pager']['options']['items_per_page'] = '5';
  $handler->display->display_options['style_plugin'] = 'list';
  $handler->display->display_options['row_plugin'] = 'fields';

  /* Relationship */
  $handler->display->display_options['relationships']['target_id']['id'] = 'target_id';
  $handler->display->display_options['relationships']['target_id']['table'] = $base_table;
  $handler->display->display_options['relationships']['target_id']['field'] = 'target_id';
  $handler->display->display_options['relationships']['target_id']['required'] = 1;
  $handler->display->display_options['relationships']['target_id']['base_entity_type'] = $base_entity_type;

  /* Field */
  $handler->display->display_options['fields'][$base_entity_field]['id'] = $base_entity_field;
  $handler->display->display_options['fields'][$base_entity_field]['table'] = $base_entity_type;
  $handler->display->display_options['fields'][$base_entity_field]['field'] = $base_entity_field;
  $handler->display->display_options['fields'][$base_entity_field]['relationship'] = 'target_id';
  $handler->display->display_options['fields'][$base_entity_field]['label'] = '';
  $handler->display->display_options['fields'][$base_entity_field]['alter']['alter_text'] = 0;
  $handler->display->display_options['fields'][$base_entity_field]['alter']['make_link'] = 0;
  $handler->display->display_options['fields'][$base_entity_field]['alter']['absolute'] = 0;
  $handler->display->display_options['fields'][$base_entity_field]['alter']['external'] = 0;
  $handler->display->display_options['fields'][$base_entity_field]['alter']['replace_spaces'] = 0;
  $handler->display->display_options['fields'][$base_entity_field]['alter']['trim'] = 0;
  $handler->display->display_options['fields'][$base_entity_field]['alter']['nl2br'] = 0;
  $handler->display->display_options['fields'][$base_entity_field]['alter']['word_boundary'] = 1;
  $handler->display->display_options['fields'][$base_entity_field]['alter']['ellipsis'] = 1;
  $handler->display->display_options['fields'][$base_entity_field]['alter']['strip_tags'] = 0;
  $handler->display->display_options['fields'][$base_entity_field]['alter']['html'] = 0;
  $handler->display->display_options['fields'][$base_entity_field]['element_label_colon'] = 0;
  $handler->display->display_options['fields'][$base_entity_field]['element_default_classes'] = 1;
  $handler->display->display_options['fields'][$base_entity_field]['hide_empty'] = 1;
  $handler->display->display_options['fields'][$base_entity_field]['empty_zero'] = 0;
  if ($base_entity_type == 'node') {
    $handler->display->display_options['fields']['title']['link_to_node'] = 1;
  }
  elseif ($base_entity_type == 'users') {
    $handler->display->display_options['fields']['name']['link_to_user'] = 1;
    $handler->display->display_options['fields']['name']['overwrite_anonymous'] = 0;
  }

  /* Sort criterion */
  $handler->display->display_options['sorts']['score']['id'] = 'score';
  $handler->display->display_options['sorts']['score']['table'] = $base_table;
  $handler->display->display_options['sorts']['score']['field'] = 'score';
  $handler->display->display_options['sorts']['score']['order'] = 'DESC';

  /* Contextual filter */
  $handler->display->display_options['arguments']['source_id']['id'] = 'source_id';
  $handler->display->display_options['arguments']['source_id']['table'] = $base_table;
  $handler->display->display_options['arguments']['source_id']['field'] = 'source_id';
  $handler->display->display_options['arguments']['source_id']['default_action'] = 'default';
  $handler->display->display_options['arguments']['source_id']['default_argument_type'] = $argument_type;
  $handler->display->display_options['arguments']['source_id']['default_argument_skip_url'] = 0;
  $handler->display->display_options['arguments']['source_id']['summary']['number_of_records'] = '0';
  $handler->display->display_options['arguments']['source_id']['summary']['format'] = 'default_summary';
  $handler->display->display_options['arguments']['source_id']['summary_options']['items_per_page'] = '25';
  $handler->display->display_options['arguments']['source_id']['break_phrase'] = 0;
  $handler->display->display_options['arguments']['source_id']['not'] = 0;

  /* Filter criterion: Recommender Application: Application name */
  $handler->display->display_options['filters']['name']['id'] = 'name';
  $handler->display->display_options['filters']['name']['table'] = 'recommender_app';
  $handler->display->display_options['filters']['name']['field'] = 'name';
  $handler->display->display_options['filters']['name']['value'] = array(
    $app_name => $app_name,
  );

  /* Filter criterion */
  $handler->display->display_options['filters']['score']['id'] = 'score';
  $handler->display->display_options['filters']['score']['table'] = $base_table;
  $handler->display->display_options['filters']['score']['field'] = 'score';
  $handler->display->display_options['filters']['score']['operator'] = '>';
  $handler->display->display_options['filters']['score']['value']['value'] = '0';

  /* Display: Block */
  $handler = $view
    ->new_display('block', 'Block', 'block');
  return $view;
}

Functions

Name	Description
recommender_create_record
recommender_cron
recommender_default_view_template	Provide default views template for helper modules. Helper modules can choose either to use "export views" or use this function to generate default views.
recommender_insert_rows
recommender_menu
recommender_permission
recommender_precompute_mlt
recommender_purge	Remove recommenders. Usually used in calling module's hook_uninstall()
recommender_views_api	Implements hook_views_api().

Constants

Name	Description
TOP_N_LIMIT	@file Providing generic recommender system algorithms.