diff --git a/README.rst b/README.rst
index 92d80bcc..a03e087b 100644
--- a/README.rst
+++ b/README.rst
@@ -8,11 +8,16 @@
*lincs* (Learn and Infer Non Compensatory Sortings) is a collection of `MCDA In this document, we denote the interval of integers from \(a\) to \(b - 1\) included by \([a..b)\).
Most often, \(a\) will be zero.
-This choice matches the indexing convention used in most modern programming language, so our documentation is as close as possible to our implementation.
+This choice matches the indexing convention used in the Python and C++ programming languages,
+so our documentation is as close as possible to our implementation.
For example, \([0..4) = \{0, 1, 2, 3\}\).
Note that \([0..n)\) contains \(n\) elements. For a given set \(S\), we denote the set of all its subsets (a.k.a. its power set) by \(\mathcal{P}(S)\).
@@ -122,11 +123,11 @@ Note that this definition extends naturally if we denote \(\mathcal{F}^0 = [0..n)\) and \(b^0 = (\min(X_0), ..., \min(X_{n-1}))\).
+ Note that this definition extends naturally if we denote \(\mathcal{F}^0 = \mathcal{P}([0..n))\) and \(b^0 = (\min(X_0), ..., \min(X_{n-1}))\).
The definition of \(f\) then simplifies to \(x \mapsto \max \{ h \in [0..p): \{ i \in [0..n): x_i \succcurlyeq_i b^h_i \} \in \mathcal{F}^h \}\). This definition may differ slightly from the one you’re used to, but it should be formally equivalent.
We use it in lincs because it is somewhat simple and matches the implementation quite well. The constraints in the definition all ensure NDS models behave according to intuition: The constraints in the definition all ensure NCS models behave according to intuition: the ordering of profiles ensures consistency with the order on categories the up-closed-ness-by-inclusion(!) of the sufficient coalitions matches the intuition that they are sufficient criteria: if a few criteria are sufficient, then more criteria are still sufficient \(w_M + w_H \ge 1\) (because \(\{M, H\} \in \mathcal{F}^1\)) \(w_P + w_H \ge 1\) (because \(\{P, H\} \in \mathcal{F}^1\)) Summing the first two equations gives \(w_M + w_P + w_L + w_H \lt 2\), and summing teh last four gives \(w_M + w_P + w_L + w_H \ge 2\),
+ Summing the first two equations gives \(w_M + w_P + w_L + w_H \lt 2\), and summing the last four gives \(w_M + w_P + w_L + w_H \ge 2\),
so there is no solution, and that model is not MR-Sort. By contrast, the coalitions \(\mathcal{F}^2\) of the previous model example can be expressed using the following weights:
\(w_M = 0.4\), \(w_P = 0.4\), \(w_L = 0.4\), \(w_H = 0.4\): coalitions of at most two criteria have weights sums less than 1,
@@ -460,9 +461,8 @@ lincs provides ways to generate synthetic pseudo-random problems, models and training sets (noisy or clean).
-The same file formats are used for synthetic and real-world data.Conceptual overview¶
Learning and classifying
\[f: x \mapsto \max (\{0\} \cup \{ h \in [1..p): \{ i \in [0..n): x_i \succcurlyeq_i b^h_i \} \in \mathcal{F}^h \})\]
-
-Example
Classification accuracy
-
lincs provides ways to generate synthetic pseudo-random problems, models and training sets (noisy or clean).
lincs (Learn and Infer Non Compensatory Sortings) is a collection of MCDA algorithms, usable as a command-line utility.
-@todo(Feature, later) Make it usable as a Python package.
-@todo(Feature, later) Make it usable as a C++ library.
-lincs supports Linux, macOS and Windows, with the exception that GPU-based algorithms are not available on macOS, because CUDA itself is not available there.
+@todo(Feature, later) Make lincs usable as a Python package.
+@todo(Feature, later) Make lincs usable as a C++ library.
+lincs supports Linux, macOS and Windows, with the exception that GPU-based algorithms are not available on macOS, because CUDA itself is not available there. +On these 3 OSes, lincs only support x86_64 CPUs.
+@todo(Feature, later) Support M1 and M2 chips on macOS.
+@todo(Feature, much later) Support ARM processors in general.
lincs is licensed under the GNU Lesser General Public License v3.0 as indicated by the two files COPYING and COPYING.LESSER.
@todo(Project management, when we publish a paper, later) Add a note asking academics to kindly cite our work.
lincs is available for install from the Python package index. @@ -65,7 +68,7 @@
lincs is designed to be easy to extend with new algorithms of even replace parts of existing algorithms. +
lincs is designed to be easy to extend with new algorithms or even replace parts of existing algorithms. See our contributor guide for more details.
lincs uses text-based (YAML and CSV) file formats. -The same formats are used when lincs reads files or when it outputs to files. 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.
Here is an example of a problem file:
-kind: classification-problem
-format_version: 1
-criteria:
- - name: Criterion 1
- value_type: real
- category_correlation: growing
- min_value: 0
- max_value: 20
- - name: Criterion 2
- value_type: real
- category_correlation: decreasing
- min_value: -5
- max_value: 5
-categories:
- - name: Low
- - name: Medium
- - name: High
+kind: classification-problem
+format_version: 1
+criteria:
+ - name: Criterion 1
+ value_type: real
+ category_correlation: growing
+ min_value: 0
+ max_value: 20
+ - name: Criterion 2
+ value_type: real
+ category_correlation: decreasing
+ min_value: -5
+ max_value: 5
+categories:
+ - name: Low
+ - name: Medium
+ - name: High
The two first keys, kind
and format_version
are here to identify exactly the file format.
@@ -103,18 +103,18 @@
Categorieskind: ncs-classification-model
-format_version: 1
-accepted_values:
- - kind: thresholds
- thresholds: [7.49331188, 15.9249287]
- - kind: thresholds
- thresholds: [4.49812794, -3.15932083]
-sufficient_coalitions:
- - &coalitions
- kind: weights
- criterion_weights: [0.938825667, 0.343733728]
- - *coalitions
+kind: ncs-classification-model
+format_version: 1
+accepted_values:
+ - kind: thresholds
+ thresholds: [7.49331188, 15.9249287]
+ - kind: thresholds
+ thresholds: [4.49812794, -3.15932083]
+sufficient_coalitions:
+ - &coalitions
+ kind: weights
+ criterion_weights: [0.938825667, 0.343733728]
+ - *coalitions
Like for problem files, the two first keys must take exactly these values.
@@ -186,20 +186,20 @@ Sufficient coalitions
Here is another model corresponding to the problem file above, but this time using the roots
kind of sufficient coalitions,
and using different coalitions for the two boundaries (so, no YAML anchor):
-kind: ncs-classification-model
-format_version: 1
-accepted_values:
- - kind: thresholds
- thresholds: [7.49331188, 15.9249287]
- - kind: thresholds
- thresholds: [4.49812794, -3.15932083]
-sufficient_coalitions:
- - kind: roots
- upset_roots:
- - [2]
- - kind: roots
- upset_roots:
- - [1, 2]
+kind: ncs-classification-model
+format_version: 1
+accepted_values:
+ - kind: thresholds
+ thresholds: [7.49331188, 15.9249287]
+ - kind: thresholds
+ thresholds: [4.49812794, -3.15932083]
+sufficient_coalitions:
+ - kind: roots
+ upset_roots:
+ - [2]
+ - kind: roots
+ upset_roots:
+ - [1, 2]
@@ -210,12 +210,12 @@ “Alternatives” files
Like model files, alternatives files are always associated to a problem file.
Here is an example corresponding to the problem above:
-name,"Criterion 1","Criterion 2",category
-"Alternative 1",10.8156891,4.39045048,Medium
-"Alternative 2",0.25551182,-1.45864725,Low
-"Alternative 3",18.4786396,4.31117153,Medium
-"Alternative 4",18.0154629,1.33949804,Medium
-"Alternative 5",9.30789757,2.66963387,Medium
+name,"Criterion 1","Criterion 2",category
+"Alternative 1",10.8156891,4.39045048,Medium
+"Alternative 2",0.25551182,-1.45864725,Low
+"Alternative 3",18.4786396,4.31117153,Medium
+"Alternative 4",18.0154629,1.33949804,Medium
+"Alternative 5",9.30789757,2.66963387,Medium
Its header line contains the names of its columns.
@@ -223,12 +223,12 @@
“Alternatives” filescategory, contains the names of the categories in which each alternative is classified.
Values in the category
column can be empty to describe alternatives that are not (yet) classified:
-name,"Criterion 1","Criterion 2",category
-"Alternative 1",10.8156891,4.39045048,
-"Alternative 2",0.25551182,-1.45864725,
-"Alternative 3",18.4786396,4.31117153,
-"Alternative 4",18.0154629,1.33949804,
-"Alternative 5",9.30789757,2.66963387,
+name,"Criterion 1","Criterion 2",category
+"Alternative 1",10.8156891,4.39045048,
+"Alternative 2",0.25551182,-1.45864725,
+"Alternative 3",18.4786396,4.31117153,
+"Alternative 4",18.0154629,1.33949804,
+"Alternative 5",9.30789757,2.66963387,
@@ -258,7 +258,7 @@ About randomness¶
With lincs generate classification-problem
, you can generate a classification problem file.
Using its default settings, you just have to pass it the numbers of criteria and categories you want, as you saw in our get started guide:
-lincs generate classification-problem 4 3
+lincs generate classification-problem 4 3
The --help
option on the command-line and our reference documentation describe the options available to tweak the generated problem.
@@ -272,7 +272,7 @@
Generating a problemGenerating a model¶
With lincs generate classification-model
, you can generate a classification model file.
Using its default settings, you just have to pass it the problem file you want to use:
-lincs generate classification-model problem.yml
+lincs generate classification-model problem.yml
For now, lincs can only generate MR-Sort models, so the --model-type
option can only take its default value: mrsort
.
@@ -284,7 +284,7 @@
Generating a model
Generating alternatives¶
With its default settings, lincs generate classified-alternatives
requires only the problem and model files and the number of alternatives to generate:
-lincs generate classified-alternatives problem.yml model.yml 100
+lincs generate classified-alternatives problem.yml model.yml 100
This generates 100 random alternatives, and then classifies them according to the model.
@@ -306,7 +306,7 @@ Generating alternativesLearning a model¶
As you’ve seen in our get started guide, the basic command to learn a classification model with lincs is lincs learn classification-model
.
With its default settings, you just have to pass it a problem file and a learning set file (of classified alternatives):
-lincs learn classification-model problem.yml learning-set.csv
+lincs learn classification-model problem.yml learning-set.csv
Its --help
option and our reference documentation give you a list of the numerous options it accepts.
@@ -372,8 +372,8 @@ “Weights” step--mrsort.weights-profiles-breed.linear-program.solver option.
By default, it uses GLOP, which is a part of Google’s OR-Tools.
Here is an example using the Alglib solver:
-lincs learn classification-model problem.yml learning-set.csv \
- --mrsort.weights-profiles-breed.linear-program.solver alglib
+lincs learn classification-model problem.yml learning-set.csv \
+ --mrsort.weights-profiles-breed.linear-program.solver alglib
It should produce a very similar model, with slight numerical differences.
@@ -390,8 +390,8 @@ “Profiles” steplincs info has-gpu.
Here is an example:
-lincs learn classification-model problem.yml learning-set.csv \
- --mrsort.weights-profiles-breed.accuracy-heuristic.processor gpu
+lincs learn classification-model problem.yml learning-set.csv \
+ --mrsort.weights-profiles-breed.accuracy-heuristic.processor gpu
It should produce the exact same model as when using the CPU;