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
[25-02-03T03:17:02] WARNING  [mio.streamDaq] Could not import   stream_daq.py:40
                             OpalKelly driver, you can't read                   
                             from FPGA!                                         
                             Check out Opal Kelly's website for                 
                             troubleshooting                                    
                             https://docs.opalkelly.com/fpsdk/g                 
                             etting-started/                                    
Traceback (most recent call last):
  File "/home/docs/checkouts/readthedocs.org/user_builds/miniscope-io/envs/82/bin/mio", line 5, in <module>
    from mio.cli.main import cli
  File "/home/docs/checkouts/readthedocs.org/user_builds/miniscope-io/envs/82/lib/python3.12/site-packages/mio/cli/main.py", line 8, in <module>
    from mio.cli.stream import stream
  File "/home/docs/checkouts/readthedocs.org/user_builds/miniscope-io/envs/82/lib/python3.12/site-packages/mio/cli/stream.py", line 12, in <module>
    from mio.stream_daq import StreamDaq
  File "/home/docs/checkouts/readthedocs.org/user_builds/miniscope-io/envs/82/lib/python3.12/site-packages/mio/stream_daq.py", line 60, in <module>
    class StreamDaq:
  File "/home/docs/checkouts/readthedocs.org/user_builds/miniscope-io/envs/82/lib/python3.12/site-packages/mio/stream_daq.py", line 260, in StreamDaq
    def _init_okdev(self, BIT_FILE: Path) -> Union[okDev, okDevMock]:
                                                   ^^^^^
NameError: name 'okDev' is not defined

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

$ mio config user path
[25-02-03T03:17:03] WARNING  [mio.streamDaq] Could not import   stream_daq.py:40
                             OpalKelly driver, you can't read                   
                             from FPGA!                                         
                             Check out Opal Kelly's website for                 
                             troubleshooting                                    
                             https://docs.opalkelly.com/fpsdk/g                 
                             etting-started/                                    
Traceback (most recent call last):
  File "/home/docs/checkouts/readthedocs.org/user_builds/miniscope-io/envs/82/bin/mio", line 5, in <module>
    from mio.cli.main import cli
  File "/home/docs/checkouts/readthedocs.org/user_builds/miniscope-io/envs/82/lib/python3.12/site-packages/mio/cli/main.py", line 8, in <module>
    from mio.cli.stream import stream
  File "/home/docs/checkouts/readthedocs.org/user_builds/miniscope-io/envs/82/lib/python3.12/site-packages/mio/cli/stream.py", line 12, in <module>
    from mio.stream_daq import StreamDaq
  File "/home/docs/checkouts/readthedocs.org/user_builds/miniscope-io/envs/82/lib/python3.12/site-packages/mio/stream_daq.py", line 60, in <module>
    class StreamDaq:
  File "/home/docs/checkouts/readthedocs.org/user_builds/miniscope-io/envs/82/lib/python3.12/site-packages/mio/stream_daq.py", line 260, in StreamDaq
    def _init_okdev(self, BIT_FILE: Path) -> Union[okDev, okDevMock]:
                                                   ^^^^^
NameError: name 'okDev' is not defined

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

$ mio config user create --dry-run
[25-02-03T03:17:03] WARNING  [mio.streamDaq] Could not import   stream_daq.py:40
                             OpalKelly driver, you can't read                   
                             from FPGA!                                         
                             Check out Opal Kelly's website for                 
                             troubleshooting                                    
                             https://docs.opalkelly.com/fpsdk/g                 
                             etting-started/                                    
Traceback (most recent call last):
  File "/home/docs/checkouts/readthedocs.org/user_builds/miniscope-io/envs/82/bin/mio", line 5, in <module>
    from mio.cli.main import cli
  File "/home/docs/checkouts/readthedocs.org/user_builds/miniscope-io/envs/82/lib/python3.12/site-packages/mio/cli/main.py", line 8, in <module>
    from mio.cli.stream import stream
  File "/home/docs/checkouts/readthedocs.org/user_builds/miniscope-io/envs/82/lib/python3.12/site-packages/mio/cli/stream.py", line 12, in <module>
    from mio.stream_daq import StreamDaq
  File "/home/docs/checkouts/readthedocs.org/user_builds/miniscope-io/envs/82/lib/python3.12/site-packages/mio/stream_daq.py", line 60, in <module>
    class StreamDaq:
  File "/home/docs/checkouts/readthedocs.org/user_builds/miniscope-io/envs/82/lib/python3.12/site-packages/mio/stream_daq.py", line 260, in StreamDaq
    def _init_okdev(self, BIT_FILE: Path) -> Union[okDev, okDevMock]:
                                                   ^^^^^
NameError: name 'okDev' is not defined

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

mio_config.yaml

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

env vars

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

.env file

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

pyproject.toml

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

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

cli

TODO

Device Configs

Todo

Document device configuration