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 |
||||||
|
type |
string |
||||
const |
classification-problem |
|||||
|
type |
integer |
||||
const |
1 |
|||||
|
Structural information about criteria used in the classification problem. |
|||||
type |
array |
|||||
items |
type |
object |
||||
oneOf |
properties |
|||||
|
type |
string |
||||
|
May be extended in the future to handle criteria with integer values, or explicitly enumerated values. |
|||||
type |
string |
|||||
enum |
real, integer |
|||||
|
May be extended in the future to handle single-peaked criteria, or criteria with unknown preference direction. |
|||||
type |
string |
|||||
enum |
increasing, isotone, decreasing, antitone |
|||||
|
type |
number |
||||
|
type |
number |
||||
additionalProperties |
False |
|||||
properties |
||||||
|
type |
string |
||||
|
type |
string |
||||
const |
enumerated |
|||||
|
Ordered list of values that can be taken by the criterion. |
|||||
type |
array |
|||||
items |
type |
string |
||||
minItems |
1 |
|||||
additionalProperties |
False |
|||||
minItems |
1 |
|||||
|
Structural information about categories in the classification problem, ordered from the worst to the best. |
|||||
type |
array |
|||||
items |
type |
object |
||||
properties |
||||||
|
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 |
|||||||
|
type |
string |
|||||
const |
ncs-classification-model |
||||||
|
type |
integer |
|||||
const |
1 |
||||||
|
For each criterion in the classification problem, a way to determine the accepted values for each category. |
||||||
type |
array |
||||||
items |
type |
object |
|||||
oneOf |
properties |
||||||
|
type |
string |
|||||
const |
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 |
||||||
|
For each category but the lowest, a description of the sufficient coalitions for that category. |
||||||
type |
array |
||||||
items |
type |
object |
|||||
oneOf |
properties |
||||||
|
type |
string |
|||||
const |
weights |
||||||
|
type |
array |
|||||
items |
type |
number |
|||||
minItems |
1 |
||||||
additionalProperties |
False |
||||||
properties |
|||||||
|
type |
string |
|||||
const |
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
ismrsort
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
isucncs
- 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
isucncs
--ucncs.strategy
ismax-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
isucncs
--ucncs.strategy
ismax-sat-by-separation
--ucncs.max-sat-by-separation.solver
iseval-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
isucncs
--ucncs.strategy
ismax-sat-by-separation
--ucncs.max-sat-by-separation.solver
iseval-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
isucncs
--ucncs.strategy
ismax-sat-by-separation
--ucncs.max-sat-by-separation.solver
iseval-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
isucncs
--ucncs.strategy
ismax-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
isucncs
--ucncs.strategy
ismax-sat-by-coalitions
--ucncs.max-sat-by-coalitions.solver
iseval-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
isucncs
--ucncs.strategy
ismax-sat-by-coalitions
--ucncs.max-sat-by-coalitions.solver
iseval-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
isucncs
--ucncs.strategy
ismax-sat-by-coalitions
--ucncs.max-sat-by-coalitions.solver
iseval-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
ismrsort
- 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
ismrsort
--mrsort.strategy
isweights-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
ismrsort
--mrsort.strategy
isweights-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
ismrsort
--mrsort.strategy
isweights-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
ismrsort
--mrsort.strategy
isweights-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
ismrsort
--mrsort.strategy
isweights-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
ismrsort
--mrsort.strategy
isweights-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
ismrsort
--mrsort.strategy
isweights-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
ismrsort
--mrsort.strategy
isweights-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
ismrsort
--mrsort.strategy
isweights-profiles-breed
--mrsort.weights-profiles-breed.weights-strategy
islinear-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
ismrsort
--mrsort.strategy
isweights-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
ismrsort
--mrsort.strategy
isweights-profiles-breed
--mrsort.weights-profiles-breed.profiles-strategy
isaccuracy-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
ismrsort
--mrsort.strategy
isweights-profiles-breed
--mrsort.weights-profiles-breed.profiles-strategy
isaccuracy-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
ismrsort
--mrsort.strategy
isweights-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
ismrsort
--mrsort.strategy
isweights-profiles-breed
--mrsort.weights-profiles-breed.breed-strategy
isreinitialize-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
ismrsort
--mrsort.strategy
isweights-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
ismrsort
--mrsort.strategy
isweights-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.
- 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 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
andload
, 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 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.
- 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__(roots: Roots)
Constructor for sufficient coalitions defined by roots.
- class Kind¶
The different kinds of descriptors for 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.
- 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 givenProblem
. 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
andload
, as a string.
- class lincs.classification.Performance¶
The performance of an alternative on a criterion.
- __init__(performance: Integer)
Constructor for an integer-valued performance.
- __init__(performance: Enumerated)
Constructor for an enumerated performance.
- 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.
- 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.
- 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 givenProblem
. 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
withcriteria_count
criteria andcategories_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 providedProblem
, classified according to the providedModel
.
- lincs.classification.misclassify_alternatives(problem: Problem, alternatives: Alternatives, count: int, random_seed: int)¶
Misclassify
count
alternatives from the providedAlternatives
.
- 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.
- 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.
- class lincs.classification.LearnUcncsBySatByCoalitionsUsingMinisat¶
The “SAT by coalitions” approach to learn Uc-NCS models.
- __init__(problem: Problem, learning_set: Alternatives)¶
Constructor.
- class lincs.classification.LearnUcncsBySatBySeparationUsingMinisat¶
The “SAT by separation” approach to learn Uc-NCS models.
- __init__(problem: Problem, learning_set: Alternatives)¶
Constructor.
- 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 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 thelearning_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 thelearning_set
for each criterion.
- property assignments: Iterable[int]¶
Indexed by
[alternative_index]
. Category index of each alternative in thelearning_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
tomodels_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.
- 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 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.
- 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 providedModel
.
- 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.