Project Configuration

The project configuration YAML file exists in the root of the project folder and holds the main parameters for the VAME workflow. The configuration file is created when initializing a new project with the init_new_project function, and some values are updated by later steps.

Some fields are kept so older projects still load, but are not read by the current code. They are marked as not used below.

Project parameters

Field	Type	Default	Description
vame_version	str		VAME version that created the project.
project_name	str		Name of the project.
project_path	str		Path to the project folder.
creation_datetime	str		Creation time of the project, in UTC (ISO 8601).
session_names	List[str]		Names of the sessions in the project, one per pose estimation file.
pose_estimation_filetype	str		File type of the input pose estimation files: csv, nwb, slp, h5 or nc.
video_type	Optional[str]	None	Extension of the project's raw videos (.mp4 or .avi), recorded when they are loaded. None when the project has no videos or mixes formats; each session's video is resolved from data/raw either way.
project_random_state	int	42	Seed for model training, the train/test split, k-means, HMM and UMAP.

Data and preprocessing

Field	Type	Default	Description
all_data	str	"yes"	When "yes", segmentation, community analysis and video functions run on all sessions. Otherwise they ask which sessions to use.
keypoints	Optional[List[str]]	None	Names of the keypoints in the pose estimation data.
extra_features	List[str]	[]	Names of pre-computed scalar features stored in each session's processed .nc file and appended to the model input. Written with vame.io.add_extra_features.
preprocessed_variable	str	"position_processed"	Output variable of the last preprocessing step. Set by vame.preprocessing, and read by create_trainset by default.
pose_confidence	float	0.99	Confidence threshold for low-confidence cleaning. Points below it are cleared and interpolated.
robust	bool	True	When false, outlier cleaning leaves the data unchanged.
iqr_factor	int	4	Outlier cleaning removes points whose z-score is more than iqr_factor times the IQR.
savgol_length	int	5	Window length of the Savitzky-Golay filter.
savgol_order	int	2	Polynomial order of the Savitzky-Golay filter.
test_fraction	float	0.1	Fraction of the data held out for testing, used when create_trainset is called with test_fraction=None.
egocentric_data	bool	False	Whether the data is egocentric from the start, as with head-fixed animals. Only read by vame.pose_to_numpy, which requires it to be true.
savgol_filter	bool	True	Not used. Pass run_savgol_filtering to vame.preprocessing instead.

RNN model general hyperparameters

Field	Type	Default	Description
model_name	str	"VAME"	Name of the model, used in model and results file paths.
pretrained_model	str	"None"	Model to start training from when pretrained_weights is true: the name of a model in this project, or a path to a weights file.
pretrained_weights	bool	False	Whether training starts from the weights of pretrained_model. KL annealing is skipped in that case.
num_features	int	12	Number of input features per frame. Set when the project and the training set are created.
batch_size	int	256	Training batch size. The test batch size is a quarter of it.
max_epochs	int	500	Maximum number of training epochs.
model_snapshot	int	50	Save a snapshot of the model every this many epochs.
model_convergence	int	50	Stop training after this many epochs without improvement of the test loss.
beta	float	1	Weight of the KL divergence loss.
zdims	int	30	Number of latent dimensions.
learning_rate	float	5e-4	Learning rate of the Adam optimizer.
time_window	int	30	Number of frames in each input window.
prediction_decoder	int	1	Whether the model has a decoder that predicts the frames after each window (1) or not (0).
prediction_steps	int	15	Number of future frames the prediction decoder predicts.
noise	bool	False	Whether Gaussian noise is added to the training inputs.
scheduler	int	1	1 reduces the learning rate when the test loss stops improving (ReduceLROnPlateau). 0 keeps it constant.
scheduler_step_size	int	100	Epochs without improvement before the learning rate is reduced.
scheduler_gamma	float	0.2	Factor the learning rate is multiplied by when it is reduced.
softplus	bool	False	Whether a softplus activation is applied to the encoder's log-variance output.
steps_per_epoch	Optional[int]	None	Number of batches per epoch. None draws one sample per frame, so epoch length grows with the data.
transition_function	str	"GRU"	Not used. The model always uses GRUs.
beta_norm	bool	False	Not used.
scheduler_threshold	Optional[float]	None	Not used. The scheduler uses a relative threshold of 1e-3.

Segmentation

Field	Type	Default	Description
n_clusters	int	15	Number of motifs.
segmentation_algorithms	List[str]	["hmm", "kmeans"]	Algorithms used to segment the latent space into motifs.
hmm_trained	bool	False	When true, segmentation loads the HMM saved in results/hmm_trained.pkl instead of fitting a new one.
hmm_n_iter	int	100	Maximum number of iterations when fitting the HMM.
kmeans_n_init	int	20	Number of times k-means is run with different centroid seeds. The run with the lowest inertia is kept. Lower values make k-means faster on large datasets.
kmeans_fit_samples	Optional[int]	None	Number of frames, sampled at random with project_random_state, that k-means is fit on. Every frame is then assigned to its nearest cluster center. None fits on all frames.

Video writer

Field	Type	Default	Description
length_of_motif_video	int	1000	Maximum number of frames in each motif video.

UMAP parameters

Field	Type	Default	Description
min_dist	float	0.1	UMAP min_dist.
n_neighbors	int	200	UMAP n_neighbors.
num_points	int	30000	Number of points used for the UMAP embedding in vame.gif.

RNN encoder hyperparameters

Field	Type	Default	Description
hidden_size_layer_1	int	256	Hidden size of the encoder GRU.
hidden_size_layer_2	int	256	Not used.
dropout_encoder	float	0	Dropout in the encoder.

RNN reconstruction hyperparameters

Field	Type	Default	Description
hidden_size_rec	int	256	Hidden size of the reconstruction decoder GRU.
dropout_rec	float	0	Dropout in the reconstruction decoder.
n_layers	int	1	Not used. The number of GRU layers is fixed in the model.

RNN prediction hyperparameters

Field	Type	Default	Description
hidden_size_pred	int	256	Hidden size of the prediction decoder GRU.
dropout_pred	float	0	Dropout in the prediction decoder.

RNN loss hyperparameters

Field	Type	Default	Description
mse_reconstruction_reduction	str	"sum"	Reduction of the reconstruction MSE loss ("sum" or "mean").
mse_prediction_reduction	str	"sum"	Reduction of the prediction MSE loss ("sum" or "mean").
kmeans_loss	int	30	Number of singular values of the latent Gram matrix summed in the k-means loss.
kmeans_lambda	float	0.1	Weight of the k-means loss.
anneal_function	str	"linear"	Shape of the KL annealing schedule: "linear" or "sigmoid".
kl_start	int	2	Epoch at which the KL and k-means losses start to be added.
annealtime	int	4	With "linear", the number of epochs over which the KL weight ramps up to 1. With "sigmoid", the epoch at the middle of the ramp.