Reports
========

MEGPrep provides two report interfaces:

* A portable static HTML report generated by the Nextflow workflow.
* An interactive Streamlit report viewer started with ``-r`` or
  ``--view_report``.

Static HTML Report
------------------

Every MEGPrep run that reaches a MEG milestone writes a static report under:

.. code-block:: text

   <output_dir>/static_html_report/

Open the report entry point:

.. code-block:: text

   <output_dir>/static_html_report/index.html

The static report can also be regenerated without rerunning the pipeline:

.. code-block:: bash

   docker run --rm -it \
     -v /data/bids:/input \
     -v /data/out:/output \
     -v /data/smri:/smri \
     cmrlab/megprep:0.0.3 \
     -i /input -o /output --fs_subjects_dir /smri --steps report

The report directory is self-contained and includes copied figures, sidecar
files, JSON summaries, CSV summaries, and a config snapshot when available.
Subject pages also include a collapsed ``Task Details`` table derived from the
Nextflow trace file when one is available. If a task failed or was ignored, the
page adds ``Task Failure Details`` with the error summary and packaged command
log excerpts.

.. list-table::
   :header-rows: 1
   :widths: 32 68

   * - Path
     - Description
   * - ``index.html``
     - Dataset-level dashboard with workflow diagram, aggregate metrics,
       subject table, alarm counts, and links to subject pages.
   * - ``subjects/<recording>.html``
     - Recording-level details for artifacts, ICA, coregistration, epochs,
       covariance, head model, source reconstruction, and packaged files.
   * - ``alarms.html``
     - Searchable alarm list across all recordings.
   * - ``data/dataset_summary.json``
     - Machine-readable dataset summary.
   * - ``data/subjects.csv``
     - Spreadsheet-friendly subject summary table.
   * - ``data/subjects/<recording>.json``
     - Machine-readable per-recording summary.
   * - ``data/nextflow.config.txt``
     - Effective Nextflow config snapshot when MEGPrep can locate one.
   * - ``data/megprep_run_manifest.json``
     - Workflow mode and run metadata used to render the workflow diagram.
   * - ``files/<recording>/errors/*.txt``
     - Packaged ``.command.err``, ``.command.log``, and ``.command.out``
       excerpts for failed or ignored tasks, when available.
   * - ``files/<recording>/tasks/*.txt``
     - Optional ``.command.log`` excerpts for successful tasks when
       ``static_task_log_mode = 'all-command-log'``.

Task Log Bundling
-----------------

By default, MEGPrep copies successful-task ``.command.log`` excerpts as well
as failed-task command logs so the portable report contains fuller task
provenance. Configure this with ``static_task_log_mode`` in the Nextflow
config, or pass ``--static_task_log_mode`` through the Docker entrypoint or
Nextflow command.

.. list-table::
   :header-rows: 1
   :widths: 28 72

   * - Value
     - Behavior
   * - ``all-command-log``
     - Default. Copy ``.command.err``, ``.command.log``, and
       ``.command.out`` excerpts for failed or ignored tasks, and also copy
       ``.command.log`` for successful tasks.
   * - ``failed``
     - Copy command logs only for failed or ignored tasks when a smaller report
       package is preferred.
   * - ``none``
     - Do not copy ``.command*`` logs. The report still shows trace-derived
       task status, exit code, duration, memory, and hash values.

Example:

.. code-block:: bash

   docker run ... cmrlab/megprep:<version> \
     -i /input -o /output \
     --static_task_log_mode all-command-log

How to Interpret the Static Report
----------------------------------

Start from ``index.html``:

1. Review the workflow diagram to verify that the selected ``steps`` mode
   matches the intended run.
2. Sort the subject table by alarms, bad channels, bad segments, coregistration
   distance, or epoch rejection rate.
3. Open subject pages for recordings marked ``WARN`` or ``FAIL``.
4. For artifact alarms, inspect the bad-channel list, bad-segment table, and
   artifact mask heatmap. The heatmap summarizes where bad channels and bad
   time segments occur across the recording before opening the more detailed
   waveform images.
5. For ICA alarms, inspect marked components, ECG/EOG candidates, component
   topographies, and ICA overlay/PSD plots.
6. For coregistration alarms, inspect the staged coregistration figures and
   confirm that the recording was matched to the correct MRI subject.
7. If a subject is marked ``FAIL`` because a Nextflow task failed or was
   ignored, open ``Task Failure Details`` first, then expand ``Task Details``
   for the full trace context.

The current report uses static thresholds and measured values. It does not yet
include calibrated normative QC scores. See :doc:`../reference/qc_metrics` for
the complete metric list.

Interactive Streamlit Report
----------------------------

To view quality control reports through the interactive Streamlit interface,
run MEGPrep with Docker and expose port ``8501``:

.. code-block:: bash

   docker run --rm -it -p 8501:8501 \
     -v /data/megprep_output:/output \
     cmrlab/megprep:<version> \
     -r

The Docker entrypoint handles mounted output permissions automatically. It
starts as root, prepares ``/output`` when needed, then drops to the host UID/GID
inferred from ``/input``. For report-only runs that only mount ``/output``, the
UID/GID are inferred from ``/output`` instead, so an existing report directory
owned by the submitting user stays writable. If neither mount has the desired
owner, pass ``-e LOCAL_UID="$(id -u)" -e LOCAL_GID="$(id -g)"``.

Then open:

.. code-block:: text

   http://<server_ip>:8501

Use ``http://localhost:8501`` when running locally. The Streamlit report is a
viewer and does not run Nextflow preprocessing.