The MarkovChains module provides access to the implementation of the Markov Chains methods of Dwork et al., 2001 and DeConde et al., 2006. It includes the MC driver class, and five small derived classes (MC1, MC2, MC3, MC4 and MCT) that can be employed by the user to execute the corresponding methods.
Implementation file
pyflagr/pyflagr/MarkovChains.py
The MC base class
This is the driver class of the module. Its direct usage is weakly discouraged. The users should prefer employing the 5 classes that derive from MC (see below) and indirectly trigger the corresponding algorithm implementations of FLAGR.
Similarly to the other PyFLAGR classes, MC derives from RAM, another base class that is defined in the RAM module. It inherits the flagr_lib connector from RAM, and through it, it obtains access to the FLAGR shared library. Its constructor determines the data types of the input arguments and the return type of the FLAGR's MC exposed function. Observe the similarity between the members of self.flagr_lib.MC.argtypes and the input arguments of the MC exposed function.
The constructor of MC takes the following arguments:
| 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\). |
ergodic_number |
Float, Optional. | |
The ergodic number, used during the computation of the ergodic transition matrix from the normalized transition matrix. |
max_iterations |
Integer, Optional. | |
The maximum number of iterations for the computation of the state matrix. |
chain |
Integer, Optional. | |
The Markov Chain method to execute. The possible values include:
|
MC includes an aggregate() function which receives the user-defined parameters and passes them to the MC exposed 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 MC1, MC2, MC3, MC4 and MCT derived classes
These classes derive from the aforementioned MC base class; as children of MC, they also inherit from the RAM class. Each of these classes triggers the execution of a different Markov Chain algorithm, simply by passing different parameters to the constructor MC. Hence, MC1 sets chain=801, MC2 sets chain=802, and so on.
Also notice that notice that none of these classes have an aggregate() function. Consequently, the aggregate() of the base class (i.e. MC) is executed when the end user invokes that function.
The following interactive block diagram depicts the architecture of PyFLAGR and its linkage to the FLAGR shared library.
