rankeval.model package — RankEval 0.00 documentation

# rankeval.model package

The `rankeval.model` module includes utilities to load a model and dump it according to several supported model’s format.

class `rankeval.model.` `RTEnsemble`(file_path, name=None, format='QuickRank', base_score=None, learning_rate=1, n_trees=None)

  Bases: `object`

  Class for efficient modelling of an ensemble-based model composed of binary regression trees.

  This class only provides the sketch of the data structure to use for storing the model. The responsibility to correctly fill these data structures is delegated to the various proxies model.

  Load the model from the file identified by file_path using the given format.

  file_path : str
    The fpath to the filename where the model has been saved
  name : str
    The name to be given to the current model
  format : [‘QuickRank’, ‘ScikitLearn’, ‘XGBoost’, ‘LightGBM’]
    The format of the model to load.
  base_score : None or float
    The initial prediction score of all instances, global bias. If None, it uses default value used by each software (0.5 XGBoost, 0.0 all the others).
  learning_rate : None or float
    The learning rate used by the model to shrinks the contribution of
      each tree. By default it is set to 1 (no shrinking at all).
  n_trees : None or int
    The maximum number of trees to load from the model. By default it is set to None, meaning the method will load all the trees.
  file : str
    The path to the filename where the model has been saved
  name : str
    The name to be given to the current model
  n_trees : integer
    The number of regression trees in the ensemble.
  n_nodes : integer
    The total number of nodes (splitting nodes and leaves) in the ensemble
  trees_root: list of integers
    Numpy array modelling the indexes of the root nodes of the regression trees composing the ensemble. The indexes refer to the following data structures: * trees_left_child * trees_right_child * trees_nodes_value * trees_nodes_feature
  trees_weight: list of floats
    Numpy array modelling the weights of the regression trees composing the ensemble.
  trees_left_child: list of integers
    Numpy array modelling the structure (shape) of the regression trees, considering only the left children. Given a node of a regression tree (a single cell in this array), the value identify the index of the left children. If the node is a leaf, the children assumes -1 value.
  trees_right_child: list of integers
    Numpy array modelling the structure (shape) of the regression trees, considering only the right children. Given a node of a regression tree (a single cell in this array), the value identify the index of the right children. If the node is a leaf, the children assumes -1 value.
  trees_nodes_value: list of integers
    Numpy array modelling either the output of a leaf node (whether the node is a leaf, in accordance with the trees_structure data structure) or the splitting value of the node in the regression trees (with respect to the feature identified by the trees_nodes_feature data structure).
  trees_nodes_feature: list of integers
    Numpy array modelling the feature-id used by the selected splitting node (or -1 if the node is a leaf).
  model : RegressionTreeEnsemble
    The loaded model as a RTEnsemble object
  `clear_cache`()

    This method is used to clear the internal cache of the model from the scoring objects. Call this method at the end of the analysis of the current model (the memory otherwise will be automatically be freed on object deletion)

  `copy`(n_trees=None)

    Create a copy of this model, with all the trees up to the given number. By default n_trees is set to None, meaning to copy all the trees

    n_trees : None or int
      The number of trees the model will have after calling this method.
    model : RTEnsemble
      The copied model, pruned from all the trees exceeding the given number of trees chosen
  `height_trees`()

    Computes the height of each tree of the model.

    heights : numpy 1d array (n_trees)
      Height of each tree
  `initialize`(n_trees, n_nodes)

    Initialize the internal data structures in order to reflect the given shape and size of the ensemble. This method should be called only by the Proxy Models (the specific format-based loader/saver)

    n_trees : integer
      The number of regression trees in the ensemble.
    n_nodes : integer
      The total number of nodes (splitting nodes and leaves) in the ensemble
  `is_leaf_node`(index)

    This method returns true if the node identified by the given index is a leaf node, false otherwise

    index : integer
      The index of the node to test
  `max_leaves`()

    Computes the maximum number of leaves across the trees of the model.

    max_leaves : int
      Maximum number of leaves
  `num_leaves`()

    Computes the number of leaves for each tree of the model.

    n_leaves : numpy 1d array (n_trees)
      Number of leaves
  `num_nodes`()

    Computes the number of nodes for each tree of the model.

    n_nodes : numpy 1d array (n_trees)
      Number of nodes
  `save`(f, format='QuickRank')

    Save the model onto the file identified by file_path, using the given model format.

    f : str
      The path to the filename where the model has to be saved
    format : str
      The format to use for saving the model
    status : bool
      Returns true if the save is successful, false otherwise
  `score`(dataset, detailed=False, cache=False)

    Score the given model on the given dataset. Depending on the detailed parameter, the scoring will be either basic (i.e., compute only the document scores) or detailed (i.e., besides computing the document scores analyze also several characteristics of the model. The scorer is cached until existance of the model instance.

    dataset : Dataset
      The dataset to be scored
    detailed : bool
      True if the model has to be scored in a detailed fashion, false otherwise
    cache : bool
      True if the scoring results has to be cached, False otherwise. Take into account that caching the results could need quite a lot of memory, and this negative effect is particularly evident when scoring multiple models on huge dataset. Default is False.
    y_pred : numpy 1d array (n_instances)
      The predictions made by scoring the model on the given dataset
    partial_y_pred : numpy 2d array (n_instances x n_trees)
      The predictions made by scoring the model on the given dataset, on a tree basis (i.e., tree by tree and instance by instance)
    y_leaves : numpy 2d array (n_instances x n_trees)
      The leaf nodes predicted by scoring the model on the given dataset, on a tree basis (i.e., tree by tree and instance by instance)

class `rankeval.model.` `ProxyQuickRank`

  Bases: `object`

  Class providing the implementation for loading/storing a QuickRank model from/to file.

  static `load`(file_path, model)

    Load the model from the file identified by file_path.

    file_path : str
      The path to the filename where the model has been saved
    model : RTEnsemble
      The model instance to fill
  static `save`(file_path, model)

    Save the model onto the file identified by file_path.

    file_path : str
      The path to the filename where the model has to be saved
    model : RTEnsemble
      The model RTEnsemble model to save on file
    status : bool
      Returns true if the save is successful, false otherwise

class `rankeval.model.` `ProxyLightGBM`

  Bases: `object`

  Class providing the implementation for loading/storing a LightGBM model from/to file.

  static `load`(file_path, model)

    Load the model from the file identified by file_path.

    file_path : str
      The path to the filename where the model has been saved
    model : RTEnsemble
      The model instance to fill
  static `save`(file_path, model)

    Save the model onto the file identified by file_path.

    file_path : str
      The path to the filename where the model has to be saved
    model : RTEnsemble
      The model RTEnsemble model to save on file
    status : bool
      Returns true if the save is successful, false otherwise

class `rankeval.model.` `ProxyXGBoost`

  Bases: `object`

  Class providing the implementation for loading/storing a XGBoost model from/to file.

  static `load`(file_path, model)

    Load the model from the file identified by file_path.

    file_path : str
      The path to the filename where the model has been saved
    model : RTEnsemble
      The model instance to fill
  static `save`(file_path, model)

    Save the model onto the file identified by file_path.

    file_path : str
      The path to the filename where the model has to be saved
    model : RTEnsemble
      The model RTEnsemble model to save on file
    status : bool
      Returns true if the save is successful, false otherwise

class `rankeval.model.` `ProxyScikitLearn`

  Bases: `object`

  Class providing the implementation for loading/storing a Scikit-Learn model from/to file.

  static `export_scikit_model`(model, file_path)
  static `load`(file_path, model)

    Load the model from the file identified by file_path.

    file_path : str
      The path to the filename where the model has been saved
    model : RTEnsemble
      The model instance to fill
  static `save`(file_path, model)

    Save the model onto the file identified by file_path.

    file_path : str
      The path to the filename where the model has to be saved
    model : RTEnsemble
      The model RTEnsemble model to save on file
    status : bool
      Returns true if the save is successful, false otherwise

class `rankeval.model.` `ProxyJforests`

  Bases: `object`

  Class providing the implementation for loading/storing a Jforests model from/to file.

  static `load`(file_path, model)

    Load the model from the file identified by file_path.

    file_path : str
      The path to the filename where the model has been saved
    model : RTEnsemble
      The model instance to fill
  static `save`(file_path, model)

    Save the model onto the file identified by file_path.

    file_path : str
      The path to the filename where the model has to be saved
    model : RTEnsemble
      The model RTEnsemble model to save on file
    status : bool
      Returns true if the save is successful, false otherwise

class `rankeval.model.` `ProxyCatBoost`

  Bases: `object`

  Class providing the implementation for loading/storing a ProxyCatBoost model from/to file.

  static `load`(file_path, model)

    Load the model from the file identified by file_path.

    file_path : str
      The path to the filename where the model has been saved
    model : RTEnsemble
      The model instance to fill
  static `remap_nodeId`(nodeId, n_nodes_per_tree)
  static `save`(file_path, model)

    Save the model onto the file identified by file_path.

    file_path : str
      The path to the filename where the model has to be saved
    model : RTEnsemble
      The model RTEnsemble model to save on file
    status : bool
      Returns true if the save is successful, false otherwise

## Submodules

## rankeval.model.proxy_CatBoost module

Class providing the implementation for loading/storing a CatBoost model from/to file.

The CatBoost project is described here:
  https://github.com/catboost/catboost

CatBoost allows to save the learned model in several formats (binary, coreml, etc). Among them, we chose to adopts the Apple CoreML format for reading and converting a model into the rankeval representation. It s possible to read the coreML representation using the coremltools python package. Once read it provides all the structured information of the ensemble, with split nodes (both features and thresholds), leaf values and tree structure. Not all the information reported in the model are useful for the different analysis, thus only the relevant parts are parsed.

NOTE: CatBoost trains oblivious trees, i.e., trees where at each level a single condition is checked, independently from the which node we are currently working on. Rankeval does not exploit oblivious trees, but instead it represent them as normal decision trees Thus the same condition will appear on all the nodes of a single level of a tree. The reason behind this choice is to fasten the development of the CatBoost proxy, allowing to analyze it without focusing too much on prediction time (that is not currently measured by rankeval).

class `rankeval.model.proxy_CatBoost.` `ProxyCatBoost`

  Bases: `object`

  Class providing the implementation for loading/storing a ProxyCatBoost model from/to file.

  static `load`(file_path, model)

    Load the model from the file identified by file_path.

    file_path : str
      The path to the filename where the model has been saved
    model : RTEnsemble
      The model instance to fill
  static `remap_nodeId`(nodeId, n_nodes_per_tree)
  static `save`(file_path, model)

    Save the model onto the file identified by file_path.

    file_path : str
      The path to the filename where the model has to be saved
    model : RTEnsemble
      The model RTEnsemble model to save on file
    status : bool
      Returns true if the save is successful, false otherwise

## rankeval.model.proxy_Jforests module

Class providing the implementation for loading/storing a QuickRank model from/to file.

The Jforests project is described here: https://github.com/yasserg/jforests

The Jforests format adopts an XML representation. There is an ensemble node, with a sub-node for each tree, identified by the “Tree” tag, followed by the description of the tree (with splitting and leaf nodes). The splitting nodes are described with two information: the feature-id used for splitting, and the threshold value. Leaf nodes on the other hand are described by a “LeafOutputs” tag with the value as content.

class `rankeval.model.proxy_Jforests.` `ProxyJforests`

  Bases: `object`

  Class providing the implementation for loading/storing a Jforests model from/to file.

  static `load`(file_path, model)

    Load the model from the file identified by file_path.

    file_path : str
      The path to the filename where the model has been saved
    model : RTEnsemble
      The model instance to fill
  static `save`(file_path, model)

    Save the model onto the file identified by file_path.

    file_path : str
      The path to the filename where the model has to be saved
    model : RTEnsemble
      The model RTEnsemble model to save on file
    status : bool
      Returns true if the save is successful, false otherwise

## rankeval.model.proxy_LightGBM module

Class providing the implementation for loading/storing a LightGBM model from/to file.

The LightGBM project is described here:
  https://github.com/Microsoft/LightGBM

The LightGBM format adopts a textual representation using arrays for storing split nodes (both features and thresholds), leaf values and tree structure. Not all the information reported in the model are useful for the different analysis, thus only the relevant parts are parsed.

NOTE: the leaves output of the regression trees already take into account the weight of the tree (i.e., the learning rate or shrinkage factor). In order to maintain the scoring made by rankeval (that multiply the leaf output by the tree weight), the weight of the trees have been set equals to 1.

NOTE: currently rankeval does not support missing features. This features is not strictly required because all the most popular open-domain Learning to Rank datasets do not have missing values. To this regard, take thus into account that you may experience an unexpected behaviour if the LightGBM model you are trying to load is trained on a dataset with missing values (especially in the case you use the setting zero_as_missing=true).

class `rankeval.model.proxy_LightGBM.` `ProxyLightGBM`

  Bases: `object`

  Class providing the implementation for loading/storing a LightGBM model from/to file.

  static `load`(file_path, model)

    Load the model from the file identified by file_path.

    file_path : str
      The path to the filename where the model has been saved
    model : RTEnsemble
      The model instance to fill
  static `save`(file_path, model)

    Save the model onto the file identified by file_path.

    file_path : str
      The path to the filename where the model has to be saved
    model : RTEnsemble
      The model RTEnsemble model to save on file
    status : bool
      Returns true if the save is successful, false otherwise

## rankeval.model.proxy_QuickRank module

Class providing the implementation for loading/storing a QuickRank model from/to file.

The QuickRank project is described here: http://quickrank.isti.cnr.it

The QuickRank format adopts an XML representation. There is an header section, identified by the “info” tag, with the most important parameters adopted to learn such a model. It follows then the description of the ensemble, with a node for each tree, identified by the “tree” tag, followed by the description of the tree (with splitting and leaf nodes). The splitting nodes are described with two information: the feature id used for splitting, and the threshold value. Leaf nodes on the other hand are described by an “output” tag with the value as content.

class `rankeval.model.proxy_QuickRank.` `ProxyQuickRank`

  Bases: `object`

  Class providing the implementation for loading/storing a QuickRank model from/to file.

  static `load`(file_path, model)

    Load the model from the file identified by file_path.

    file_path : str
      The path to the filename where the model has been saved
    model : RTEnsemble
      The model instance to fill
  static `save`(file_path, model)

    Save the model onto the file identified by file_path.

    file_path : str
      The path to the filename where the model has to be saved
    model : RTEnsemble
      The model RTEnsemble model to save on file
    status : bool
      Returns true if the save is successful, false otherwise

## rankeval.model.proxy_ScikitLearn module

Class providing the implementation for loading/storing a Scikit-Learn model from/to file. The model has to be saved using the export_scikit_model method: .. code-block:: python

> from sklearn import ensemble from rankeval.model import ProxyScikitLearn … gbrt = ensemble.GradientBoostingRegressor(…) gbrt.fit(X, y) ProxyScikitLearn.export_scikit_model(model=gbrt, file_path=model_path) gbrt_rankeval = RTEnsemble(file_path=model_path, format=’ScikitLearn’)

The Scikit-Learn project is described here:
  http://scikit-learn.org/

class `rankeval.model.proxy_ScikitLearn.` `ProxyScikitLearn`

  Bases: `object`

  Class providing the implementation for loading/storing a Scikit-Learn model from/to file.

  static `export_scikit_model`(model, file_path)
  static `load`(file_path, model)

    Load the model from the file identified by file_path.

    file_path : str
      The path to the filename where the model has been saved
    model : RTEnsemble
      The model instance to fill
  static `save`(file_path, model)

    Save the model onto the file identified by file_path.

    file_path : str
      The path to the filename where the model has to be saved
    model : RTEnsemble
      The model RTEnsemble model to save on file
    status : bool
      Returns true if the save is successful, false otherwise

## rankeval.model.proxy_XGBoost module

Class providing the implementation for loading/storing a XGBoost model from/to file. The model has to be saved using textual representation, i.e., by using the following method: .. code-block:: python

> import xgboost as xgb … bst = xgb.train(param, dtrain, num_round) bst.dump_model(‘xgboost.model’)

The XGBoost project is described here:
  https://github.com/dmlc/xgboost

The XGBoost format adopts a textual representation where each line of the file represent a single split node or a leaf node, with several attributes describing the feature and the threshold involved (in case of a split node) or the output (in case of a leaf). Each node is identified by a unique integer as well as additional information not usefull for rankeval and thus ignored.

NOTE: the XGBoost version 0.6 does not properly dump the model. Indeed, as reported in the issue here:

- https://github.com/dmlc/xgboost/issues/2077

The precision of the dumping is not sufficient and cause inconsistencies with the XGBoost model. This inconsistencies cause rankeval scoring to return different predictions with respect to the original model. Without a fix by XGBoost authors, DO NOT USE this proxy.

class `rankeval.model.proxy_XGBoost.` `ProxyXGBoost`

  Bases: `object`

  Class providing the implementation for loading/storing a XGBoost model from/to file.

  static `load`(file_path, model)

    Load the model from the file identified by file_path.

    file_path : str
      The path to the filename where the model has been saved
    model : RTEnsemble
      The model instance to fill
  static `save`(file_path, model)

    Save the model onto the file identified by file_path.

    file_path : str
      The path to the filename where the model has to be saved
    model : RTEnsemble
      The model RTEnsemble model to save on file
    status : bool
      Returns true if the save is successful, false otherwise

## rankeval.model.rt_ensemble module

Class for efficient modelling of an ensemble-based model of binary regression trees.

class `rankeval.model.rt_ensemble.` `RTEnsemble`(file_path, name=None, format='QuickRank', base_score=None, learning_rate=1, n_trees=None)

  Bases: `object`

  Class for efficient modelling of an ensemble-based model composed of binary regression trees.

  This class only provides the sketch of the data structure to use for storing the model. The responsibility to correctly fill these data structures is delegated to the various proxies model.

  Load the model from the file identified by file_path using the given format.

  file_path : str
    The fpath to the filename where the model has been saved
  name : str
    The name to be given to the current model
  format : [‘QuickRank’, ‘ScikitLearn’, ‘XGBoost’, ‘LightGBM’]
    The format of the model to load.
  base_score : None or float
    The initial prediction score of all instances, global bias. If None, it uses default value used by each software (0.5 XGBoost, 0.0 all the others).
  learning_rate : None or float
    The learning rate used by the model to shrinks the contribution of
      each tree. By default it is set to 1 (no shrinking at all).
  n_trees : None or int
    The maximum number of trees to load from the model. By default it is set to None, meaning the method will load all the trees.
  file : str
    The path to the filename where the model has been saved
  name : str
    The name to be given to the current model
  n_trees : integer
    The number of regression trees in the ensemble.
  n_nodes : integer
    The total number of nodes (splitting nodes and leaves) in the ensemble
  trees_root: list of integers
    Numpy array modelling the indexes of the root nodes of the regression trees composing the ensemble. The indexes refer to the following data structures: * trees_left_child * trees_right_child * trees_nodes_value * trees_nodes_feature
  trees_weight: list of floats
    Numpy array modelling the weights of the regression trees composing the ensemble.
  trees_left_child: list of integers
    Numpy array modelling the structure (shape) of the regression trees, considering only the left children. Given a node of a regression tree (a single cell in this array), the value identify the index of the left children. If the node is a leaf, the children assumes -1 value.
  trees_right_child: list of integers
    Numpy array modelling the structure (shape) of the regression trees, considering only the right children. Given a node of a regression tree (a single cell in this array), the value identify the index of the right children. If the node is a leaf, the children assumes -1 value.
  trees_nodes_value: list of integers
    Numpy array modelling either the output of a leaf node (whether the node is a leaf, in accordance with the trees_structure data structure) or the splitting value of the node in the regression trees (with respect to the feature identified by the trees_nodes_feature data structure).
  trees_nodes_feature: list of integers
    Numpy array modelling the feature-id used by the selected splitting node (or -1 if the node is a leaf).
  model : RegressionTreeEnsemble
    The loaded model as a RTEnsemble object
  `clear_cache`()

    This method is used to clear the internal cache of the model from the scoring objects. Call this method at the end of the analysis of the current model (the memory otherwise will be automatically be freed on object deletion)

  `copy`(n_trees=None)

    Create a copy of this model, with all the trees up to the given number. By default n_trees is set to None, meaning to copy all the trees

    n_trees : None or int
      The number of trees the model will have after calling this method.
    model : RTEnsemble
      The copied model, pruned from all the trees exceeding the given number of trees chosen
  `height_trees`()

    Computes the height of each tree of the model.

    heights : numpy 1d array (n_trees)
      Height of each tree
  `initialize`(n_trees, n_nodes)

    Initialize the internal data structures in order to reflect the given shape and size of the ensemble. This method should be called only by the Proxy Models (the specific format-based loader/saver)

    n_trees : integer
      The number of regression trees in the ensemble.
    n_nodes : integer
      The total number of nodes (splitting nodes and leaves) in the ensemble
  `is_leaf_node`(index)

    This method returns true if the node identified by the given index is a leaf node, false otherwise

    index : integer
      The index of the node to test
  `max_leaves`()

    Computes the maximum number of leaves across the trees of the model.

    max_leaves : int
      Maximum number of leaves
  `num_leaves`()

    Computes the number of leaves for each tree of the model.

    n_leaves : numpy 1d array (n_trees)
      Number of leaves
  `num_nodes`()

    Computes the number of nodes for each tree of the model.

    n_nodes : numpy 1d array (n_trees)
      Number of nodes
  `save`(f, format='QuickRank')

    Save the model onto the file identified by file_path, using the given model format.

    f : str
      The path to the filename where the model has to be saved
    format : str
      The format to use for saving the model
    status : bool
      Returns true if the save is successful, false otherwise
  `score`(dataset, detailed=False, cache=False)

    Score the given model on the given dataset. Depending on the detailed parameter, the scoring will be either basic (i.e., compute only the document scores) or detailed (i.e., besides computing the document scores analyze also several characteristics of the model. The scorer is cached until existance of the model instance.

    dataset : Dataset
      The dataset to be scored
    detailed : bool
      True if the model has to be scored in a detailed fashion, false otherwise
    cache : bool
      True if the scoring results has to be cached, False otherwise. Take into account that caching the results could need quite a lot of memory, and this negative effect is particularly evident when scoring multiple models on huge dataset. Default is False.
    y_pred : numpy 1d array (n_instances)
      The predictions made by scoring the model on the given dataset
    partial_y_pred : numpy 2d array (n_instances x n_trees)
      The predictions made by scoring the model on the given dataset, on a tree basis (i.e., tree by tree and instance by instance)
    y_leaves : numpy 2d array (n_instances x n_trees)
      The leaf nodes predicted by scoring the model on the given dataset, on a tree basis (i.e., tree by tree and instance by instance)