Setup and configuration¶

To get the most out of cellpy, set up your folders and a config file once. Runtime settings live in cellpy.config and are stored as cellpy.toml (not the old YAML .conf).

Quick setup¶

Interactive setup prompts for preferred locations:

cellpy setup -i

Silent / default layout:

cellpy setup --silent

Optional root folder for the directory tree:

cellpy setup -i -d /Users/you/cellpy_data

cellpy setup writes (or refreshes) a user cellpy.toml, tries to create the usual directory layout, and creates a .env_cellpy file for secrets / remote credentials (edit that file before using SSH remotes).

Typical directories:

batchfiles/
cellpyfiles/
db/
examples/
instruments/
logs/
notebooks/
out/
raw/
templates/

Where is my config?

cellpy info --configloc
cellpy info --config

--configloc / -l prints the path; --config / -C dumps resolved values with provenance (which layer each setting came from).

Configuration layers¶

Settings resolve later-over-earlier:

defaults → user cellpy.toml → project cellpy.toml → environment / .env → runtime overrides

Ask in Python:

import cellpy.config

print(cellpy.config.sources())

Environment variables use CELLPY_<SECTION>__<FIELD> (two underscores), e.g. CELLPY_READER__AUTO_DIRS=0.

Full key list: Configuration settings.

Example cellpy.toml¶

Paths are the part most people edit. A short example:

[paths]
outdatadir = "/home/you/cellpy_data/out"
rawdatadir = "/home/you/lab/raw"
cellpydatadir = "/home/you/cellpy_data/cellpyfiles"
db_path = "/home/you/cellpy_data/db"
filelogdir = "/home/you/cellpy_data/logs"
db_filename = "cellpy_db.xlsx"
env_file = "/home/you/.env_cellpy"

[reader]
cycle_mode = "anode"
sep = ";"

rawdatadir (and optionally cellpydatadir) may be a remote URI — see Work with remote files.

Runtime overrides¶

import cellpy does not load config by itself; first access / setup does. Prefer the new API:

import cellpy.config as config

config.reader.cycle_mode = "cathode"
config.reader.sep = ","
config.paths.outdatadir = "experiment01/processed_data"

Legacy from cellpy.parameters import prms still forwards with a DeprecationWarning — see Coming from cellpy 1.x.

Database file¶

cellpy can use a simple Excel “database” for cell metadata (name, mass, type, …) when running batch workflows. The first row is headers, the second row types, then one row per cell. A sample file ships with the batch tutorial.

Credentials¶

Passwords, SSH keys, and remote host details are not stored in cellpy.toml. They come from the environment or your .env / .env_cellpy file:

A [secrets] section in cellpy.toml is an error, not a silent override. Passwords are held as SecretStr so they do not appear in reprs, logs, or config dumps.

Legacy .conf files¶

Older installs used a YAML file named .cellpy_prms_USERNAME.conf. cellpy 2.x reads and migrates that format:

cellpy migrate

or let cellpy setup write a fresh TOML. Details: Coming from cellpy 1.x (configuration section).