partial_ranker package

Submodules

partial_ranker.graph module

class partial_ranker.graph.Graph(dependencies, depths)

Bases: object

Class to represent the dependencies of the objects as a transitively reduced directed acyclic graph.

Inputs:

deps (dict[str, list[str]]): Dictionary with nodes as keys and a list of nodes that it depends on as values.

• e.g.; if dependency is based on a better-than relation, then in deps that look like {'obj1': ['obj2', 'obj3], 'obj2': ['obj4'], ...}, obj2 and obj3 are better than obj1, obj4 is better than obj2, etc.

depths (dict[int,List[str]]): A dictionary consisting of the list of objects at each rank.

• e.g.; in {0: ['obj1'], 1: ['obj2', 'obj3'], ...}, obj1 is at rank 0, obj2 and obj3 are at rank 1, etc.

Attributes and Methods:

in_nodes

Dictionary with nodes as keys and a list of nodes that has incoming edges to the node indicated in the key.

Type:

dict[str, list[str]]

out_nodes

Dictionary with nodes as keys and a list of nodes that has outgoing edges from the node indicated in the key.

Type:

dict[str, list[str]]

get_separable_arrangement() → List

Returns:

Arrangement of the objects according to Methodology 2 (Step 1 to 3) in the paper.

Return type:

List[str]

visualize(highlight_nodes=[])

Visualize the dependencies and ranks of the objects as a transitively reduced directed acyclic graph.

Parameters:

highlight_nodes (list, optional) – The nodes in this list are highlighted in the visualization. Defaults to [].

Returns:

A graphviz object.

Return type:

graphviz.Digraph

partial_ranker.measurements_simulator module

class partial_ranker.measurements_simulator.MeasurementsSimulator(obj_params: dict, seed=0)

Bases: object

Class for simulating measurements values using a normal distribution. Given a dictionary with object IDs as keys, and [mean, std] as values, measurement values are generated and stored.

Inputs:

obj_params (dict[str,List[float]]): Keys are object IDs (str) whose value indicates the mean and standard deviation of the normal distribution represented as [mean, std].

• e.g., for noramal distribution, {'obj1': [1.0, 0.1], 'obj2': [2.0, 0.2], ...}, the mean and std are 1.0 and 0.1 for object ‘obj1’, and 2.0 and 0.2 for object ‘obj2’.

seed (int): The numpy seed used to generate measurements. Defaults to 0.

Attributes and Methods:

measurements

A dictionary to store measurements. Keys are object IDs (str), and values are lists of measurement values.

• e.g., {'obj1': [1.0, 2.0, 3.0], 'obj2': [4.0, 5.0, 6.0, 9.0], ...}

Type:

dict[str,List[float]]

add_measurement(obj_id, x: float) → None

Adds a measurement to the measurements dictionary under the object ID obj_id.

Parameters:

• obj_id (str | int) – The ID of the object.

• x (float) – The measurement value to add.

Returns:

None

get_measurements() → dict

Returns:

A dictionary containing measurements.

Keys are object IDs (str), and values are lists of measurement values.

Return type:

dict[str,List[float]]

measure(reps: int) → None

Generates measurements for each object based on the specified distribution parameters and number of repetitions.

Parameters:

reps (int) – The number of repetitions for measuring each object.

Returns:

None

normal(mean: float, std: float) → float

Parameters:

• mean (float) – The mean of the normal distribution.

• std (float) – The standard deviation of the normal distribution.

Returns:

A random number from the normal distribution.

Return type:

float

partial_ranker.measurements_visualizer module

class partial_ranker.measurements_visualizer.MeasurementsVisualizer(measurements: dict, obj_seq: List | None = None)

Bases: object

Class for visualizing sets of measurements as box-plots or violin-plots. The y-axis indicates the object ID and the x-axis indicates the measurement values.

Input:

measurements (dict[str, List[float]]): A dictionary of objects consisting of a list of measurement values.

• e.g., {'obj1': [1.0, 2.0, 3.0], 'obj2': [4.0, 5.0, 6.0, 9.0], ...}

obj_seq (List[str], optional):

A list of object IDs which represents the order in which the y-axis of the visualization should be arranged. If not provided, it defaults to a random order.

Methods:

remove_outliers(x: List[float]) → List[float]

Remove outliers from a list of measurements. To this end, the first and third quartiles (Q1 and Q3) and the interquartile range (IQR) of the input list of measurements are computed and the outliers are identified as values that fall below Q1 - 1.5 * IQR or above Q3 + 1.5 * IQR. The method returns a new list containing only the non-outlier measurements.

Parameters:

x (List[float]) – A list of measurement values.

Returns:

A list of measurement values with outliers removed.

Return type:

List[float]

show_measurement_histograms(obj_list: List | None = None, bins=10, hspace=0.5)

Displays a subplot with a histogram of measurements for each object in obj_list.

Parameters:

• obj_list (List, optional) – The subplots are shown only for the those objects in the list. The subplots are arranged according to the order of the objects in the list.

• objects. (Defaults to a random order of all)

• bins (int, optional) – bins the measurements values. Defaults to 10.

• hspace (float, optional) – matplotlib paramater to control the space between the subplots. Defaults to 0.5.

Returns:

matplotlib.pyplot.figure

show_measurements_boxplots(obj_list=None, outliers=False, scale=1.5, tick_size=12)

Displays a graph with a boxplot of measurements for each object in obj_list. The box represents the Inter Quartile Interval (IQI), which is the interval between the 25th and the 75th quantile values, and the red line within the box represents the median value.

Parameters:

• obj_list (List, optional) – The boxplots are shown only for the those objects in the list. The boxplots are arranged according to the order of the objects in the list. Defaults to a random order of all objects.

• outliers (bool, optional) – Include outliers to calculate the box range. Defaults to False.

• scale (float, optional) – matplotlib param to control the size of the plot. Defaults to 1.5.

• tick_size (int, optional) – matplotlib param to control the size of the axis labels. Defaults to 12.

Returns:

matplotlib.pyplot.figure

show_measurements_violinplot(obj_list=None, outliers=False, scale=1.5)

Displays a graph with a violinplot of measurements for each object in obj_list.

Parameters:

• obj_list (List, optional) – The violinplots are shown only for the those objects in the list. The violinplots are arranged according to the order of the objects in the list. Defaults to a random order of all objects.

• outliers (bool, optional) – Include outliers to calculate the box range. Defaults to False.

• scale (float, optional) – matplotlib param to control the size of the plot. Defaults to 1.5.

Returns:

matplotlib.pyplot.figure

partial_ranker.partial_ranker_dfg module

class partial_ranker.partial_ranker_dfg.PartialRankerDFG(comparer)

Bases: object

DFG based partial ranking methodology (Methodology 1 in the paper). The ranks of an object corresponds to the depth of the object in a dependency graph which indicates the better-than relations. The algorithm is implemented in the method compute_ranks().

Input:

comparer (partial_ranker.QuantileComparer):

The QuantileComparer object that contains the results of pair-wise comparisons. i.e, comparer.compare() should have been called.

Attributes and Methods:

dependencies

A dictionary with objects as keys, whose value holds the list of objects that are better than the object indicated in the key. If obj_i is better than obj_j, then the value of obj_j in the dictionary is a list containing obj_i.

• e.g.; in the dict {'obj1': ['obj2', 'obj3], 'obj2': ['obj4'], ...}, obj2 and obj3 are better than obj1, obj4 is better than obj2, etc.

Type:

dict[str,list[str]]

compute_ranks() → None

Computes the partial ranks of the objects according to Methodology 1. The internal variables that stores the rank of the objects are updated.

Returns:

None

get_dfg()

Returns:

A Graph object that represents the rank relation among the objects according to Methodology 1.

Return type:

partial_ranker.Graph

get_rank_obj(obj: str) → int

Parameters:

obj (str) – Object name.

Returns:

The partial rank of a given object.

Return type:

int

get_ranks() → dict[int, list[str]]

Returns:

A dictionary consisting of the list of objects at each rank. e.g.; {0: ['obj1'], 1: ['obj2', 'obj3'], ...}.

Return type:

dict[int,List[str]]

partial_ranker.partial_ranker_dfg_r module

class partial_ranker.partial_ranker_dfg_r.PartialRankerDFGReduced(comparer)

Bases: object

DFG based partial ranking methodology (Methodology 2 in the paper). First, the partial ranking is computed using Methodology 1. Then, the dependency graph from Methodology 1 is used to identify an alternative partial ranking with fewer ranks. The algorithm is implemented in the method compute_ranks().

Input:

comparer (partial_ranker.QuantileComparer):

The QuantileComparer object that contains the results of pair-wise comparisons. i.e, comparer.compare() should have been called.

Attributes and Methods:

objs

List of object names.

Type:

List[str]

pr_dfg

The partial ranking object which computes a parial ranking according to Methodology 1.

Type:

partial_ranker.PartialRankerDFG

graph_H

The dependency graph that represents the rank relation among the objects according to Methodology 1.

Type:

partial_ranker.Graph

compute_ranks() → None

Computes the partial ranks of the objects according to Methodology 2. The internal variables that stores the rank of the objects are updated.

get_dfg()

Returns:

A Graph object that represents the rank relation among the objects according to Methodology 2.

Return type:

partial_ranker.Graph

get_rank_obj(obj: str) → int

Parameters:

obj (str) – Object name.

Returns:

The partial rank of a given object.

Return type:

int

get_ranks() → dict[int, list[str]]

Returns:

A dictionary consisting of the list of objects at each rank. e.g.; {0: ['obj1'], 1: ['obj2', 'obj3'], ...}.

Return type:

dict[int,List[str]]

partial_ranker.partial_ranker_min module

class partial_ranker.partial_ranker_min.PartialRankerMin(comparer)

Bases: object

Partial ranking methodology (Methodology 3 in the paper). First, the objects are grouped into mutually exclusive equivalence classes based on the results of pair-wise comparisons. Then, the equivalence classes are ranked according to increasing lower quantiles values of one of the objects each class. All the objects in an equivalence class are ranked equally. The algorithm is implemented in the method compute_ranks().

Input:

comparer (partial_ranker.QuantileComparer):

The QuantileComparer object that contains the results of pair-wise comparisons. i.e, comparer.compare() should have been called.

Attributes and Methods:

objs

List of object names.

Type:

List[str]

equivalence

A dictionary with objects as keys, whose value holds the list of objects that are equivalent to the object indicated in the key.

• e.g.; in the dict {'obj1': ['obj3', 'obj4], 'obj2': ['obj5'], ...}, obj3 and obj4 are equivalent to obj1, obj5 is equivalent to obj2, etc.

Type:

dict[str,list[str]]

compute_ranks() → None

Computes the partial ranks of the objects according to Methodology 3. The internal variables that stores the rank of the objects are updated.

get_dfg()

Returns:

A Graph object that represents the rank relation among the objects according to Methodology 3.

Return type:

partial_ranker.Graph

get_rank_obj(obj) → int

Parameters:

obj (str) – Object name.

Returns:

The partial rank of a given object.

Return type:

int

get_ranks() → dict[int, list[str]]

Returns:

A dictionary consisting of the list of objects at each rank. e.g.; {0: ['obj1'], 1: ['obj2', 'obj3'], ...}.

Return type:

dict[int,List[str]]

partial_ranker.partial_ranker_wrapper module

class partial_ranker.partial_ranker_wrapper.Method(value)

Bases: Enum

An Enum class to specify the method to compute the partial ranks.

DFG = 1

DFGReduced = 2

Min = 3

class partial_ranker.partial_ranker_wrapper.PartialRanker(comparer, method: Method = Method.DFGReduced)

Bases: object

A general class to compute the partial ranks of objects based on the results of pair-wise comparisons.

Input:

comparer (partial_ranker.QuantileComparer):

The QuantileComparer object that contains the results of pair-wise comparisons. i.e, comparer.compare() should have been called.

method (Method):

The method to compute the partial ranks. The default is Method.DFGReduced.

• Method.DFG: The methodology implemenmted in partial_ranker.PartialRankerDFG is used.

• Method.DFGReduced: The methodology implemenmted in partial_ranker.PartialRankerDFGReduced is used.

• Method.Min: The methodology implemenmted in partial_ranker.PartialRankerMin is used.

Attributes and Methods:

ranker

The instance of the partial ranking methodology class used to compute the partial ranks.

compute_ranks(method: Method = Method.DFGReduced) → None

Computes the partial ranks of objects. The attribute ranker is set to the instance of the partial ranking methodology class used to compute the partial ranks.

Parameters:

method (Method, optional) – The method to compute the partial ranks. Defaults to Method.DFGReduced.

get_dfg()

Returns:

A Graph object that represents the rank relation among the objects.

Return type:

partial_ranker.Graph

get_rank_obj(obj) → int

Parameters:

obj (str) – Object name.

Returns:

The partial rank of a given object.

Return type:

int

get_ranks() → dict[int, list[str]]

Returns:

A dictionary consisting of the list of objects at each rank. e.g.; {0: ['obj1'], 1: ['obj2', 'obj3'], ...}.

Return type:

dict[int,List[str]]

get_separable_arrangement() → List[str]

Returns:

Arrangement of the objects according to PartialRankerDFG.get_dfg().get_separable_arrangement().

Return type:

List[str]

partial_ranker.quantile_comparer module

class partial_ranker.quantile_comparer.QuantileComparer(measurements: dict[str, list[float]])

Bases: object

Given a dictionary of objects consisting of a list of measurement values, e.g., {'obj1': [1.2, 1.3, 1.4], 'obj2': [1.5, 1.6, 1.7,0.9], ...}, this class provides methods to compare objects pairwise using a quantile-based better than relation, and to store the results of the comparisons in a comparison matrix.

Input:

measurements (dict[str, List[float]]): A dictionary of objects consisting of a list of measurement values.

Attributes and Methods:

C

A square matrix of size (N x N), where N is the number of objects. This matrix should holds the results of pair-wise comparisons as follows:

• If obj_i is better than obj_j, then C[obj_i][obj_j] = 0.

• If obj_i is equivalent to obj_j, then C[obj_i][obj_j] = 1.

• If obj_i is worse than obj_j, then C[obj_i][obj_j] = 2.

Type:

dict[str, dict[str, int]]

objs

A list of object keys in the measurements dictionary.

• e.g., ['obj1', 'obj2', ...].

Type:

list[str]

t_up

A dictionary to store the upper quantile values of the measurements for each object.

• e.g., {'obj1': 1.5, 'obj2': 1.6, ...}.

Type:

dict[str, float]

t_low

A dictionary to store the lower quantile values of the measurements for each object.

Type:

dict[str, float]

better_than_relation(obj1: str, obj2: str) → int

The better than relation to compare two objects based on the quantile vales of their measurements.

• obj1 is better than obj2 if the upper quantile value of obj1 is less than the lower quantile value of obj2.

• obj1 is worse than obj2 if the upper quantile value of obj2 is less than the lower quantile value of obj1.

• obj1 is equivalent to obj2 if neither of the above conditions are satisfied.

Parameters:

• obj1 (str) – the key of an object in the measurements dictionary.

• obj2 (str) – the key of another object in the measurements dictionary.

Returns:

• If obj1 is better than obj2, returns 0

• If obj1 is equivalent to obj2, returns 1

• If obj1 is worse than obj2, returns 2

Return type:

int

compare() → None

Performs a pair-wise comparison of all objects in the measurements dictionary and stores the results in C.

Returns:

None

compute_quantiles(q_max: int, q_min: int, outliers=False) → None

For a given quantile range, the upper and lower quantile values of measurements are computed and stored in the t_up and t_low dictionaries. The elements of the comparison matrix C is initialized to -1.

Parameters:

• q_max (int) – Upper quantile. E.g., 75 for 75th percentile.

• q_min (int) – Lower quantile. E.g., 25 for 25th percentile.

• outliers (bool, optional) – Remove outliers using the 1.5 IQR rule. Defaults to False.

Returns:

None

get_comparison_matrix() → dict[str, dict[str, int]]

Returns:

The comparison matrix C.

Return type:

dict[str, dict[str, int]]

Module contents