.. -*- mode: rst; fill-column: 78 -*-
.. ex: set sts=4 ts=4 sw=4 et tw=79:
  ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ###
  #
  #   See COPYING file distributed along with the PyMVPA package for the
  #   copyright and license terms.
  #
  ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ###


.. index:: misc

*************
Miscellaneous
*************

.. index:: progress tracking, verbosity, debug, warning

Progress Tracking
=================

.. some parts should migrate into developer reference I guess

There are 3 types of messages PyMVPA can produce:

 verbose_
   regular informative messages about generic actions being performed
 debug_
   messages about the progress of computation, manipulation on data
   structures
 warning_
    messages which are reported by mvpa if something goes a little
    unexpected but not critical


.. _verbose: api/mvpa.misc-module.html#verbose
.. _debug: api/mvpa.misc-module.html#debug
.. _warning: api/mvpa.misc-module.html#warning


.. index:: redirecting output

Redirecting Output
------------------

By default, all types of messages are printed by PyMVPA to the standard
output. It is possible to redirect them to standard error, or a file, or a
list of multiple such targets, by using environment variable
``MVPA_?_OUTPUT``, where X is either ``VERBOSE``, ``DEBUG``, or ``WARNING``
correspondingly. E.g.::

  export MVPA_VERBOSE_OUTPUT=stdout,/tmp/1 MVPA_WARNING_OUTPUT=/tmp/3 MVPA_DEBUG_OUTPUT=stderr,/tmp/2

would direct verbose messages to standard output as well as to ``/tmp/1``
file, warnings will be stored only in ``/tmp/3``, and debug output would
appear on standard error output, as well as in the file ``/tmp/2``.

PyMVPA output redirection though has no effect on external libraries debug
output if corresponding debug_ target is enabled

 shogun
   debug output (if any of internal ``SG_`` debug_ targets is enabled)
   appears on standard output

 SMLR
   debug output (if ``SMLR_`` debug_ target is enabled) appears on standard
   output

 libsvm
   debug output (if ``LIBSVM`` debug_ target is enabled) appears on
   standard error

.. index:: verbosity

Verbose Messages
----------------

Primarily for a user of PyMVPA to provide information about the
progress of their scripts. Such messages are printed out if their
level specified as the first parameter to verbose_ function call is
less than specified. There are two easy ways to specify verbosity
level:

* command line: you can use optVerbose_ for precrafted command
  line option for to give facility to change it from your script (see
  examples)
* environment variable ``MVPA_VERBOSE``
* code: verbose.level property

The following verbosity levels are supported:

  :0: nothing besides errors
  :1: high level stuff -- top level operation or file operations
  :2: cmdline handling
  :3: n.a.
  :4: computation/algorithm relevant thing


.. index:: warning

Warning Messages
----------------

Reported by PyMVPA if something goes a little unexpected but not critical. By
default they are printed just once per occasion, i.e. once per piece of code
where it is called. Following environment variables control the
behavior of warnings:

* ``MVPA_WARNINGS_COUNT=<int>`` controls for how many invocations of
  specific warning it gets printed (default behavior is 1 for
  once). Specification of negative count results in all invocations
  being printed, and value of 0 obviously suppresses the warnings
* ``MVPA_NO_WARNINGS`` analogous to ``MVPA_WARNINGS_COUNT=0`` it
  resultant behavior
* ``MVPA_WARNINGS_BT=<int>`` controls up to how many lines of traceback
  is printed for the warnings

In python code, invocation of warning with argument ``bt = True``
enforces printout of traceback whenever warning tracebacks are
disabled by default.


.. index:: debug

Debug Messages
--------------

Debug messages are used to track progress of any computation inside
PyMVPA while the code run by python without optimization (i.e. without
``-O`` switch to python). They are specified not by the level but by
some id usually specific for a particular PyMVPA routine. For example
``RFEC`` id causes debugging information about `Recursive Feature
Elimination call`_ to be printed (See `misc module sources`_ for the
list of all ids, or print ``debug.registered`` property).

Analogous to verbosity level there are two easy ways to specify set of
ids to be enabled (reported):

* command line: you can use optDebug_ for precrafted command line
  option to provide it from your script (see examples). If in command
  line if optDebug_ is used, ``-d list`` is given, PyMVPA will print
  out list of known ids.
* environment: variable ``MVPA_DEBUG`` can contain comma-separated
  list of ids or python regular expressions to match multiple ids. Thus
  specifying ``MVPA_DEBUG=CLF.*`` would enable all ids which start with
  ``CLF``, and ``MVPA_DEBUG=.*`` would enable all known ids.
* code: debug.active property (e.g. ``debug.active = [ 'RFEC', 'CLF' ]``)

Besides printing debug messages, it is also possible to print some
metric. You can define new metrics or select predefined ones (vmem,
asctime, pid). To enable list of metrics you can use
``MVPA_DEBUG_METRICS`` environment variable to list desired metric
names comma-separated.

As it was mentioned earlier, debug messages are printed only in
non-optimized python invocation. That was done to eliminate any
slowdown introduced by such 'debugging' output, which might appear at
some computational bottleneck places in the code.

Some of the debug ids are defined to facilitate additional checking of the
validity of the analysis. E.g. ``RETRAIN`` id would cause additional checking
of the data in retraining phase. Such additional testing might spot out some
bugs in the internal logic.

.. TODO: Unify loggers behind verbose and debug. imho debug should have
   also way to specify the level for the message so we could provide
   more debugging information if desired.

.. _optVerbose: api/mvpa.misc.cmdline-module.html#optVerbose
.. _optDebug: api/mvpa.misc.cmdline-module.html#optDebug
.. _misc module sources: api/mvpa.misc-pysrc.html
.. _Recursive Feature Elimination call: api/mvpa.featsel.rfe.RFE-class.html#__call__


Additional Little Helpers
=========================

.. index:: random number generation, RNG

Random Number Generation
------------------------

To facilitate reproducible troubleshooting, a seed value of random generator
of NumPy can be provided in debug mode (python is called without ``-O``) via
environment variable ``MVPA_SEED=<int>``. Otherwise it gets seeded with random
integer which can be displayed with debug id ``RANDOM`` e.g.::

  > MVPA_SEED=123 MVPA_DEBUG=RANDOM python test_clf.py
  [RANDOM] DBG: Seeding RNG with 123
  ...
  > MVPA_DEBUG=RANDOM python test_clf.py
  [RANDOM] DBG: Seeding RNG with 1447286079
  ...

Others
------
(to be written)

.. put information about IO helpers, external bindings, etc here


.. index:: FSL

FSL Bindings
============

(to be written)

