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

May be extended in the future to handle criteria with integer values, or explicitly enumerated values.

type

string

enum

real, integer

  • preference_direction

May be extended in the future to handle single-peaked criteria, or criteria with unknown preference direction.

type

string

enum

increasing, isotone, decreasing, antitone

  • 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

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)

--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 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 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 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: Iterable[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: Iterable[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: Iterable[Criterion], ordered_categories: Iterable[Category])

Parameters map exactly to attributes with identical names.

property criteria: Iterable[Criterion]

The criteria of this problem.

property ordered_categories: Iterable[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.

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.

property kind: Kind

The kind of descriptor for these accepted values.

property is_thresholds: bool

True if the descriptor is a set of thresholds.

class RealThresholds

Descriptor for thresholds for an real-valued criterion.

__init__(thresholds: Iterable[float])

Parameters map exactly to attributes with identical names.

property thresholds: Iterable[float]

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: Iterable[int])

Parameters map exactly to attributes with identical names.

property thresholds: Iterable[int]

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: Iterable[str])

Parameters map exactly to attributes with identical names.

property thresholds: Iterable[str]

The thresholds for this descriptor.

property enumerated_thresholds: EnumeratedThresholds

Descriptor of the enumerated thresholds, accessible if is_enumerated and is_thresholds.

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: Iterable[float])

Parameters map exactly to attributes with identical names.

property criterion_weights: Iterable[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: Iterable[Iterable[int]])

Parameters map exactly to attributes with identical names.

property upset_roots: Iterable[Iterable[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: Iterable[AcceptedValues], sufficient_coalitions: Iterable[SufficientCoalitions])

The Model being initialized must correspond to the given Problem. Other parameters map exactly to attributes with identical names.

property accepted_values: Iterable[AcceptedValues]

The accepted values for each criterion.

property sufficient_coalitions: Iterable[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: Iterable[Performance], category_index: float | None = None)

Parameters map exactly to attributes with identical names.

property name: str

The name of the alternative.

property profile: Iterable[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: Iterable[Alternative])

The Alternatives being initialized must correspond to the given Problem. Other parameters map exactly to attributes with identical names.

property alternatives: Iterable[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: Iterable[PreferenceDirection] = [], allowed_value_types: Iterable[ValueType] = []) 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.LearnMrsortByWeightsProfilesBreed

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

__init__(learning_data: LearningData, profiles_initialization_strategy: ProfilesInitializationStrategy, weights_optimization_strategy: WeightsOptimizationStrategy, profiles_improvement_strategy: ProfilesImprovementStrategy, breeding_strategy: BreedingStrategy, termination_strategy: TerminationStrategy, observers: Iterable[Observer] = [])

Constructor accepting the strategies to use for each step of the learning.

class LearningData

Data shared by all the strategies used in this learning.

__init__(problem: Problem, learning_set: Alternatives, models_count: int, random_seed: int)

Constructor, pre-processing the learning set into a simpler form for strategies.

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 values_counts: Iterable[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: Iterable[Iterable[int]]

Indexed by [criterion_index][alternative_index]. Rank of each alternative in the learning_set for each criterion.

property assignments: Iterable[int]

Indexed by [alternative_index]. Category index of each alternative in the learning_set.

property models_count: int

The number of in-progress models for this learning.

property urbgs: Iterable[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: Iterable[int]

Indexed by 0 to models_count - 1. Indexes of in-progress models ordered by increasing accuracy.

property weights: Iterable[Iterable[int]]

Indexed by [model_index][criterion_index]. The current MR-Sort weight of each criterion for each model.

property profile_ranks: Iterable[Iterable[Iterable[int]]]

Indexed by [model_index][profile_index][criterion_index]. The current rank of each profile, for each model and criterion.

property accuracies: Iterable[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.

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 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 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__(learning_data: LearningData)

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__(learning_data: LearningData)

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__(learning_data: LearningData)

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__(learning_data: LearningData)

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__(learning_data: LearningData)

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__(learning_data: LearningData, profiles_initialization_strategy: ProfilesInitializationStrategy, 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__(learning_data: LearningData, 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__(learning_data: LearningData, 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__(learning_data: LearningData, 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__(learning_data: LearningData, 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: Iterable[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.