Reference¶

File formats¶

lincs uses text-based (YAML and CSV) file formats. The same formats are used for synthetic and real-world data. The same formats are used when lincs reads files or when it outputs to files. The same formats are used when lincs outputs to actual files or to the standard output.

The problem file¶

The problem file is a YAML file specified by the following JSON Schema:

Classification problem
type	object
properties
kind	type	string
	const	classification-problem
format_version	type	integer
	const	1
criteria	Structural information about criteria used in the classification problem.
	type	array
	items	type	object
		oneOf	properties
			name	type	string
			value_type	type	string
				enum	real, integer
			preference_direction	type	string
				enum	increasing, isotone, decreasing, antitone, single-peaked
			min_value	type	number
			max_value	type	number
			additionalProperties	False
			properties
			name	type	string
			value_type	type	string
				const	enumerated
			ordered_values	Ordered list of values that can be taken by the criterion.
				type	array
				items	type	string
				minItems	1
			additionalProperties	False
	minItems	1
ordered_categories	Structural information about categories in the classification problem, ordered from the worst to the best.
	type	array
	items	type	object
		properties
		name	type	string
		additionalProperties	False
	minItems	2
additionalProperties	False

The NCS model file¶

The model file is a YAML file specified by the following JSON Schema:

NCS classification model
type	object
properties
kind	type	string
	const	ncs-classification-model
format_version	type	integer
	const	1
accepted_values	For each criterion in the classification problem, a way to determine the accepted values for each category.
	type	array
	items	type	object
		oneOf	properties
			kind	type	string
				const	thresholds
			thresholds	For each category but the lowest, the threshold to be accepted in that category according to that criterion.
				type	array
				minItems	1
			additionalProperties	False
			properties
			kind	type	string
				const	intervals
			intervals	For each category but the lowest, the interval of values to be accepted in that category according to that criterion.
				type	array
				items	oneOf	type	null
						type	array
						items	type	number
						maxItems	2
						minItems	2
				minItems	1
			additionalProperties	False
	minItems	1
sufficient_coalitions	For each category but the lowest, a description of the sufficient coalitions for that category.
	type	array
	items	type	object
		oneOf	properties
			kind	type	string
				const	weights
			criterion_weights	type	array
				items	type	number
				minItems	1
			additionalProperties	False
			properties
			kind	type	string
				const	roots
			upset_roots	type	array
				items	type	array
					items	type	integer
					minItems	0
				minItems	0
			additionalProperties	False
	minItems	1
additionalProperties	False

The alternatives file¶

The alternatives file is a CSV file.

Separator: the separator is an actual comma: ,.

Comments: lines starting with a # are ignored.

Quotes: strings can be quoted using ". Strings containing commas or whitespace must be quoted.

Header line: the first non-comment line is a header. It must contain the names of the columns, separated by commas.

Data lines: the following non-comment lines are data lines. Each line represents an alternative.

First column: its name is name. Its values are the names of the alternatives.

Intermediate columns: their names are the names of the criteria, as found in the associated problem file. Their values are the values of the alternatives for the criteria.

Last column: its name is category. Its values can either be empty strings (for unclassified alternatives), or the names of the categories, as found in the associated problem file.

Command-line interface¶

lincs¶

lincs (Learn and Infer Non-Compensatory Sorting) is a set of tools for training and using MCDA models.

lincs [OPTIONS] COMMAND [ARGS]...

Options

--version¶: Show the version and exit.

classification-accuracy¶

Compute a classification accuracy.

PROBLEM is a classification problem file. MODEL is a classification model file for that problem. TESTING_SET is a classified alternatives file for that problem.

The classification accuracy is written to standard output as an integer between 0 and the number of alternatives.

lincs classification-accuracy [OPTIONS] PROBLEM MODEL TESTING_SET

Arguments

PROBLEM¶: Required argument

MODEL¶: Required argument

TESTING_SET¶: Required argument

classify¶

Classify alternatives.

PROBLEM is a classification problem file. MODEL is a classification model file for that problem. ALTERNATIVES is an unclassified alternatives file for that problem.

lincs classify [OPTIONS] PROBLEM MODEL ALTERNATIVES

Options

--output-alternatives <output_alternatives>¶: Write classified alternatives to this file instead of standard output.

Arguments

PROBLEM¶: Required argument

MODEL¶: Required argument

ALTERNATIVES¶: Required argument

describe¶

Provide human-readable descriptions.

lincs describe [OPTIONS] COMMAND [ARGS]...

classification-model¶

Describe a classification model.

PROBLEM is a classification problem file. MODEL is a classification model file for that problem.

lincs describe classification-model [OPTIONS] PROBLEM MODEL

Options

--output-description <output_description>¶: Write description to this file instead of standard output.

Arguments

PROBLEM¶: Required argument

MODEL¶: Required argument

classification-problem¶

Describe a classification problem.

PROBLEM is a classification problem file.

lincs describe classification-problem [OPTIONS] PROBLEM

Options

--output-description <output_description>¶: Write description to this file instead of standard output.

Arguments

PROBLEM¶: Required argument

generate¶

Generate synthetic data.

lincs generate [OPTIONS] COMMAND [ARGS]...

classification-model¶

Generate a synthetic classification model.

PROBLEM is a classification problem file describing the problem to generate a model for.

lincs generate classification-model [OPTIONS] PROBLEM

Options

--output-model <output_model>¶: Write generated model to this file instead of standard output.

--random-seed <random_seed>¶: The random seed to use.

--model-type <model_type>¶

The type of classification model to generate.

Default:: 'mrsort'
Options:: mrsort

--mrsort.fixed-weights-sum <mrsort__fixed_weights_sum>¶

Make sure weights add up to this pre-determined value instead of a pseudo-random one.

Only valid if:

--model-type is mrsort

Arguments

PROBLEM¶: Required argument

classification-problem¶

Generate a synthetic classification problem.

The generated problem has CRITERIA_COUNT criteria and CATEGORIES_COUNT categories.

lincs generate classification-problem [OPTIONS] CRITERIA_COUNT
                                      CATEGORIES_COUNT

Options

--denormalized-min-max¶: Generate criteria with random denormalized min and max values. (By default, min and max value are 0 and 1)

--forbid-increasing-criteria¶: Forbid criteria to have increasing preference direction. (Requires ‘–allow-decreasing-criteria’)

--allow-decreasing-criteria¶: Allow criteria to have decreasing preference direction. (By default, all criteria have increasing preference direction)

--allow-single-peaked-criteria¶: Allow criteria to have single-peaked preference direction. (By default, all criteria have increasing preference direction)

--forbid-real-criteria¶: Forbid criteria with real values. (Requires another ‘–allow-…-criteria’ option)

--allow-enumerated-criteria¶: Allow criteria with enumerated values. (By default, all criteria are real)

--allow-integer-criteria¶: Allow criteria with integer values. (By default, all criteria are real)

--output-problem <output_problem>¶: Write generated problem to this file instead of standard output.

--random-seed <random_seed>¶: The random seed to use.

Arguments

CRITERIA_COUNT¶: Required argument

CATEGORIES_COUNT¶: Required argument

classified-alternatives¶

Generate synthetic classified alternatives.

PROBLEM is a classification problem file describing the problem to generate alternatives for. MODEL is a classification model file for that problem describing the model to use to classify the generated alternatives.

lincs generate classified-alternatives [OPTIONS] PROBLEM MODEL
                                       ALTERNATIVES_COUNT

Options

--output-alternatives <output_alternatives>¶: Write generated classified alternatives to this file instead of standard output.

--max-imbalance <max_imbalance>¶: Ensure that categories are balanced, by forcing their size to differ from the perfectly balanced size by at most this fraction.

--misclassified-count <misclassified_count>¶: Misclassify that many alternatives.

--random-seed <random_seed>¶: The random seed to use.

Arguments

PROBLEM¶: Required argument

MODEL¶: Required argument

ALTERNATIVES_COUNT¶: Required argument

info¶

Get information about lincs itself.

lincs info [OPTIONS] COMMAND [ARGS]...

has-gpu¶

Check whether lincs was compiled with CUDA support. Return code is 0 if CUDA is supported, 1 otherwise.

lincs info has-gpu [OPTIONS]

Options

--quiet¶: Don’t print anything, just return the exit code.

learn¶

Learn a model.

lincs learn [OPTIONS] COMMAND [ARGS]...

classification-model¶

Learn a classification model.

PROBLEM is a classification problem file describing the problem to learn a model for. LEARNING_SET is a classified alternatives file for that problem. It’s used as a source of truth to learn the model.

If you use the –mrsort.weights-profiles-breed strategy, you SHOULD specify at least one termination strategy, e.g. –mrsort.weights-profiles-breed.max-duration.

lincs learn classification-model [OPTIONS] PROBLEM LEARNING_SET

Options

--output-model <output_model>¶: Write the learned classification model to this file instead of standard output.

--model-type <model_type>¶

The type of classification model to learn.

Default:: 'mrsort'
Options:: mrsort | ucncs

--ucncs.strategy <ucncs__strategy>¶

The general approach to transform the learning problem into a satisfiability problem.

Only valid if:

--model-type is ucncs

Default:: 'sat-by-coalitions'
Options:: sat-by-coalitions | sat-by-separation | max-sat-by-coalitions | max-sat-by-separation

--ucncs.max-sat-by-separation.solver <ucncs__max_sat_by_separation__solver>¶

Only valid if:

--model-type is ucncs
--ucncs.strategy is max-sat-by-separation

Default:: 'eval-max-sat'
Options:: eval-max-sat

--ucncs.max-sat-by-separation.eval-max-sat.nb-minimize-threads <ucncs__max_sat_by_separation__eval_max_sat__nb_minimize_threads>¶

Only valid if:

--model-type is ucncs
--ucncs.strategy is max-sat-by-separation
--ucncs.max-sat-by-separation.solver is eval-max-sat

Default:: 0

--ucncs.max-sat-by-separation.eval-max-sat.timeout-fast-minimize <ucncs__max_sat_by_separation__eval_max_sat__timeout_fast_minimize>¶

Only valid if:

--model-type is ucncs
--ucncs.strategy is max-sat-by-separation
--ucncs.max-sat-by-separation.solver is eval-max-sat

Default:: 60

--ucncs.max-sat-by-separation.eval-max-sat.coef-minimize-time <ucncs__max_sat_by_separation__eval_max_sat__coef_minimize_time>¶

Only valid if:

--model-type is ucncs
--ucncs.strategy is max-sat-by-separation
--ucncs.max-sat-by-separation.solver is eval-max-sat

Default:: 2

--ucncs.max-sat-by-coalitions.solver <ucncs__max_sat_by_coalitions__solver>¶

The solver to use to solve the MaxSAT problem.

Only valid if:

--model-type is ucncs
--ucncs.strategy is max-sat-by-coalitions

Default:: 'eval-max-sat'
Options:: eval-max-sat

--ucncs.max-sat-by-coalitions.eval-max-sat.nb-minimize-threads <ucncs__max_sat_by_coalitions__eval_max_sat__nb_minimize_threads>¶

The number of threads to use to minimize the MaxSAT problem. Passed directly to the EvalMaxSAT solver.

Only valid if:

--model-type is ucncs
--ucncs.strategy is max-sat-by-coalitions
--ucncs.max-sat-by-coalitions.solver is eval-max-sat

Default:: 0

--ucncs.max-sat-by-coalitions.eval-max-sat.timeout-fast-minimize <ucncs__max_sat_by_coalitions__eval_max_sat__timeout_fast_minimize>¶

The maximum duration of the “fast minimize” phase of solving the MaxSAT problem, in seconds. Passed directly to the EvalMaxSAT solver.

Only valid if:

--model-type is ucncs
--ucncs.strategy is max-sat-by-coalitions
--ucncs.max-sat-by-coalitions.solver is eval-max-sat

Default:: 60

--ucncs.max-sat-by-coalitions.eval-max-sat.coef-minimize-time <ucncs__max_sat_by_coalitions__eval_max_sat__coef_minimize_time>¶

The coefficient to use to multiply the time spent minimizing the MaxSAT problem. Passed directly to the EvalMaxSAT solver.

Only valid if:

--model-type is ucncs
--ucncs.strategy is max-sat-by-coalitions
--ucncs.max-sat-by-coalitions.solver is eval-max-sat

Default:: 2

--mrsort.strategy <mrsort__strategy>¶

The top-level strategy to use to learn the MRSort model. See https://mics-lab.github.io/lincs/user-guide.html#learning-strategies about strategies.

Only valid if:

--model-type is mrsort

Default:: 'weights-profiles-breed'
Options:: weights-profiles-breed

--mrsort.weights-profiles-breed.target-accuracy <mrsort__weights_profiles_breed__target_accuracy>¶

The target accuracy to reach on the learning set.

Only valid if:

--model-type is mrsort
--mrsort.strategy is weights-profiles-breed

Default:: 1.0

--mrsort.weights-profiles-breed.max-iterations <mrsort__weights_profiles_breed__max_iterations>¶

The maximum number of iterations to use to learn the MRSort model.

Only valid if:

--model-type is mrsort
--mrsort.strategy is weights-profiles-breed

--mrsort.weights-profiles-breed.max-iterations-without-progress <mrsort__weights_profiles_breed__max_iterations_without_progress>¶

The maximum number of iterations to try learning the MRSort model without progressing before giving up.

Only valid if:

--model-type is mrsort
--mrsort.strategy is weights-profiles-breed

--mrsort.weights-profiles-breed.max-duration <mrsort__weights_profiles_breed__max_duration>¶

The maximum duration to learn the MRSort model, in seconds.

Only valid if:

--model-type is mrsort
--mrsort.strategy is weights-profiles-breed

--mrsort.weights-profiles-breed.max-duration-without-progress <mrsort__weights_profiles_breed__max_duration_without_progress>¶

The maximum duration to try learning the MRSort model without progressing before giving up, in seconds.

Only valid if:

--model-type is mrsort
--mrsort.strategy is weights-profiles-breed

--mrsort.weights-profiles-breed.models-count <mrsort__weights_profiles_breed__models_count>¶

The number of temporary MRSort models to train. The result of the learning will be the most accurate of those models.

Only valid if:

--model-type is mrsort
--mrsort.strategy is weights-profiles-breed

Default:: 9

--mrsort.weights-profiles-breed.initialization-strategy <mrsort__weights_profiles_breed__initialization_strategy>¶

The strategy to use to initialize the MRSort models.

Only valid if:

--model-type is mrsort
--mrsort.strategy is weights-profiles-breed

Default:: 'maximize-discrimination-per-criterion'
Options:: maximize-discrimination-per-criterion

--mrsort.weights-profiles-breed.weights-strategy <mrsort__weights_profiles_breed__weights_strategy>¶

The strategy to use to improve the weights of the MRSort models.

Only valid if:

--model-type is mrsort
--mrsort.strategy is weights-profiles-breed

Default:: 'linear-program'
Options:: linear-program

--mrsort.weights-profiles-breed.linear-program.solver <mrsort__weights_profiles_breed__linear_program__solver>¶

The solver to use to solve the linear programs.

Only valid if:

--model-type is mrsort
--mrsort.strategy is weights-profiles-breed
--mrsort.weights-profiles-breed.weights-strategy is linear-program

Default:: 'glop'
Options:: glop | alglib

--mrsort.weights-profiles-breed.profiles-strategy <mrsort__weights_profiles_breed__profiles_strategy>¶

The strategy to use to improve the profiles of the MRSort models.

Only valid if:

--model-type is mrsort
--mrsort.strategy is weights-profiles-breed

Default:: 'accuracy-heuristic'
Options:: accuracy-heuristic

--mrsort.weights-profiles-breed.accuracy-heuristic.random-seed <mrsort__weights_profiles_breed__accuracy_heuristic__random_seed>¶

The random seed to use for this heuristic.

Only valid if:

--model-type is mrsort
--mrsort.strategy is weights-profiles-breed
--mrsort.weights-profiles-breed.profiles-strategy is accuracy-heuristic

--mrsort.weights-profiles-breed.accuracy-heuristic.processor <mrsort__weights_profiles_breed__accuracy_heuristic__processor>¶

The processor to use to improve the profiles of the MRSort models.

Only valid if:

--model-type is mrsort
--mrsort.strategy is weights-profiles-breed
--mrsort.weights-profiles-breed.profiles-strategy is accuracy-heuristic

Default:: 'cpu'
Options:: cpu | gpu

--mrsort.weights-profiles-breed.breed-strategy <mrsort__weights_profiles_breed__breed_strategy>¶

The strategy to use to breed the MRSort models.

Only valid if:

--model-type is mrsort
--mrsort.strategy is weights-profiles-breed

Default:: 'reinitialize-least-accurate'
Options:: reinitialize-least-accurate

--mrsort.weights-profiles-breed.reinitialize-least-accurate.portion <mrsort__weights_profiles_breed__reinitialize_least_accurate__portion>¶

The portion of the least accurate MRSort models to reinitialize.

Only valid if:

--model-type is mrsort
--mrsort.strategy is weights-profiles-breed
--mrsort.weights-profiles-breed.breed-strategy is reinitialize-least-accurate

Default:: 0.5

--mrsort.weights-profiles-breed.verbose¶

Print information about the learning process on stderr while learning.

Only valid if:

--model-type is mrsort
--mrsort.strategy is weights-profiles-breed

--mrsort.weights-profiles-breed.output-metadata <mrsort__weights_profiles_breed__output_metadata>¶

Write metadata about the learning process to this file.

Only valid if:

--model-type is mrsort
--mrsort.strategy is weights-profiles-breed

Arguments

PROBLEM¶: Required argument

LEARNING_SET¶: Required argument

visualize¶

Make graphs from data.

lincs visualize [OPTIONS] COMMAND [ARGS]...

classification-model¶

Visualize a classification model.

PROBLEM is a classification problem file. MODEL is a classification model file for that problem describing the model to visualize. The generated image is written to the OUTPUT file in PNG format.

lincs visualize classification-model [OPTIONS] PROBLEM MODEL OUTPUT

Options

--alternatives <alternatives>¶: Add the alternatives from this classified alternatives file to the visualization.

--alternatives-count <alternatives_count>¶: Add only this number of alternatives.

Arguments

PROBLEM¶: Required argument

MODEL¶: Required argument

OUTPUT¶: Required argument

Python API¶

The `lincs` package¶

This is the main module for the lincs library. It contains general information (version, GPU availability, etc.) and items of general usage (e.g. the exception for invalid data).

lincs.__version__: str¶: The version of lincs, as a string in Version Specifier format.

lincs.has_gpu: bool¶: True if lincs was built with CUDA support.

exception lincs.DataValidationException¶: Raised by constructors when called with invalid data. ex.args[0] gives a human-readable description of the error.

exception lincs.LearningFailureException¶: Raised by learning algorithms when they can’t reach their objective.

class lincs.UniformRandomBitsGenerator¶

Random number generator.

__call__() → int¶: Generate the next pseudo-random integer.

The `lincs.classification` module¶

This module contains everything related to classification.

class lincs.classification.Criterion¶

A classification criterion, to be used in a classification Problem.

__init__(name: str, values: RealValues)¶: Constructor for real-valued criterion.

__init__(name: str, values: IntegerValues): Constructor for integer-valued criterion.

__init__(name: str, values: EnumeratedValues): Constructor for criterion with enumerated values.

property name: str¶: The name of the criterion.

class ValueType¶

The different types of values for a criterion.

class property real: ValueType¶: Real values.

class property integer: ValueType¶: Integer values.

class property enumerated: ValueType¶: Enumerated values.

property value_type: ValueType¶: The type of values for this criterion.

property is_real: bool¶: True if the criterion is real-valued.

property is_integer: bool¶: True if the criterion is integer-valued.

property is_enumerated: bool¶: True if the criterion takes enumerated values.

class PreferenceDirection¶

What values are preferred for a criterion.

class property increasing: PreferenceDirection¶: For criteria where higher numerical values are known to be better.

class property decreasing: PreferenceDirection¶: For criteria where lower numerical values are known to be better.

class property single_peaked: PreferenceDirection¶: For criteria where intermediate numerical values are known to be better.

class property isotone: PreferenceDirection¶: Synonym for increasing.

class property antitone: PreferenceDirection¶: Synonym for decreasing.

class RealValues¶

Descriptor of the real values allowed for a criterion.

__init__(preference_direction: PreferenceDirection, min_value: float, max_value: float)¶: Parameters map exactly to attributes with identical names.

property min_value: float¶: The minimum value allowed for this criterion.

property max_value: float¶: The maximum value allowed for this criterion.

property preference_direction: PreferenceDirection¶: The preference direction for this criterion.

property is_increasing: bool¶: True if the criterion has increasing preference direction.

property is_decreasing: bool¶: True if the criterion has decreasing preference direction.

property is_single_peaked: bool¶: True if the criterion has single-peaked preference direction.

property real_values: RealValues¶: Descriptor of the real values allowed for this criterion, accessible if is_real.

class IntegerValues¶

Descriptor of the integer values allowed for a criterion.

__init__(preference_direction: PreferenceDirection, min_value: int, max_value: int)¶: Parameters map exactly to attributes with identical names.

property min_value: float¶: The minimum value allowed for this criterion.

property max_value: float¶: The maximum value allowed for this criterion.

property preference_direction: PreferenceDirection¶: The preference direction for this criterion.

property is_increasing: bool¶: True if the criterion has increasing preference direction.

property is_decreasing: bool¶: True if the criterion has decreasing preference direction.

property is_single_peaked: bool¶: True if the criterion has single-peaked preference direction.

property integer_values: IntegerValues¶: Descriptor of the integer values allowed for this criterion, accessible if is_integer.

class EnumeratedValues¶

Descriptor of the enumerated values allowed for a criterion.

__init__(ordered_values: list[str])¶: Parameters map exactly to attributes with identical names.

get_value_rank(value: str) → int¶: Get the rank of a given value.

property ordered_values: list[str]¶: The values for this criterion, from the worst to the best.

property enumerated_values: EnumeratedValues¶: Descriptor of the enumerated values allowed for this criterion, accessible if is_enumerated.

class lincs.classification.Category¶

A category of a classification Problem.

__init__(name: str)¶: Parameters map exactly to attributes with identical names.

property name: str¶: The name of this category.

class lincs.classification.Problem¶

A classification problem, with criteria and categories.

__init__(criteria: list[Criterion], ordered_categories: list[Category])¶: Parameters map exactly to attributes with identical names.

property criteria: list[Criterion]¶: The criteria of this problem.

property ordered_categories: list[Category]¶: The categories of this problem, from the worst to the best.

dump(out: object)¶: Dump the problem to the provided .write-supporting file-like object, in YAML format.

static load(in: object) → Problem¶: Load a problem from the provided .read-supporting file-like object, in YAML format.

JSON_SCHEMA: str¶: The JSON schema defining the format used by dump and load, as a string.

class lincs.classification.AcceptedValues¶

The values accepted by a model for a criterion.

__init__(values: RealThresholds)¶: Constructor for thresholds on a real-valued criterion.

__init__(values: IntegerThresholds): Constructor for thresholds on an integer-valued criterion.

__init__(values: EnumeratedThresholds): Constructor for thresholds on an enumerated criterion.

__init__(values: RealIntervals): Constructor for intervals on a real-valued criterion.

__init__(values: IntegerIntervals): Constructor for intervals on an integer-valued criterion.

property value_type: ValueType¶: The type of values for the corresponding criterion.

property is_real: bool¶: True if the corresponding criterion is real-valued.

property is_integer: bool¶: True if the corresponding criterion is integer-valued.

property is_enumerated: bool¶: True if the corresponding criterion takes enumerated values.

class Kind¶

The different kinds of descriptors for accepted values.

class property thresholds: Kind¶: A threshold for each category.

class property intervals: Kind¶: An interval for each category.

property kind: Kind¶: The kind of descriptor for these accepted values.

property is_thresholds: bool¶: True if the descriptor is a set of thresholds.

property is_intervals: bool¶: True if the descriptor is a set of intervals.

class RealThresholds¶

Descriptor for thresholds for an real-valued criterion.

__init__(thresholds: list[float | None])¶: Parameters map exactly to attributes with identical names.

property thresholds: list[float | None]¶: The thresholds for this descriptor.

property real_thresholds: RealThresholds¶: Descriptor of the real thresholds, accessible if is_real and is_thresholds.

class IntegerThresholds¶

Descriptor for thresholds for an integer-valued criterion.

__init__(thresholds: list[int | None])¶: Parameters map exactly to attributes with identical names.

property thresholds: list[int | None]¶: The thresholds for this descriptor.

property integer_thresholds: IntegerThresholds¶: Descriptor of the integer thresholds, accessible if is_integer and is_thresholds.

class EnumeratedThresholds¶

Descriptor for thresholds for a criterion taking enumerated values.

__init__(thresholds: list[str | None])¶: Parameters map exactly to attributes with identical names.

property thresholds: list[str | None]¶: The thresholds for this descriptor.

property enumerated_thresholds: EnumeratedThresholds¶: Descriptor of the enumerated thresholds, accessible if is_enumerated and is_thresholds.

class RealIntervals¶

Descriptor for intervals for an real-valued criterion.

__init__(intervals: list[tuple[float, float] | None])¶: Parameters map exactly to attributes with identical names.

property intervals: list[tuple[float, float] | None]¶: The intervals for this descriptor.

property real_intervals: RealIntervals¶: Descriptor of the real intervals, accessible if is_real and is_intervals.

class IntegerIntervals¶

Descriptor for intervals for an integer-valued criterion.

__init__(intervals: list[tuple[int, int] | None])¶: Parameters map exactly to attributes with identical names.

property intervals: list[tuple[int, int] | None]¶: The intervals for this descriptor.

property integer_intervals: IntegerIntervals¶: Descriptor of the integer intervals, accessible if is_integer and is_intervals.

class lincs.classification.SufficientCoalitions¶

The coalitions of sufficient criteria to accept an alternative in a category.

__init__(weights: Weights)¶: Constructor for sufficient coalitions defined by weights.

__init__(roots: Roots): Constructor for sufficient coalitions defined by roots.

class Kind¶

The different kinds of descriptors for sufficient coalitions.

class property weights: Kind¶: For sufficient coalitions described by criterion weights.

class property roots: Kind¶: For sufficient coalitions described by the roots of their upset.

property kind: Kind¶: The kind of descriptor for these sufficient coalitions.

property is_weights: bool¶: True if the descriptor is a set of weights.

property is_roots: bool¶: True if the descriptor is a set of roots.

class Weights¶

Descriptor for sufficient coalitions defined by weights.

__init__(criterion_weights: list[float])¶: Parameters map exactly to attributes with identical names.

property criterion_weights: list[float]¶: The weights for each criterion.

property weights: Weights¶: Descriptor of the weights, accessible if is_weights.

class Roots¶

Descriptor for sufficient coalitions defined by roots.

__init__(problem: Problem, upset_roots: list[list[int]])¶: Parameters map exactly to attributes with identical names.

property upset_roots: list[list[int]]¶: The roots of the upset of sufficient coalitions.

property roots: Roots¶: Descriptor of the roots, accessible if is_roots.

class lincs.classification.Model¶

An NCS classification model.

__init__(problem: Problem, accepted_values: list[AcceptedValues], sufficient_coalitions: list[SufficientCoalitions])¶: The Model being initialized must correspond to the given Problem. Other parameters map exactly to attributes with identical names.

check_consistency_with(problem: Problem)¶: Raise DataValidationException if the model is not consistent with the provided problem.

property accepted_values: list[AcceptedValues]¶: The accepted values for each criterion.

property sufficient_coalitions: list[SufficientCoalitions]¶: The sufficient coalitions for each category.

dump(problem: Problem, out: object)¶: Dump the model to the provided .write-supporting file-like object, in YAML format.

static load(problem: Problem, in: object) → Model¶: Load a model for the provided Problem, from the provided .read-supporting file-like object, in YAML format.

JSON_SCHEMA: str¶: The JSON schema defining the format used by dump and load, as a string.

class lincs.classification.Performance¶

The performance of an alternative on a criterion.

__init__(performance: Real)¶: Constructor for a real-valued performance.

__init__(performance: Integer): Constructor for an integer-valued performance.

__init__(performance: Enumerated): Constructor for an enumerated performance.

property value_type: ValueType¶: The type of values for the corresponding criterion.

property is_real: bool¶: True if the corresponding criterion is real-valued.

property is_integer: bool¶: True if the corresponding criterion is integer-valued.

property is_enumerated: bool¶: True if the corresponding criterion takes enumerated values.

class Real¶

A performance for a real-valued criterion.

__init__(value: float)¶: Parameters map exactly to attributes with identical names.

property value: float¶: The numerical value of the real performance.

property real: Real¶: The real performance, accessible if is_real.

class Integer¶

A performance for an integer-valued criterion.

__init__(value: int)¶: Parameters map exactly to attributes with identical names.

property value: int¶: The numerical value of the integer performance.

property integer: Integer¶: The integer performance, accessible if is_integer.

class Enumerated¶

A performance for a criterion taking enumerated values.

__init__(value: str)¶: Parameters map exactly to attributes with identical names.

property value: str¶: The string value of the enumerated performance.

property enumerated: Enumerated¶: The enumerated performance, accessible if is_enumerated.

class lincs.classification.Alternative¶

An alternative, with its performance on each criterion, maybe classified.

__init__(name: str, profile: list[Performance], category_index: int | None = None)¶: Parameters map exactly to attributes with identical names.

property name: str¶: The name of the alternative.

property profile: list[Performance]¶: The performance profile of the alternative.

property category_index: int | None¶: The index of the category of the alternative, if it is classified.

class lincs.classification.Alternatives¶

A set of alternatives, maybe classified.

__init__(problem: Problem, alternatives: list[Alternative])¶: The Alternatives being initialized must correspond to the given Problem. Other parameters map exactly to attributes with identical names.

check_consistency_with(problem: Problem)¶: Raise DataValidationException if these alternatives are not consistent with the provided problem.

property alternatives: list[Alternative]¶: The Alternative objects in this set.

dump(problem: Problem, out: object)¶: Dump the set of alternatives to the provided .write-supporting file-like object, in CSV format.

static load(problem: Problem, in: object) → Alternatives¶: Load a set of alternatives (classified or not) from the provided .read-supporting file-like object, in CSV format.

lincs.classification.generate_problem(criteria_count: int, categories_count: int, random_seed: int, normalized_min_max: bool = True, allowed_preference_directions: list[PreferenceDirection] = [PreferenceDirection.increasing], allowed_value_types: list[ValueType] = [ValueType.real]) → Problem¶: Generate a Problem with criteria_count criteria and categories_count categories.

lincs.classification.generate_mrsort_model(problem: Problem, random_seed: int, fixed_weights_sum: float | None = None) → Model¶: Generate an MR-Sort model for the provided Problem.

exception lincs.classification.BalancedAlternativesGenerationException¶: Raised by generate_alternatives when it fails to find alternatives to balance the categories.

lincs.classification.generate_alternatives(problem: Problem, model: Model, alternatives_count: int, random_seed: int, max_imbalance: float | None = None) → Alternatives¶: Generate a set of alternatives_count pseudo-random alternatives for the provided Problem, classified according to the provided Model.

lincs.classification.misclassify_alternatives(problem: Problem, alternatives: Alternatives, count: int, random_seed: int)¶: Misclassify count alternatives from the provided Alternatives.

class lincs.classification.LearnUcncsByMaxSatByCoalitionsUsingEvalmaxsat¶

The “max-SAT by coalitions” approach to learn Uc-NCS models.

__init__(problem: Problem, learning_set: Alternatives, nb_minimize_threads: int = 0, timeout_fast_minimize: int = 60, coef_minimize_time: int = 2)¶: Constructor.

perform() → Model¶: Actually perform the learning and return the learned model.

class lincs.classification.LearnUcncsByMaxSatBySeparationUsingEvalmaxsat¶

The “max-SAT by separation” approach to learn Uc-NCS models.

__init__(problem: Problem, learning_set: Alternatives, nb_minimize_threads: int = 0, timeout_fast_minimize: int = 60, coef_minimize_time: int = 2)¶: Constructor.

perform() → Model¶: Actually perform the learning and return the learned model.

class lincs.classification.LearnUcncsBySatByCoalitionsUsingMinisat¶

The “SAT by coalitions” approach to learn Uc-NCS models.

__init__(problem: Problem, learning_set: Alternatives)¶: Constructor.

perform() → Model¶: Actually perform the learning and return the learned model.

class lincs.classification.LearnUcncsBySatBySeparationUsingMinisat¶

The “SAT by separation” approach to learn Uc-NCS models.

__init__(problem: Problem, learning_set: Alternatives)¶: Constructor.

perform() → Model¶: Actually perform the learning and return the learned model.

class lincs.classification.PreprocessedLearningSet¶

A representation of a learning set with its data normalized as ranks (unsigned integers).

__init__(problem: Problem, learning_set: Alternatives)¶: Constructor, pre-processing the learning set into a simpler form for learning.

property criteria_count: int¶: Number of criteria in the Problem.

property categories_count: int¶: Number of categories in the Problem.

property boundaries_count: int¶: Number of boundaries in the Problem, i.e categories_count - 1.

property alternatives_count: int¶: Number of alternatives in the learning_set.

property single_peaked: list[bool]¶: Indexed by [criterion_index]. Whether each criterion is single-peaked or not.

property values_counts: list[int]¶: Indexed by [criterion_index]. Number of different values for each criterion, in the learning_set and min and max values for numerical criteria.

property performance_ranks: list[list[int]]¶: Indexed by [criterion_index][alternative_index]. Rank of each alternative in the learning_set for each criterion.

property assignments: list[int]¶: Indexed by [alternative_index]. Category index of each alternative in the learning_set.

class lincs.classification.LearnMrsortByWeightsProfilesBreed¶

The approach described in Olivier Sobrie’s PhD thesis to learn MR-Sort models.

__init__(preprocessed_learning_set: PreprocessedLearningSet, models_being_learned: ModelsBeingLearned, profiles_initialization_strategy: ProfilesInitializationStrategy, weights_optimization_strategy: WeightsOptimizationStrategy, profiles_improvement_strategy: ProfilesImprovementStrategy, breeding_strategy: BreedingStrategy, termination_strategy: TerminationStrategy, observers: list[Observer] = [])¶: Constructor accepting the strategies to use for each step of the learning.

class ModelsBeingLearned¶

Data shared by all the strategies used in this learning.

__init__(preprocessed_learning_set: PreprocessedLearningSet, models_count: int, random_seed: int)¶: Constructor, allocating but not initializing data about models about to be learned.

property models_count: int¶: The number of in-progress models for this learning.

property random_generators: list[UniformRandomBitsGenerator]¶: Indexed by [model_index]. Random number generators associated to each in-progress model.

property iteration_index: int¶: The index of the current iteration of the WPB algorithm.

property model_indexes: list[int]¶: Indexed by 0 to models_count - 1. Indexes of in-progress models ordered by increasing accuracy.

property weights: list[list[int]]¶: Indexed by [model_index][criterion_index]. The current MR-Sort weight of each criterion for each model.

property low_profile_ranks: list[list[list[int]]]¶: Indexed by [model_index][boundary_index][criterion_index]. The current rank of each low profile, for each model and criterion.

property high_profile_rank_indexes: list[unsigned]¶: Indexed by [criterion_index]. The index in high_profile_ranks, for each single-peaked criterion.

property high_profile_ranks: list[list[list[int]]]¶: Indexed by [model_index][boundary_index][high_profile_rank_indexes[criterion_index]]. The current rank of each high profile, for each model and single-peaked criterion.

property accuracies: list[int]¶: Indexed by [model_index]. Accuracy of each in-progress model.

get_best_accuracy() → int¶: Return the accuracy of the best model so far.

get_best_model() → Model¶: Return the best model so far.

get_model(model_index: int) → Model¶: Return the model at the given index.

recompute_accuracy(model_index: int)¶: Recompute the accuracy of the model at the given index.

class ProfilesInitializationStrategy¶

Abstract base class for profiles initialization strategies.

initialize_profiles(model_indexes_begin: int, model_indexes_end: int)¶: Method to override. Should initialize all low_profile_ranks and high_profile_ranks of models at indexes in [model_indexes[i] for i in range(model_indexes_begin, model_indexes_end)].

class WeightsOptimizationStrategy¶

Abstract base class for weights optimization strategies.

optimize_weights(model_indexes_begin: int, model_indexes_end: int)¶: Method to override. Should optimize weights of models at indexes in [model_indexes[i] for i in range(model_indexes_begin, model_indexes_end)].

class ProfilesImprovementStrategy¶

Abstract base class for profiles improvement strategies.

improve_profiles(model_indexes_begin: int, model_indexes_end: int)¶: Method to override. Should improve low_profile_ranks and high_profile_ranks of models at indexes in [model_indexes[i] for i in range(model_indexes_begin, model_indexes_end)].

class BreedingStrategy¶

Abstract base class for breeding strategies.

breed()¶: Method to override.

class TerminationStrategy¶

Abstract base class for termination strategies.

terminate() → bool¶: Method to override. Should return True if the learning should stop, False otherwise.

class Observer¶

Abstract base class for observation strategies.

after_iteration()¶: Method to override. Called after each iteration. Should not change anything in the learning data.

before_return()¶: Method to override. Called just before returning the learned model. Should not change anything in the learning data.

perform() → Model¶: Actually perform the learning and return the learned model.

class lincs.classification.InitializeProfilesForProbabilisticMaximalDiscriminationPowerPerCriterion¶

The profiles initialization strategy described in Olivier Sobrie’s PhD thesis.

__init__(preprocessed_learning_set: PreprocessedLearningSet, models_being_learned: ModelsBeingLearned)¶: Constructor. Keeps a reference to the learning data.

initialize_profiles(model_indexes_begin: int, model_indexes_end: int)¶: Overrides the base method.

class lincs.classification.OptimizeWeightsUsingAlglib¶

The weights optimization strategy described in Olivier Sobrie’s PhD thesis. The linear program is solved using AlgLib.

__init__(preprocessed_learning_set: PreprocessedLearningSet, models_being_learned: ModelsBeingLearned)¶: Constructor. Keeps a reference to the learning data.

optimize_weights(model_indexes_begin: int, model_indexes_end: int)¶: Overrides the base method.

class lincs.classification.OptimizeWeightsUsingGlop¶

The weights optimization strategy described in Olivier Sobrie’s PhD thesis. The linear program is solved using GLOP.

__init__(preprocessed_learning_set: PreprocessedLearningSet, models_being_learned: ModelsBeingLearned)¶: Constructor. Keeps a reference to the learning data.

optimize_weights(model_indexes_begin: int, model_indexes_end: int)¶: Overrides the base method.

class lincs.classification.ImproveProfilesWithAccuracyHeuristicOnCpu¶

The profiles improvement strategy described in Olivier Sobrie’s PhD thesis. Run on the CPU.

__init__(preprocessed_learning_set: PreprocessedLearningSet, models_being_learned: ModelsBeingLearned)¶: Constructor. Keeps a reference to the learning data.

improve_profiles(model_indexes_begin: int, model_indexes_end: int)¶: Overrides the base method.

class lincs.classification.ImproveProfilesWithAccuracyHeuristicOnGpu¶

The profiles improvement strategy described in Olivier Sobrie’s PhD thesis. Run on the CUDA-capable GPU.

__init__(preprocessed_learning_set: PreprocessedLearningSet, models_being_learned: ModelsBeingLearned)¶: Constructor. Keeps a reference to the learning data.

improve_profiles(model_indexes_begin: int, model_indexes_end: int)¶: Overrides the base method.

class lincs.classification.ReinitializeLeastAccurate¶

The breeding strategy described in Olivier Sobrie’s PhD thesis: re-initializes count in-progress models.

__init__(models_being_learned: ModelsBeingLearned, profiles_initialization_strategy: ProfilesInitializationStrategy, weights_optimization_strategy: WeightsOptimizationStrategy, count: int)¶: Constructor. Keeps references to the profiles initialization strategy and the learning data.

breed()¶: Overrides the base method.

class lincs.classification.TerminateAfterIterations¶

Termination strategy. Terminates the learning after a given number of iterations.

__init__(models_being_learned: ModelsBeingLearned, max_iterations_count: int)¶: Constructor. Keeps a reference to the learning data.

terminate() → bool¶: Overrides the base method.

class lincs.classification.TerminateAfterIterationsWithoutProgress¶

Termination strategy. Terminates the learning after a given number of iterations without progress.

__init__(models_being_learned: ModelsBeingLearned, max_iterations_count: int)¶: Constructor. Keeps a reference to the learning data.

terminate() → bool¶: Overrides the base method.

class lincs.classification.TerminateAfterSeconds¶

Termination strategy. Terminates the learning after a given duration.

__init__(max_seconds: float)¶: Constructor.

terminate() → bool¶: Overrides the base method.

class lincs.classification.TerminateAfterSecondsWithoutProgress¶

Termination strategy. Terminates the learning after a given duration without progress.

__init__(models_being_learned: ModelsBeingLearned, max_seconds: float)¶: Constructor. Keeps a reference to the learning data.

terminate() → bool¶: Overrides the base method.

class lincs.classification.TerminateAtAccuracy¶

Termination strategy. Terminates the learning when the best model reaches a given accuracy.

__init__(models_being_learned: ModelsBeingLearned, target_accuracy: int)¶: Constructor. Keeps a reference to the learning data.

terminate() → bool¶: Overrides the base method.

class lincs.classification.TerminateWhenAny¶

Termination strategy. Terminates the learning when one or more termination strategies decide to terminate.

__init__(termination_strategies: list[TerminationStrategy])¶: Constructor. Keeps references to each termination strategies.

terminate() → bool¶: Overrides the base method.

class lincs.classification.ClassificationResult¶

Return type for classify_alternatives.

property changed: int¶: Number of alternatives that were not in the same category before and after classification.

property unchanged: int¶: Number of alternatives that were in the same category before and after classification.

lincs.classification.classify_alternatives(problem: Problem, model: Model, alternatives: Alternatives) → ClassificationResult¶: Classify the provided Alternatives according to the provided Model.

lincs.classification.describe_model(problem: Problem, model: Model) → Iterable[str]¶: Generate a human-readable description of a classification model.

lincs.classification.describe_problem(problem: Problem) → Iterable[str]¶: Generate a human-readable description of a classification problem.

lincs.classification.visualize_model(problem: Problem, model: Model, alternatives: Iterable[Alternative], axes: matplotlib.axes._axes.Axes)¶: Create a visual representation of a classification model and classified alternatives, using Matplotlib.

Reference¶

File formats¶

The problem file¶

The NCS model file¶

The alternatives file¶

Command-line interface¶

lincs¶

classification-accuracy¶

classify¶

describe¶

classification-model¶

classification-problem¶

generate¶

classification-model¶

classification-problem¶

classified-alternatives¶

info¶

has-gpu¶

learn¶

classification-model¶

visualize¶

classification-model¶

Python API¶

The `lincs` package¶

The `lincs.classification` module¶

lincs

Navigation

Related Topics

Reference¶

File formats¶

The problem file¶

The NCS model file¶

The alternatives file¶

Command-line interface¶

lincs¶

classification-accuracy¶

classify¶

describe¶

classification-model¶

classification-problem¶

generate¶

classification-model¶

classification-problem¶

classified-alternatives¶

info¶

has-gpu¶

learn¶

classification-model¶

visualize¶

classification-model¶

Python API¶

The lincs package¶

The lincs.classification module¶

The `lincs` package¶

The `lincs.classification` module¶