RST reporting

Simple example.

Example on how to accumulate runtime information in an RST report. See user guide for details.

Functions

Let’s create some functions to monitor.

from brainprep.decorators import (
    LogRuntimeHook,
    step,
)
from brainprep.utils import Bunch


@step(
    hooks=[LogRuntimeHook()]
)
def workflow(val1, val2=None):
    """
    This is the main workflow.

    Parameters
    ----------
    val1: int
        a value.
    val2: int, default None
        an optional value.

    Returns
    -------
    val: int
        a value.
    """
    if val2 is not None:
        return Bunch(val=val1 * square(val2).val2)
    else:
        return Bunch(val=val1)


@step(
    hooks=[LogRuntimeHook()]
)
def square(val):
    """
    Return the square of the input.

    Parameters
    ----------
    val: int
        a value.

    Returns
    -------
    val2: int
        the value squared.
    """
    return Bunch(val2=val ** 2)

Reporting

Now let’s generate the RST report.

from pathlib import Path

from brainprep.reporting import RSTReport

working_dir = Path("/tmp/brainprep-reporting")
working_dir.mkdir(parents=True, exist_ok=True)

report = RSTReport()
print(workflow(val1=1))
print(report)
report = RSTReport()
print(workflow(val1=1, val2=2))
print(report)
report.save_as_rst(working_dir / "report.rst")

Bunch(
  val: 1
)
Bunch(
  step1: Bunch(
    module: '__main__.workflow'
    description: '\n    This is the main workflow.\n\n    Parameters\n    ----------\n    val1: int\n        a value.\n    val2: int, default None\n        an optional value.\n\n    Returns\n    -------\n    val: int\n        a value.\n    '
    inputs: Bunch(
      val1: 1
      val2: None
    )
    outputs: Bunch(
      val: 1
    )
    runtime: Bunch(
      start: '2026-04-01 12:42:16.530388'
      end: '2026-04-01 12:42:16.530404'
      execution_time: 4.444444444444444e-09
      brainprep_version: '2.0.0'
      platform: 'Linux-6.17.0-1008-azure-x86_64-with-glibc2.39'
      hostname: 'runnervmrg6be'
    )
    config: Bunch(
      verbose: True
      dryrun: False
      no_color: False
      skip_run_check: False
      cat12_file: PosixPath('/opt/cat12/standalone/cat_standalone.sh')
      spm12_dir: PosixPath('/opt/cat12')
      matlab_dir: PosixPath('/opt/MCR-2017b/v93')
      tpm_file: PosixPath('/opt/cat12/spm12_mcr/home/gaser/gaser/spm/spm12/tpm/TPM.nii')
      darteltpm_file: PosixPath('/opt/cat12/spm12_mcr/home/gaser/gaser/spm/spm12/toolbox/cat12/templates_MNI152NLin2009cAsym/Template_1_Dartel.nii')
    )
  )
)
Bunch(
  val: 4
)
Bunch(
  step1: Bunch(
    module: '__main__.workflow'
    description: '\n    This is the main workflow.\n\n    Parameters\n    ----------\n    val1: int\n        a value.\n    val2: int, default None\n        an optional value.\n\n    Returns\n    -------\n    val: int\n        a value.\n    '
    inputs: Bunch(
      val1: 1
      val2: 2
    )
    outputs: Bunch(
      val: 4
    )
    runtime: Bunch(
      start: '2026-04-01 12:42:16.538022'
      end: '2026-04-01 12:42:16.541775'
      execution_time: 1.0425e-06
      brainprep_version: '2.0.0'
      platform: 'Linux-6.17.0-1008-azure-x86_64-with-glibc2.39'
      hostname: 'runnervmrg6be'
    )
    config: Bunch(
      verbose: True
      dryrun: False
      no_color: False
      skip_run_check: False
      cat12_file: PosixPath('/opt/cat12/standalone/cat_standalone.sh')
      spm12_dir: PosixPath('/opt/cat12')
      matlab_dir: PosixPath('/opt/MCR-2017b/v93')
      tpm_file: PosixPath('/opt/cat12/spm12_mcr/home/gaser/gaser/spm/spm12/tpm/TPM.nii')
      darteltpm_file: PosixPath('/opt/cat12/spm12_mcr/home/gaser/gaser/spm/spm12/toolbox/cat12/templates_MNI152NLin2009cAsym/Template_1_Dartel.nii')
    )
  )
  step2: Bunch(
    module: '__main__.square'
    description: '\n    Return the square of the input.\n\n    Parameters\n    ----------\n    val: int\n        a value.\n\n    Returns\n    -------\n    val2: int\n        the value squared.\n    '
    inputs: Bunch(
      val: 2
    )
    outputs: Bunch(
      val2: 4
    )
    runtime: Bunch(
      start: '2026-04-01 12:42:16.541732'
      end: '2026-04-01 12:42:16.541740'
      execution_time: 2.222222222222222e-09
      brainprep_version: '2.0.0'
      platform: 'Linux-6.17.0-1008-azure-x86_64-with-glibc2.39'
      hostname: 'runnervmrg6be'
    )
    config: Bunch(
      verbose: True
      dryrun: False
      no_color: False
      skip_run_check: False
      cat12_file: PosixPath('/opt/cat12/standalone/cat_standalone.sh')
      spm12_dir: PosixPath('/opt/cat12')
      matlab_dir: PosixPath('/opt/MCR-2017b/v93')
      tpm_file: PosixPath('/opt/cat12/spm12_mcr/home/gaser/gaser/spm/spm12/tpm/TPM.nii')
      darteltpm_file: PosixPath('/opt/cat12/spm12_mcr/home/gaser/gaser/spm/spm12/toolbox/cat12/templates_MNI152NLin2009cAsym/Template_1_Dartel.nii')
    )
  )
)

Estimated memory usage: 115 MB