Running LogML
========================================

LogML is not a simple script: it is a full-scale data analysis framework, so it comes loaded with
the set of python libraries of all kinds, mostly related to data analysis or visualization of its
results. This set of libraries is installed on the local machine in a form of
so called `conda environment` which decouples LogML-specific python executable and all libraries
from all other python installations.

To run LogML directly we have to *activate* its conda environment first.

- `log_ml.sh` - bash script, which activates current environment and launches `log_ml.py`
- `log_ml.py` - primary LogML 'executable' file, where you can run analysis, reporting and utility
  routines.


On a **local machine** we need to activate environment only once

.. code-block:: bash

        # Activate environment by name, or by full path:
        conda activate logml

        # Go to root folder of LogML distribution
        #
        cd /projects/logml

        # Invoke
        python log_ml.py pipeline --help


To describe the procedure we use environment variables, however this is only for illustrative purpose:

.. code-block:: bash

    export LML_OUTPUT=~/logml_output
    export LML_RUN_NAME=wine_modeling_01
    export LML_CFG=~/logml/examples/wine/modeling.yaml
    export LML_DATASET=~/logml/examples/wine/wine.csv


    python log_ml.py pipeline run \
        -o $LML_OUTPUT \
        -c $LML_CFG \
        -d $LML_DATASET \
        -n $LML_RUN_NAME

This starts process of step-by-step pipeline execution which will end in several minutes for
this example, but in reality it may be quite long.

After the job is completed, you should expect the following artifacts within ``$LML_OUTPUT`` folder:

- ``$LML_RUN_NAME`` folder with all the artifacts produced during the run

- ``$LML_OUTPUT/$LML_RUN_NAME/$LML_RUN_NAME.zip`` - the result archive with the most important
  artifacts (report + some supporting artifacts)

.. code-block:: bash

    $ # examine $LML_OUTPUT folder.
    $ cd ~/logml_output && tree -L 2
      .
      └── wine_modeling_01  # $LML_RUN_NAME
          ├── default  # Strata data ("default" when no explicit stratification).
          ├── analysis
          ├── analysis_metadata
          ├── logs
          ├── _logs
          ├── _dag
          ├── report
          ├── release  # final report, folder zipped as $LML_RUN_NAME.zip
          └── wine_modeling_01.zip # $LML_RUN_NAME.zip


Command Line Parameters
-----------------------------

.. click:: src.logml.main:logml_cmd_group
   :prog: log_ml.py
   :nested: full