Config Reference

All config keys, organised by module

This is a reference for all available configuration keys in SleePyPhases. It is generated from the JSON Schema files defined by the core and plugin codebases. Keys marked with * are required.

Top-level Keys

Data & Paths

Key	Type	Default	Description
data-path	string	./data	Base path for data storage
eval-path	string	eval/	Path where evaluation results are stored

Model & Training

Key	Type	Default	Description
modelName	string	—	Name of the model class (also defines the path)
modelPath	string	—	Path where models are stored. Each model must be in modelPath/modelName/modelName.py
model	object	—	Model-specific configuration parameters
pretraining	object	—	Pretraining configuration passed to the model before the main training loop
trainingParameter	object	—	Hyperparameters controlling the training loop (extends pyPhasesML defaults) (see ↓ trainingParameter)
inputShape	array[integer | null]	—	Input shape as [segmentLength, channelSize]. Use null for dynamic dimensions

Dataset Splits & Folds

Key	Type	Default	Description
datasetSplits	array[string]	—	List of active split names derived from dataversion.split at runtime by Setup/Eval. Read-only — do not set manually
validationSplit	number	0.2	Fraction of records to reserve for the validation split when no explicit split slice is given
testSplit	number	0	Fraction of records to reserve for the test split when no explicit split slice is given
fold	integer	0	Zero-based index of the cross-validation fold to run
foldName	string	—	Named fold key from dataversion.namedFolds to use instead of a numeric fold index
startFold	integer	0	First fold index to run when iterating over all folds in Training
endFold	integer	—	Last fold index (exclusive) to run when iterating over folds in Training. Defaults to dataversion.folds
validateDataset	boolean	true	Raise an exception when the data-version validation fails (e.g. wrong number of records)
recordId	string	—	Single record ID to export. When set, only that record is processed
useLoader	string	—	The name of the loader to use (must match a key in ‘loader’)
dataversion	object	—	Data versioning and splitting configuration. Determines which records go into each split (see ↓ dataversion)

Segmentation

Key	Type	Default	Description
recordWise	boolean	true	If the data manipulation expects records (true) or segments (false)
segmentLength	integer	—	Length of each data segment in samples (at targetFrequency). Used when recordWise is false
segmentLengthLabel	integer	—	Length of each label segment in samples (at labelFrequency). Defaults to segmentLength when not set
segmentPadding	array[integer]	[0, 0]	Number of context samples to pad on each side of each segment: [left, right]

Label & Class Config

Key	Type	Default	Description
labelChannels	array[string]	—	Feature signals extracted from the record and stored as label (Y) channels alongside the model input
ignoreClassIndex	integer	—	Class index to always ignore during training and evaluation

Data Manipulation

Key	Type	Default	Description
segmentManipulation	array[object]	—	Data augmentation / manipulation steps applied to each segment during training dataset building
segmentManipulationEval	array[object]	—	Manipulation steps applied to each segment during evaluation and prediction (no augmentation). Defaults to segmentManipulation when not set
batchManipulation	array[object]	—	Data manipulation steps applied at the batch level during dataset building
manipulationAfterPredict	array[object]	—	Post-processing steps applied to raw model output before scoring or storing predictions

Evaluation

Key	Type	Default	Description
evalOn	string | object	—	Controls which split (or alternative dataset config) is used for the Eval and EvalReport phases
enableEventEval	boolean	true	Include event-based (epoch-level) evaluation in EvalReport
thresholdMetric	string | array[string] | null	—	Metric(s) used to select the optimal threshold. One metric per label
fixedThreshold	number | array[number] | False	false	Fixed classification threshold(s) applied to model output probabilities. Provide a single number, a per-label array, or false to use the optimised threshold.
optimizeOn	string	validation	Split name used for threshold optimisation in ThresholdOptimisation phase. One of: training, validation, test
optimizeThresholdFor	string	—	Label name to restrict threshold optimisation to (optimises all labels when null)
startThresholdsAt	array[number]	—	Initial threshold values for each label used by ThresholdOptimisation

Feature Extraction

Key	Type	Default	Description
featureConfigs	object	—	Per-feature configuration objects keyed by feature name, used by FeatureExtraction

Export (SleepHarmonizer)

Key	Type	Default	Description
export	object	—	Specification of which signals and annotations to include in the exported records (see ↓ export)
export-path	string	data/export/	Path to the directory where exported records will be written
useWriter	string	RecordWriterEDF	Name of the record writer to use for exporting records. One of: RecordWriterEDF, RecordWriterDICOM

Other

Key	Type	Default	Description
importAfter	array[string]	—
importBefore	array[string]	—
isFullConfig	boolean	false	If true, this is a full project config. Otherwise merged into config section.
loader	object	—	Named loader configurations. Each key is a loader name (e.g., ‘nox’, ‘shhs’).
metadata-update-query	string	1	Pandas query string that selects which records to reload during an UpdateMetadata phase
oneHotDecoded	boolean	false	Whether the labels are one-hot encoded

Nested Configuration Sections

classification

Classification task definition

Key	Type	Default	Description
labelNames	array[string]	—	Names of the label channels in the order they appear in the model output
classNames	array[array[string]]	—	Class names per label channel. Each entry is the list of class names for that label
name	string	default	Identifier for the classification task, used in log filenames and reports
predictionSignals	array[string]	—	Name of the signal channel that carries the raw model prediction for each label
predictionFrequencies	array[number]	—	Sampling frequency (in Hz) of each prediction signal, in the same order as predictionSignals
scorerTypes	array[string]	—	Scorer type per label: ‘segment’ for epoch-level scoring or ‘event’ for event-level scoring

preprocessing

Signal preprocessing configuration applied during Extract, Predict and Export phases.

Key	Type	Default	Description
targetFrequency	number	100	Target sampling frequency in Hz that all signals are resampled to. The resampling need to configured in preprocessing.stepsPerType
stepsPerType	object	—	Signal-type-specific preprocessing pipeline. Keys are signal types (eeg, eog, emg, ecg, …); values are ordered lists of preprocessing step names (strings) or step objects with a ‘name’ key. See https://sleepyphases.readthedocs.io/en/latest/tutorial/preprocessing.html#configuring-preprocessing-steps
labelFrequency	number	—	Frequency in Hz of the label/annotation channel (e.g. 1/30 for 30-second sleep stages)
dtype	string	float32	Numpy dtype used when exporting or loading processed signals. One of: float16, float32, float64
targetChannels	array[array[string | array[string]]]	—	Ordered list of target channels. Each element is a priority list; the first matching channel in the record is used
manipulationSteps	array[object]	—	Global preprocessing steps applied to all channels (alternative to stepsPerType)
featureChannels	array[object]	—	List of channel names to extract and added to the record signal during preprocessing. These allows the creation of custom channels that can be than used in preprocessing.targetChannels. See: https://sleepyphases.readthedocs.io/en/latest/tutorial/preprocessing.html#feature-channels for details.
tailorToTargetSignals	boolean	false	When true (Predict phase), an a record is skipped if any of the channels defined in preprocessing.targetChannels are missing from the record (BEFORE preprocessing/feature extraction).
combineChannels	object	—	Virtual combined channels: keys are new channel names, values list the source channels to average/concatenate

dataversion

Data versioning and splitting configuration. Determines which records go into each split

Key	Type	Default	Description
seed	null | integer	—	Random seed used when shuffling records before splitting
recordIds	array | null	—	Explicit ordered list of record IDs used to create splits. Overrides the database-derived list
groupBy	string | null	—
filterQuery	string	1	Pandas query string applied to the metadata DataFrame to filter records (e.g. ‘age >= 18 and ahi > 15’)
allChannels	string | False	false	When set, requires all channels of this type to pass channelFilterQuery (rather than at least one)
channelNameQueries	object | False	false
folds	integer	0	Number of cross-validation folds. When > 0 the trainval slice is divided into this many folds
namedFolds	object	—	Explicitly named fold configurations. Each key is a fold name; value defines custom slices or configurations.
split	object	—	Define data splits using slice notation (e.g. ‘0:80’ for first 80 %). Special key ‘trainval’ is used with folds

datafold

Multi-dataset cross-validation configuration. Allows combining multiple dataset configs for each fold

Key	Type	Default	Description
datasets	object	{}	Map from dataset/fold key to a config overlay applied for that dataset fold
seed	integer	2024	Random seed for shuffling within datafold dataset selection
shuffle	boolean	false	Shuffle dataset order within each datafold split

trainingParameter

Hyperparameters controlling the training loop (extends pyPhasesML defaults)

Key	Type	Default	Description
batchSize	integer	32	Number of segments per training batch
maxEpochs	integer | False	—	Maximum number of epochs (false for unlimited)
learningRate	number	0.001	Learning rate
learningRateDecay	number	0	Learning rate decay
optimizer	string	adams	Optimizer type: a predefined name (adams, adamsw, nadams, sgd, rmsprop, nesterov) or a custom string for model-specific optimizers.
validationEvery	integer | False	—	Validate every N epochs (deprecated)
validationMetrics	any	—
stopAfterNotImproving	integer | False	10	Early stopping patience (false to disable)
cyclicLearningRate	boolean	false	Enable cyclic learning rate scheduling (CLR)
cycleLRDivisor	integer	4	Cyclic LR divisor (minLR = lr / cycleLRDivisor)
classWeights	array[number]	—	Class weights for loss calculation
shuffle	boolean	false	Shuffle segments within each training epoch
shuffleSeed	integer	2	Random seed for shuffle reproducibility
findCyclicLearningRate	boolean	false	Run the LR-range finder before training instead of training normally

eval

Evaluation-specific configuration

Key	Type	Default	Description
batchSize	integer	—	Batch size used when loading the test dataset for evaluation
metrics	array[string]	—	Metrics to compute during evaluation. Defaults to trainingParameter.validationMetrics
clinicalMetrics	array[string]	—	Additional clinical metadata fields to include in the evaluation report

eventEval

Event-level evaluation settings used by the EventScorer

Key	Type	Default	Description
tpStrat	string	overlap	True-positive matching strategy: ‘overlap’ counts any overlap as TP; ‘majority’ requires >50 % overlap. One of: overlap, majority
tnStrat	string	eventcount	True-negative counting strategy: ‘eventcount’ counts TN as the number of non-event windows; ‘noTN’ disables TN counting. One of: eventcount, noTN
augmentationCountThatShouldNotBeOptimized	integer	0	Number of augmentation steps at the end of segmentManipulation that should be excluded during threshold optimisation
manipulationAfterPredict	array | boolean	—	Post-predict manipulation steps used specifically during event threshold optimisation. False disables

featureExtraction

Feature extraction configuration for the ExtractFeatures phase

Key	Type	Default	Description
features	array[object]	[]	List of feature configurations to extract. Each item names a feature and its parameters
force	boolean	false	Re-compute features even if a cached version already exists

predict

Configuration for the Predict phase (running the model on new, unseen recordings)

Key	Type	Default	Description
inputFile	string	—	Path to the input EDF (or other format) file to run prediction on
weights	string | False	false	Path to custom model weights file. false = use the weights produced by Training
recordLoader	string | False	false	RecordLoader class name to use when reading the input file. false = auto-detect
channelMapping	object	—	Map from expected channel names (as defined in preprocessing.targetChannels) to actual channel names present in the input file
lastChannelMappingPath	string	lastchannelmapping.json	File path where the last interactive channel mapping is persisted for reuse

cleanup

LogCleanup phase configuration

Key	Type	Default	Description
options	array[string]	—	Cleanup flags. ‘all’ skips interactive confirmation and removes everything matching the criteria

overview

LogOverview phase configuration for aggregating and displaying training results

Key	Type	Default	Description
logDirectory	string	results/	Root directory that contains per-run result sub-folders
evalFolder	string	eval/	Sub-path inside each run folder where evaluation artefacts are stored
configName	string	project.config	Filename of the serialised config inside each run folder
minEpochs	integer	10	Minimum number of completed training epochs required for a run to appear in the overview
useEpoch	integer	-1	Epoch index to read metrics from (-1 = last epoch)
query	string | False	false	Pandas query string to filter the results table after loading. false = no filter
ignore	array[string]	[]	Config key names to exclude from the overview table
ignoreValues	array[any]	[]	Values to treat as missing / ignore when comparing runs
dropColumns	array[string]	[]	Column names to drop from the final overview table
replaceValues	object	{}	Column-level value replacement map. Keys are column names; values are {from: to} dicts or a ‘default’ key
addLabelnames	array[string]	[]	Additional label name strings to append to the label names derived from classification.labelNames

debugConfig

Debug configuration for TestRun phase, overwrites/extends default configuration

No documented sub-keys.

somnometrics

Per-metric configuration for somnometric feature extraction (keyed by metric name)

No documented sub-keys.

BuildDataset

Phase-level configuration for the BuildDataset phase

Key	Type	Default	Description
useMultiThreading	boolean	true	Use multiple threads when building the dataset

export

Specification of which signals and annotations to include in the exported records

Key	Type	Default	Description
channels	array[array[string]]	[]	List of channel groups. Each group is an ordered list of alternative channel names; the first name found in the record is used and renamed to the first entry
annotations	array[string]	[]	List of annotation group names to include (e.g. ‘apnea’, ‘arousal’, ‘sleepStage’). Groups are expanded via PSGEventManager.eventGroups
unitMap	object	{}	Map of channel type or label to the physical unit string used when writing the record