The Linear module provides access to the implementations of the linear combination methods of FLAGR. In these methods, the score of each element is computed by summing up the partial scores of that element with respect to its rankings in each input preference list. The module includes four classes which are described below: CombSUM, CombMNZ, BordaCount and SimpleBordaCount.
Implementation file
pyflagr/pyflagr/Linear.py
The CombSUM and CombMNZ Python classes
Both classes derive from RAM, a base class defined in the RAM module. They inherit the flagr_lib connector from RAM, and through it, they obtain access to the FLAGR shared library. Their constructors are identical and determine the data types of the input arguments and the return type of the Linear exposed function. Observe the similarity between the members of self.flagr_lib.Linear.argtypes and the input arguments of the Linear exposed function.
The arguments of the constructors of CombSUM and CombMNZ include:
| Parameter | Type | Default | Description |
eval_pts |
Integer, Optional. Considered only if rels_file or rels_df is set. |
10 | Determines the elements in the aggregate list on which the evaluation measures (i.e. Precision, and nDCG) will be computed. For example, for eval_pts=10 FLAGR will compute Average Precision, \(P@1, P@2, ... P@10\) and \(N@1, N@2, ... N@10\). |
norm |
String, Optional. | borda |
Rank or score normalization methods.
|
CombSUM and CombMNZ also include an aggregate() function which receives the user-defined parameters and passes them to the Linear exposed C function, that subsequently performs the aggregation of the ranked input preference lists. The arguments of aggregate() are:
| Parameter | Type | Default | Description |
input_file |
String - Required, unless input_df is set. |
Empty String | A CSV file that contains the input lists to be aggregated. |
input_df |
Pandas DataFrame - Required, unless input_file is set. |
None |
A Pandas DataFrame that contains the input lists to be aggregated. Note: If both input_file and input_df are set, only the former is used; the latter is ignored. |
rels_file |
String, Optional. | Empty String | A CSV file that contains the relevance judgements of the involved list elements. If such a file is passed, FLAGR will evaluate the generated aggregate list/s by computing several retrieval effectiveness evaluation measures. The results of the evaluation will be stored in the eval_df DataFrame. Otherwise, no evaluation will take place and eval_df will be empty. |
rels_df |
Pandas DataFrame, Optional. | None |
A Pandas DataFrame that contains the relevance judgements of the involved list elements. If such a dataframe is passed, FLAGR will evaluate the generated aggregate list/s by computing several retrieval effectiveness evaluation measures. The results of the evaluation will be stored in the eval_df DataFrame. Otherwise, no evaluation will take place and eval_df will be empty.Note: If both rels_file and rels_df are set, only the former is used; the latter is ignored. |
output_dir |
String, Optional. | Temporary directory (OS-specific) | The directory where the output files (aggregate lists and evaluation) will be stored. If it is not set, the default location will be used. |
The BordaCount and SimpleBordaCount Python classes
These two classes have been included in PyFLAGR for historical reasons. They are equivalent to the CombSUM linear combination method with norm='borda' and norm='simple-borda' respectively.
BordaCount and SimpleBordaCount derive from CombSUM (which in turn derives from RAM). They do not have an aggregate() method, so they both call the same aggregate() function of CombSUM. Their only difference lies in their constructors: The former initializes CombSUM with norm='borda', whereas the latter with norm='simple-borda'.
The following interactive block diagram depicts the architecture of PyFLAGR and its linkage to the FLAGR shared library.
