Configuration basics¶

BrkRaw uses a user-level configuration directory to control output naming, layout behavior, logging, and installed extensions.

Most users only need to adjust a small subset of configuration options to be productive. This page focuses on those commonly used settings.

Config location¶

By default, BrkRaw stores configuration under:

~/.brkraw

You can override this location by setting:

BRKRAW_CONFIG_HOME=/path/to/config

The main configuration file is config.yaml.

It is created automatically by:

brkraw init

What you may want to customize first¶

1. Output naming and layout¶

BrkRaw does not hard-code output filenames. Instead, filenames are generated from metadata using configurable layout rules.

The most commonly adjusted settings live under:

output.layout_entries
output.layout_template

Typical reasons to edit layout settings:

Match an existing lab naming convention
Include or hide protocol names
Separate outputs by subject or session
Shorten long protocol strings

Most users start with layout_entries and leave layout_template unset.

2. Logging verbosity¶

To see more details about what BrkRaw is doing, increase the logging level:

logging.level: DEBUG

This is useful when debugging rules, specs, or hooks.

3. Table formatting¶

If CLI tables wrap badly on your terminal, adjust:

logging.print_width

This affects commands such as brkraw info and brkraw hook list.

4. Floating-point formatting¶

BrkRaw rounds floating-point values when displaying metadata and derived outputs.

You can control this via:

output.float_decimals

This is mainly a display preference.

Multi-slicepack outputs¶

Some scans produce multiple slice packs. In this case, BrkRaw appends a suffix to distinguish outputs.

The default behavior can be customized via:

output.slicepack_suffix

Most users should keep the default. If you need richer, study-specific naming, prefer managing mapped metadata via rules/specs (and then using layout settings) rather than encoding semantics into the slice-pack suffix.

Common layout patterns¶

Below are three example layout patterns that reflect common research workflows.

These examples are starting points, not fixed standards.

Minimal layout¶

A simple, compact naming scheme suitable for quick experiments or temporary outputs.

output:
  layout_entries:
    - key: Subject.ID
      entry: sub
    - key: ScanID
      entry: scan

Produces filenames such as:

sub-01_scan-3.nii.gz

Lab-style layout¶

A more descriptive layout that includes session and protocol information, commonly used in lab-managed datasets.

output:
  layout_entries:
    - key: Subject.ID
      entry: sub
      sep: "/"
    - key: Session.ID
      entry: ses
      sep: "/"
    - key: ScanID
      entry: scan
    - key: Protocol
      hide: true

Produces paths such as:

sub-01/ses-1/scan-3_T2w.nii.gz

For BIDS-style naming guidance (including example layouts and a roadmap for brkraw-bids), see BIDS integration.

Installed extensions and files¶

The configuration directory also contains subdirectories for extensions:

rules/
specs/
pruner_specs/
transforms/

These are populated automatically when you install addons or hooks. Most users should not edit these files manually.

Stability and future changes¶

The configuration schema may evolve over time.

config_version is managed internally and should not be edited.
New configuration keys may be added in future releases.
Existing keys may gain new optional fields.

For authoritative details, refer to the Configuration Reference section of the documentation.

Next steps¶

To explore all available configuration options, see the full Configuration Reference.
To edit configuration interactively, run:

brkraw config edit