.. Copyright 2023-2024 Vincent Jacques

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

.. _ref-file-problem:

The problem file
----------------

The problem file is a YAML file specified by the following :download:`JSON Schema <problem-schema.yml>`:

.. jsonschema:: problem-schema.yml
   :lift_title: false

.. _ref-file-ncs-model:

The NCS model file
------------------

The model file is a YAML file specified by the following :download:`JSON Schema <model-schema.yml>`:

.. jsonschema:: model-schema.yml
   :lift_title: false

.. _ref-file-alternatives:

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.

.. _ref-cli:

Command-line interface
======================

.. @todo(Documentation, later) Ensure that ranges appear in the doc like they do in the CLI's --help
.. Example: 0.0<=x<=1.0 for --mrsort.weights-profiles-breed.target-accuracy

.. click:: lincs.command_line_interface:main
   :prog: lincs
   :nested: full

.. _ref-python-api:

Python API
==========

.. I did not manage to get sufficient control over the doc generated by autodoc, so I resorted to writing an ad-hoc generator.

.. include:: reference/lincs.rst