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

The console script ``hetero`` is bound to :func:`hetero.cli.main`. The parser is
built by :func:`hetero.cli.get_parser`, whose flags are grouped into the
sections listed below; :func:`hetero.cli.create_param_dicts` turns the parsed
namespace into the nested parameter dictionary that
:class:`hetero.sim.Simulation` consumes. Every default comes from
:data:`hetero.config.CFG`, so the parser stays in sync with the config
automatically.

Input and output
----------------

``--root``
    Result directory. Default: :data:`hetero.config.res_root`.
``--stype``
    Storage dtype of the simulated states (``float64`` for accurate
    forecasting, ``float16`` otherwise). Default: ``float16``.
``--ncore``
    Number of worker processes; ``-1`` uses all cores. Default: ``-1``.
``--seed``
    Random number seed. Default: ``1234``.

Stage skips
-----------

Each of these skips one stage of the run, so a finished run can be extended or
inspected piecemeal.

``--noint``
    Skip integration and reuse the states on disk.
``--nobm``
    Skip benchmarking and reuse the scores on disk.
``--nosvd``
    Skip the SVD computation, i.e. skip the ``svals``/``erank``/``angle`` csv
    files. This is a *computation* flag, not a plot flag: ``--noviz`` still
    writes the numbers to disk.

``--noviz``
    Skip every figure of the run. Implies ``--noconn``, ``--notau``,
    ``--nouvx``, ``--noscore``, ``--noangle`` and ``--nosumplot`` (see
    :data:`hetero.cli.PLOT_SKIP_FLAGS`). The csv files are still computed.
    Use it while sweeping parameters.
``--replot``
    Re-render every figure of a finished run, loading whatever is already on
    disk and computing only what is missing. Overrides ``--noviz`` and the
    individual ``--no*`` plot flags, and also recomputes missing
    integration/benchmark results even under ``--noint``/``--nobm``.

The individual plot flags are ``--noconn`` (connectivity), ``--notau``
(time-constant distribution), ``--nouvx`` (input/voltage/activation traces),
``--noscore`` (readout score map), ``--noangle`` (angle-vs-score) and
``--nosumplot`` (angle CDF, singular values, effective rank). The summary
figures aggregate every state on disk, so in a sweep they are re-rendered from
all previously computed cases after every single run.

Heterogeneity
-------------

``--distro``
    Distribution of the neuronal time constants, e.g. ``lognormal``, ``gamma``,
    ``normal``, ``uniform``. Any ``numpy.random``-compatible distribution.
    Default: ``lognormal``.
``--n_means``
    Number of mean-timescale levels. Default: ``3``.
``--n_vars``
    Number of heterogeneity levels per mean level. Default: ``3``.
``--log_distance``
    Log-10 distance between two consecutive mean levels. Default: ``0.5``.

Network
-------

``--N``
    Number of neurons. Default: ``250``.
``--p``
    Connection probability (sparsity). Default: ``0.1``.
``--f``
    Fraction of excitatory neurons. Default: ``0.8``.
``--mue``
    Mean excitatory synaptic weight. Default: ``1.0``.
``--sig0``
    Standard deviation of the excitatory and inhibitory weights. Default: ``1.0``.
``--autapse``
    Whether self-connections are allowed. Default: ``False``.
``--delay``
    Synaptic delay in units of ``dt``. Default: ``0``.

Gains
-----

``--Jn``
    Gain of the white noise. Default: ``0.1``.
``--J``
    Gain of the recurrent weights. Default: ``1.0``.
``--Ju``
    Gain of the feedforward weights. Default: ``1.0``.

Stimulation
-----------

``--stim``
    One or more stimulus labels; the timeseries are concatenated. See the
    ``stim`` block of :data:`hetero.config.CFG` for the available labels
    (``lorenz``, ``mackey_glass-10``, ``mackey_glass-50``, ``mackey_glass-80``,
    ``sin``, ``sin-5``, ``sinabs``, ``sign``, ``sign-5``, ``narma``,
    ``constant``) and their parameters.

Task
----

``--task``
    ``taylor``, ``nostradamus`` or ``tayloramus``. Default: ``tayloramus``.

Dataset
-------

``--n_trn``
    Length of the training set, in units of the input base timescale. Default: ``20``.
``--n_tst``
    Length of the test set, in the same units. Default: ``10``.
``--disable_scale_by_size``
    Turn off the automatic scaling of the training-set size with the network
    size. By default enlarging the network by a factor of ``x`` enlarges the
    training set by the same factor; the test set is unaffected.

Dynamics
--------

``--dyn``
    ``LI`` (leaky integrator, rate) or ``LIF`` (leaky integrate-and-fire,
    ``brian2``). Default: ``LI``.
``--solver``
    Solver used by the rate dynamics. Default: ``euler``.

Readout
-------

``--readout_activation``
    How the neuronal state is turned into a readout signal. Rate networks take
    an activation function (``possig1``, ``tanh1``), spiking networks take a
    temporal kernel (``array``, ``g50``, ``gnc50``, ``d50``, ``d10``, ``a50``,
    ``ma50``). An incompatible choice is corrected with a warning; see
    :data:`hetero.config.VALID_ACTIVATIONS`. Default: ``possig1``.

Optimization
------------

``--alg``
    Any ``scikit-learn``-compatible regressor, e.g. ``ridge``, ``ols``,
    ``lasso``, ``elasticnet``. Default: ``ridge``.
``--reg``
    Regularization strength, where the algorithm uses one. Default: ``1e-6``.
``--fit_bias``
    Whether to fit an intercept. Default: ``True``.

Uncertainty quantification
--------------------------

``--n_trials``
    Number of non-overlapping contiguous intervals over which a readout is
    trained. The spread of the corresponding test scores estimates the
    performance uncertainty. Default: ``3``.
``--n_realizations``
    Number of independent realizations of the topology and the weights. The
    spread of the scores across realizations estimates the network
    uncertainty. Default: ``1``.

API
---

.. automodule:: hetero.cli
   :members:
   :undoc-members:
   :member-order: bysource