3.16. Integrating custom methods

This step-by-step guide describes how custom rank aggregation methods can be implemented and integrated into FLAGR. If you intend to implement fewer than three methods, then several of the steps below are already implemented in FLAGR. For three or more custom methods, additional actions must be performed.

Implementing your own method/s

Custom methods must be implemented as C++ functions in the src/ram/CustomMethods.cpp file. This file already contains two such functions: CustomMethod1() and CustomMethod2(). In case you desire to implement more methods (e.g. CustomMethod3(), etc.), then you must implement them similarly in that file.

Typically, a rank aggregation method assigns scores to the list elements and then, it sorts the elements in either increasing, or decreasing score order. For this reason, the last step in your implementation must be the sorting process of the elements of MergedList. Observe that CustomMethod1() and CustomMethod2() contain a call to qsort (QuickSort) in order to perform the required sorting.

Each algorithm implementation (including the built-in ones) takes three arguments:

• An array of the input preference lists (class InputList ** inlists). Most rank aggregation methods do not require access to this array, since when the function is called, the input lists have already been merged in the MergedList (i.e. this) object. However, several methods require the computation of list distances (e.g. DIBRA, Agglomerative) and the inlists pointer provides access to this array.
• A pointer to a SimpleScoreStats object in case you desire to store score statistics (max, min, mean, etc.).
• A pointer to the InputParams object that contains the user-defined input parameters.

The following code example demonstrates an iteration through the elements of the aggregate list. For each element q, an iteration through its individual rankings in each input preference list is performed:

void MergedList::CustomMethod1 (class InputList ** inlists, class SimpleScoreStats * s, class InputParams * prms) {
	class MergedItem * q;
	class Ranking * r;

	for (rank_t i = 0; i < this->num_nodes; i++) {
		/// q stores an element of the aggregate list
		q = this->item_list[i];

		/// Iterate through the individual rankings of q
		for (uint32_t j = 0; j < q->get_num_alloc_rankings(); j++) {
			r = q->get_ranking(j);
			/// Do something with q and r

		}
	}
	/// Sort the list elements in decreasing score order
	qsort(this->item_list, this->num_nodes, sizeof(class MergedItem *),
		&MergedList::cmp_score_desc);
}

Calling the new method/s

The implementation of the new methods can be immediately used, provided that you have not changed the names of the functions CustomMethod1() and CustomMethod2(). In this case, the following piece of code inside the main() function in cflagr.cpp and dllflagr.cpp invokes the new implementations:

/// Execution of CustomMethod1
Custom1(input_file, qrels_file, 20, "RRA", output_dir);

/// Execution of CustomMethod2
Custom2(input_file, qrels_file, 20, "RRA", output_dir);

If you change the aforementioned function names, or you create a new function for a new algorithm implementation, then a sequence of actions must be taken so that it becomes available for usage. More specifically:

• The user must determine an integer identifier for the algorithm. To avoid conflicts with the built-in methods of FLAGR, it is advised that the leading digit of the identifier is 9 (e.g., 900).
• The user must update the aggregate() function of the Aggregator to allow the execution of the custom method. More specifically, the if statement must be appropriately extended.
• An exposed C function must be written in both cflagr.cpp and dllflagr.cpp with the aim of including the custom implementation in a shared/dynamic link library. The function can be called in the main() function of cflagr.cpp or dllflagr.cpp.

Additional details for custom method implementations

1. A custom rank aggregation method must be declared as a public member function of the MergedList class. This is performed in the class descriptor, in the src/MergedList.h header file. Notice that CustomMethod1() and CustomMethod2() are already public members of MergedList.
2. The required .cpp file that contains the implementation of the member function must be stored in the src/ram directory.
3. Then, the .cpp file is imported in the project with an include statement in src/MergedList.cpp.