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).

--configloc names the file cellpy actually reads. If you migrated from cellpy 1 and kept the old .cellpy_prms_<user>.conf, it says so explicitly — the legacy file is still on disk but no longer has any effect:

[cellpy] -> C:\Users\you\AppData\Local\cellpy\cellpy\cellpy.toml
[cellpy] (legacy C:\Users\you\.cellpy_prms_you.conf is ignored - cellpy.toml takes precedence)

When a project cellpy.toml is found by walking up from the current directory, --configloc names it too. That file is merged after the user file and wins on conflicts (cellpy edit config still opens the user file):

[cellpy] -> C:\Users\you\AppData\Local\cellpy\cellpy\cellpy.toml
[cellpy] (project C:\work\proj\cellpy.toml also applies and takes precedence)

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).