Configuration

Tip

See also the API docs in mio.models.config

Config in mio uses a combination of pydantic models and pydantic-settings.

Configuration takes a few forms:

  • Global config: control over basic operation of mio like logging, location of user directories, plugins, etc.

  • Device config: control over the operation of specific devices and miniscopes like firmware versions, ports, capture parameters, etc.

  • Runtime/experiment config: control over how a device behaves when it runs, like plotting, data output, etc.

Global Config

Global config uses the Config class

Config values can be set (in order of priority from high to low, where higher priorities override lower priorities)

  • in the arguments passed to the class constructor (not user configurable)

  • in environment variables like export MIO_LOG_DIR=~/

  • in a .env file in the working directory

  • in a mio_config.yaml file in the working directory

  • in the tool.mio.config table in a pyproject.toml file in the working directory

  • in a user mio_config.yaml file in the user directory (see below)

  • in the global mio_config.yaml file in the platform-specific data directory (use mio config global path to find its location)

  • the default values in the Config model

Parent directories are not checked - .env files, mio_config.yaml, and pyproject.toml files need to be in the current working directory to be discovered.

You can see your current configuration with mio config

User Directory

The configuration system allows project-specific configs per-directory with mio_config.yaml files in the working directory, as well as global configuration via mio_config.yaml in the system-specific config directory (via platformdirs). By default, mio does not create new directories in the user’s home directory to be polite, but the site config directory might be inconvenient or hard to reach, so it’s possible to create a user directory in a custom location.

mio discovers this directory from the user_dir setting from any of the available sources, though the global mio_config.yaml file is the most reliable.

To create a user directory, use the mio config user create command. (ignore the --dry-run flag, which are just used to avoid overwriting configs while rendering the docs ;)

$ mio config user create ~/my_new_directory --dry-run
DRY RUN - No files changed
-----
Would have created user config at /home/docs/my_new_directory/mio_config.yaml:
-----
user_dir: /home/docs/my_new_directory
config_dir: /home/docs/my_new_directory/config
log_dir: /home/docs/my_new_directory/logs
logs:
  level: INFO
  level_file: null
  level_stdout: null
  file_n: 5
  file_size: 4194304

You can confirm that this will be where mio discovers the user directory like

$ mio config user path
/home/docs/.config/mio/mio_config.yaml

If a directory is not supplied, the default ~/.config/mio is used:

$ mio config user create --dry-run
DRY RUN - No files changed
-----
Would have created user config at /home/docs/.config/mio/mio_config.yaml:
-----
user_dir: /home/docs/.config/mio
config_dir: /home/docs/.config/mio/config
log_dir: /home/docs/.config/mio/logs
logs:
  level: INFO
  level_file: null
  level_stdout: null
  file_n: 5
  file_size: 4194304

Setting Values

Todo

Implement setting values from CLI.

For now, please edit the configuration files directly.

Keys

Prefix

Keys for environment variables (i.e. set in a shell with e.g. export or in a .env file) are prefixed with MIO_ to not shadow other environment variables. Keys in toml or yaml files are not prefixed with MIO_ .

Nesting

Keys for nested models are separated by a __ double underscore in .env files or environment variables (eg. MIO_LOGS__LEVEL)

Keys in toml or yaml files do not have a dunder separator because they can represent the nesting directly (see examples below)

When setting values from the cli, keys for nested models are separated with a ..

Case

Keys are case-insensitive, i.e. these are equivalent::

export MIO_LOGS__LEVEL=INFO
export mio_logs__level=INFO

Examples

user_dir: ~/.config/mio
log_dir: ~/.config/mio/logs
logs:
  level_file: INFO
  level_stream: WARNING
  file_n: 5

export MIO_USER_DIR='~/.config/mio'
export MIO_LOG_DIR='~/config/mio/logs'
export MIO_LOGS__LEVEL_FILE='INFO'
export MIO_LOGS__LEVEL_STREAM='WARNING'
export MIO_LOGS__FILE_N=5

MIO_USER_DIR='~/.config/mio'
MIO_LOG_DIR='~/config/mio/logs'
MIO_LOG__LEVEL_FILE='INFO'
MIO_LOG__LEVEL_STREAM='WARNING'
MIO_LOG__FILE_N=5

[tool.mio.config]
user_dir = "~/.config/mio"

[tool.linkml.config.log]
dir = "~/config/mio/logs"
level_file = "INFO"
level_stream = "WARNING"
file_n = 5

TODO

Device Configs

Todo

Document device configuration