Skip to content

Commit

Permalink
Merge branch 'topics/doc'
Browse files Browse the repository at this point in the history
  • Loading branch information
jacquev6 committed Oct 24, 2023
2 parents f7a4768 + fcdaa1f commit 3ba502a
Show file tree
Hide file tree
Showing 17 changed files with 113 additions and 93 deletions.
11 changes: 8 additions & 3 deletions README.rst
Original file line number Diff line number Diff line change
Expand Up @@ -8,11 +8,16 @@
*lincs* (Learn and Infer Non Compensatory Sortings) is a collection of `MCDA <https://en.wikipedia.org/wiki/Multiple-criteria_decision_analysis>`_ algorithms, usable as a command-line utility.

@todo(Feature, later) Make it usable as a Python package.
@todo(Feature, later) Make *lincs* usable as a Python package.

@todo(Feature, later) Make it usable as a C++ library.
@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 <COPYING>`_ and `COPYING.LESSER <COPYING.LESSER>`_.

Expand Down Expand Up @@ -50,7 +55,7 @@ Just follow the "Get started" section below.
Provide a base for developing new MCDA algorithms
-------------------------------------------------

*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 <https://mics-lab.github.io/lincs/contributor-guide.html>`_ for more details.


Expand Down
12 changes: 6 additions & 6 deletions doc-sources/conceptual-overview.rst
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,8 @@ Notation

In this document, we denote the interval of integers from :math:`a` to :math:`b - 1` included by :math:`[a..b)`.
Most often, :math:`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, :math:`[0..4) = \{0, 1, 2, 3\}`.
Note that :math:`[0..n)` contains :math:`n` elements.

Expand Down Expand Up @@ -110,13 +111,13 @@ Additionally, this set of coalitions can be different for each category.
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 \})
Note that this definition extends naturally if we denote :math:`\mathcal{F}^0 = [0..n)` and :math:`b^0 = (\min(X_0), ..., \min(X_{n-1}))`.
Note that this definition extends naturally if we denote :math:`\mathcal{F}^0 = \mathcal{P}([0..n))` and :math:`b^0 = (\min(X_0), ..., \min(X_{n-1}))`.
The definition of :math:`f` then simplifies to :math:`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
Expand Down Expand Up @@ -453,7 +454,7 @@ This gives us :math:`|\mathcal{P}(\{M, P, L, H\})| = 16` equations, amongst whic
- :math:`w_M + w_H \ge 1` (because :math:`\{M, H\} \in \mathcal{F}^1`)
- :math:`w_P + w_H \ge 1` (because :math:`\{P, H\} \in \mathcal{F}^1`)

Summing the first two equations gives :math:`w_M + w_P + w_L + w_H \lt 2`, and summing teh last four gives :math:`w_M + w_P + w_L + w_H \ge 2`,
Summing the first two equations gives :math:`w_M + w_P + w_L + w_H \lt 2`, and summing the last four gives :math:`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 :math:`\mathcal{F}^2` of the previous model example can be expressed using the following weights:
Expand Down Expand Up @@ -513,10 +514,9 @@ It's not always practical to use real-world data when developing a new learning
In that approach, one specifies the problem and provides a pre-known model.
They then generate pseudo-random alternatives classified according to that original model,
and use them as a training set to learn a new model.
Finally, they compare how close the learned model behaves to the original one to evaluate the quality of the algorithm.
Finally, they compare how close the learned model behaves to the original one to evaluate the quality of the learning algorithm.

*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.


Next
Expand Down
2 changes: 1 addition & 1 deletion doc-sources/reference.rst
Original file line number Diff line number Diff line change
Expand Up @@ -8,8 +8,8 @@ File formats
============

*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.

.. _ref-file-problem:
Expand Down
6 changes: 6 additions & 0 deletions doc-sources/user-guide.rst
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,8 @@ Formatting data for *lincs*
"Problem" files
---------------

.. highlight:: yaml

The concept of classification problem is defined in our :ref:`conceptual overview <overview-about-classification>`.
To describe problems, *lincs* uses YAML files conforming to the `JSON schema <https://json-schema.org/>`_ you'll find in our :ref:`reference documentation <ref-file-problem>`.

Expand Down Expand Up @@ -222,6 +224,8 @@ It's a CSV file with a header line and one line per alternative.

Like model files, alternatives files are always associated to a problem file.

.. highlight:: text

.. START file-formats/expected-classified-alternatives.csv
Here is an example corresponding to the problem above::
Expand Down Expand Up @@ -284,6 +288,8 @@ When you need reproducibility, you can specify the seed to use with the ``--rand

In all cases, the :ref:`comments <user-comments-in-generated-files>` left by *lincs* in the generated files specify the seed that was used.

.. highlight:: shell

Generating a problem
--------------------

Expand Down
Binary file modified docs/.doctrees/conceptual-overview.doctree
Binary file not shown.
Binary file modified docs/.doctrees/environment.pickle
Binary file not shown.
Binary file modified docs/.doctrees/index.doctree
Binary file not shown.
Binary file modified docs/.doctrees/reference.doctree
Binary file not shown.
Binary file modified docs/.doctrees/user-guide.doctree
Binary file not shown.
12 changes: 6 additions & 6 deletions docs/_sources/conceptual-overview.rst.txt
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,8 @@ Notation

In this document, we denote the interval of integers from :math:`a` to :math:`b - 1` included by :math:`[a..b)`.
Most often, :math:`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, :math:`[0..4) = \{0, 1, 2, 3\}`.
Note that :math:`[0..n)` contains :math:`n` elements.

Expand Down Expand Up @@ -110,13 +111,13 @@ Additionally, this set of coalitions can be different for each category.
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 \})
Note that this definition extends naturally if we denote :math:`\mathcal{F}^0 = [0..n)` and :math:`b^0 = (\min(X_0), ..., \min(X_{n-1}))`.
Note that this definition extends naturally if we denote :math:`\mathcal{F}^0 = \mathcal{P}([0..n))` and :math:`b^0 = (\min(X_0), ..., \min(X_{n-1}))`.
The definition of :math:`f` then simplifies to :math:`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
Expand Down Expand Up @@ -453,7 +454,7 @@ This gives us :math:`|\mathcal{P}(\{M, P, L, H\})| = 16` equations, amongst whic
- :math:`w_M + w_H \ge 1` (because :math:`\{M, H\} \in \mathcal{F}^1`)
- :math:`w_P + w_H \ge 1` (because :math:`\{P, H\} \in \mathcal{F}^1`)

Summing the first two equations gives :math:`w_M + w_P + w_L + w_H \lt 2`, and summing teh last four gives :math:`w_M + w_P + w_L + w_H \ge 2`,
Summing the first two equations gives :math:`w_M + w_P + w_L + w_H \lt 2`, and summing the last four gives :math:`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 :math:`\mathcal{F}^2` of the previous model example can be expressed using the following weights:
Expand Down Expand Up @@ -513,10 +514,9 @@ It's not always practical to use real-world data when developing a new learning
In that approach, one specifies the problem and provides a pre-known model.
They then generate pseudo-random alternatives classified according to that original model,
and use them as a training set to learn a new model.
Finally, they compare how close the learned model behaves to the original one to evaluate the quality of the algorithm.
Finally, they compare how close the learned model behaves to the original one to evaluate the quality of the learning algorithm.

*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.


Next
Expand Down
2 changes: 1 addition & 1 deletion docs/_sources/reference.rst.txt
Original file line number Diff line number Diff line change
Expand Up @@ -8,8 +8,8 @@ File formats
============

*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.

.. _ref-file-problem:
Expand Down
6 changes: 6 additions & 0 deletions docs/_sources/user-guide.rst.txt
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,8 @@ Formatting data for *lincs*
"Problem" files
---------------

.. highlight:: yaml

The concept of classification problem is defined in our :ref:`conceptual overview <overview-about-classification>`.
To describe problems, *lincs* uses YAML files conforming to the `JSON schema <https://json-schema.org/>`_ you'll find in our :ref:`reference documentation <ref-file-problem>`.

Expand Down Expand Up @@ -222,6 +224,8 @@ It's a CSV file with a header line and one line per alternative.

Like model files, alternatives files are always associated to a problem file.

.. highlight:: text

.. START file-formats/expected-classified-alternatives.csv
Here is an example corresponding to the problem above::
Expand Down Expand Up @@ -284,6 +288,8 @@ When you need reproducibility, you can specify the seed to use with the ``--rand

In all cases, the :ref:`comments <user-comments-in-generated-files>` left by *lincs* in the generated files specify the seed that was used.

.. highlight:: shell

Generating a problem
--------------------

Expand Down
14 changes: 7 additions & 7 deletions docs/conceptual-overview.html
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,8 @@ <h1>Conceptual overview<a class="headerlink" href="#conceptual-overview" title="
<h2>Notation<a class="headerlink" href="#notation" title="Permalink to this heading"></a></h2>
<p>In this document, we denote the interval of integers from <span class="math notranslate nohighlight">\(a\)</span> to <span class="math notranslate nohighlight">\(b - 1\)</span> included by <span class="math notranslate nohighlight">\([a..b)\)</span>.
Most often, <span class="math notranslate nohighlight">\(a\)</span> 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, <span class="math notranslate nohighlight">\([0..4) = \{0, 1, 2, 3\}\)</span>.
Note that <span class="math notranslate nohighlight">\([0..n)\)</span> contains <span class="math notranslate nohighlight">\(n\)</span> elements.</p>
<p>For a given set <span class="math notranslate nohighlight">\(S\)</span>, we denote the set of all its subsets (<em>a.k.a.</em> its power set) by <span class="math notranslate nohighlight">\(\mathcal{P}(S)\)</span>.
Expand Down Expand Up @@ -122,11 +123,11 @@ <h2>Learning and classifying<a class="headerlink" href="#learning-and-classifyin
<div class="math notranslate nohighlight">
\[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 \})\]</div>
</div>
<p>Note that this definition extends naturally if we denote <span class="math notranslate nohighlight">\(\mathcal{F}^0 = [0..n)\)</span> and <span class="math notranslate nohighlight">\(b^0 = (\min(X_0), ..., \min(X_{n-1}))\)</span>.
<p>Note that this definition extends naturally if we denote <span class="math notranslate nohighlight">\(\mathcal{F}^0 = \mathcal{P}([0..n))\)</span> and <span class="math notranslate nohighlight">\(b^0 = (\min(X_0), ..., \min(X_{n-1}))\)</span>.
The definition of <span class="math notranslate nohighlight">\(f\)</span> then simplifies to <span class="math notranslate nohighlight">\(x \mapsto \max \{ h \in [0..p): \{ i \in [0..n): x_i \succcurlyeq_i b^h_i \} \in \mathcal{F}^h \}\)</span>.</p>
<p>This definition may differ slightly from the one you’re used to, but it should be formally equivalent.
We use it in <em>lincs</em> because it is somewhat simple and matches the implementation quite well.</p>
<p>The constraints in the definition all ensure NDS models behave according to intuition:</p>
<p>The constraints in the definition all ensure NCS models behave according to intuition:</p>
<ul class="simple">
<li><p>the ordering of profiles ensures consistency with the order on categories</p></li>
<li><p>the up-closed-ness-by-inclusion(!) of the sufficient coalitions matches the intuition that they are <em>sufficient</em> criteria: if a few criteria are sufficient, then more criteria are still sufficient</p></li>
Expand Down Expand Up @@ -394,7 +395,7 @@ <h3>Example<a class="headerlink" href="#id1" title="Permalink to this heading">
<li><p><span class="math notranslate nohighlight">\(w_M + w_H \ge 1\)</span> (because <span class="math notranslate nohighlight">\(\{M, H\} \in \mathcal{F}^1\)</span>)</p></li>
<li><p><span class="math notranslate nohighlight">\(w_P + w_H \ge 1\)</span> (because <span class="math notranslate nohighlight">\(\{P, H\} \in \mathcal{F}^1\)</span>)</p></li>
</ul>
<p>Summing the first two equations gives <span class="math notranslate nohighlight">\(w_M + w_P + w_L + w_H \lt 2\)</span>, and summing teh last four gives <span class="math notranslate nohighlight">\(w_M + w_P + w_L + w_H \ge 2\)</span>,
<p>Summing the first two equations gives <span class="math notranslate nohighlight">\(w_M + w_P + w_L + w_H \lt 2\)</span>, and summing the last four gives <span class="math notranslate nohighlight">\(w_M + w_P + w_L + w_H \ge 2\)</span>,
so there is no solution, and that model is not MR-Sort.</p>
<p>By contrast, the coalitions <span class="math notranslate nohighlight">\(\mathcal{F}^2\)</span> of the previous model example can be expressed using the following weights:
<span class="math notranslate nohighlight">\(w_M = 0.4\)</span>, <span class="math notranslate nohighlight">\(w_P = 0.4\)</span>, <span class="math notranslate nohighlight">\(w_L = 0.4\)</span>, <span class="math notranslate nohighlight">\(w_H = 0.4\)</span>: coalitions of at most two criteria have weights sums less than 1,
Expand Down Expand Up @@ -460,9 +461,8 @@ <h2>Classification accuracy<a class="headerlink" href="#classification-accuracy"
In that approach, one specifies the problem and provides a pre-known model.
They then generate pseudo-random alternatives classified according to that original model,
and use them as a training set to learn a new model.
Finally, they compare how close the learned model behaves to the original one to evaluate the quality of the algorithm.</p>
<p><em>lincs</em> 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.</p>
Finally, they compare how close the learned model behaves to the original one to evaluate the quality of the learning algorithm.</p>
<p><em>lincs</em> provides ways to generate synthetic pseudo-random problems, models and training sets (noisy or clean).</p>
</section>
<section id="next">
<h2>Next<a class="headerlink" href="#next" title="Permalink to this heading"></a></h2>
Expand Down
11 changes: 7 additions & 4 deletions docs/index.html
Original file line number Diff line number Diff line change
Expand Up @@ -36,9 +36,12 @@
<section id="readme">
<h1>README<a class="headerlink" href="#readme" title="Permalink to this heading"></a></h1>
<p><em>lincs</em> (Learn and Infer Non Compensatory Sortings) is a collection of <a class="reference external" href="https://en.wikipedia.org/wiki/Multiple-criteria_decision_analysis">MCDA</a> algorithms, usable as a command-line utility.</p>
<p>&#64;todo(Feature, later) Make it usable as a Python package.</p>
<p>&#64;todo(Feature, later) Make it usable as a C++ library.</p>
<p><em>lincs</em> supports Linux, macOS and Windows, with the exception that GPU-based algorithms are not available on macOS, because CUDA itself is not available there.</p>
<p>&#64;todo(Feature, later) Make <em>lincs</em> usable as a Python package.</p>
<p>&#64;todo(Feature, later) Make <em>lincs</em> usable as a C++ library.</p>
<p><em>lincs</em> 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, <em>lincs</em> only support x86_64 CPUs.</p>
<p>&#64;todo(Feature, later) Support M1 and M2 chips on macOS.</p>
<p>&#64;todo(Feature, much later) Support ARM processors in general.</p>
<p><em>lincs</em> is licensed under the GNU Lesser General Public License v3.0 as indicated by the two files <a class="reference external" href="COPYING">COPYING</a> and <a class="reference external" href="COPYING.LESSER">COPYING.LESSER</a>.</p>
<p>&#64;todo(Project management, when we publish a paper, later) Add a note asking academics to kindly cite our work.</p>
<p><em>lincs</em> is available for install from the <a class="reference external" href="https://pypi.org/project/lincs/">Python package index</a>.
Expand All @@ -65,7 +68,7 @@ <h3>Provide MCDA tools usable out of the box<a class="headerlink" href="#provide
</section>
<section id="provide-a-base-for-developing-new-mcda-algorithms">
<h3>Provide a base for developing new MCDA algorithms<a class="headerlink" href="#provide-a-base-for-developing-new-mcda-algorithms" title="Permalink to this heading"></a></h3>
<p><em>lincs</em> is designed to be easy to extend with new algorithms of even replace parts of existing algorithms.
<p><em>lincs</em> is designed to be easy to extend with new algorithms or even replace parts of existing algorithms.
See our <a class="reference internal" href="contributor-guide.html"><span class="doc">contributor guide</span></a> for more details.</p>
</section>
</section>
Expand Down
2 changes: 1 addition & 1 deletion docs/reference.html
Original file line number Diff line number Diff line change
Expand Up @@ -37,8 +37,8 @@ <h1>Reference<a class="headerlink" href="#reference" title="Permalink to this he
<section id="file-formats">
<h2>File formats<a class="headerlink" href="#file-formats" title="Permalink to this heading"></a></h2>
<p><em>lincs</em> uses text-based (YAML and CSV) file formats.
The same formats are used when <em>lincs</em> 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 <em>lincs</em> reads files or when it outputs to files.
The same formats are used when <em>lincs</em> outputs to actual files or to the standard output.</p>
<section id="the-problem-file">
<span id="ref-file-problem"></span><h3>The problem file<a class="headerlink" href="#the-problem-file" title="Permalink to this heading"></a></h3>
Expand Down
2 changes: 1 addition & 1 deletion docs/searchindex.js

Large diffs are not rendered by default.

Loading

0 comments on commit 3ba502a

Please sign in to comment.