Training of ContractionNet

This tutorial explains how to train ContractionNet with custom training data. SarcAsM contains a pretrained model that works well for most use cases. If users are unsatisfied with the results of this model, we recommend training of a custom model.

Creating training data

ContractionNet is trained on individual time-series with respective ground truth binary time-series (0: quiescent phase, 1: contraction intervals). As training data, we recommend a mixture of ~200 manually annotated and ~200 simulated time-series.

For training, the time series need to be stored as plain .txt files in a folder together with their ground truth using identical names with additional ‘_contr’ at the end for the ground truth (e.g., time series: time_series_123xyz.txt, ground truth: time_series_123xyz_contr.txt).

import os

import numpy as np

# folder with training data
folder_training_data = 'path/to/training_data/'  # adjust path
os.makedirs(folder_training_data, exist_ok=True)

Time-series of Z-bands and sarcomere lengths

Users can either manually collect time-series and save them as .txt files, or use time-series of Z-band positions and sarcomere lengths analyzed by SarcAsM as described here for a list of LOIs:

from sarcasm import Motion

# assuming list_lois is defined (list of tuples with (filename, loi))
for file, loi in list_lois:
    motion_obj = Motion(file, loi)

    # track Z-bands
    motion_obj.detekt_peaks()
    motion_obj.track_z_bands()

    # save individual z-band position and sarcomere length time series as .txt
    z_pos = motion_obj.loi_data['z_pos']
    slen = motion_obj.loi_data['slen']
    name = os.path.basename(file)[:-4]

    for i, z_i in enumerate(z_pos):
        np.savetxt(folder_training_data + f'{name}_z_pos_{i}.txt', z_i)
    for i, slen_i in enumerate(slen):
        np.savetxt(folder_training_data + f'{name}_slen_{i}.txt', slen_i)

Manual annotation of contraction intervals in experimental time-series

For experimental time-series data, contraction intervals are manually annotated in an interactive jupyter notebook, using the customTimeSeriesAnnotator, see API reference.

Press the left mouse button at the start of contraction interval and release at the end of contraction interval. When annotation of time-series is finished, press “Save & Next”. In case of annotation mistakes, press “Reset” and to reset annotations of current time-series.

import matplotlib
import glob
import os
from contraction_net.annotation import TimeSeriesAnnotator
matplotlib.use('nbagg')
%matplotlib notebook

# find all .txt files
files= glob.glob(folder_training_data + '*.txt')

# start annotator (adjust output_dir)
TimeSeriesAnnotator(files, output_dir=folder_training_data)

<contraction_net.annotation.TimeSeriesAnnotator at 0x11f0b07d0>

Simulation of time-series using trigonometric functions

Training time-series are simulated using trigonometric functions to create the base signals and adds random drift and noise to simulate real-world conditions, parameters and details see API reference.

from contraction_net.utils import simulate_training_data

simulate_training_data(folder_training_data, n=100, input_len=512)

Training

Next, the training dataset is processed and augmented, e.g., by addition of normal-distributed noise or random outliers, all parameters see API reference:

from contraction_net.data import DataProcess

# prepare training data, adjust augmentation parameters
dataset = DataProcess(folder_training_data)

from contraction_net.utils import plot_selection_training_data

# plot selection of training data
plot_selection_training_data(dataset, n_sample=10)

from contraction_net.contraction_net import ContractionNet
from contraction_net.training import Trainer

save_dir = '../temp_training/'  # adjust path

# set training parameters
trainer = Trainer(dataset=dataset, n_filter=64, network=ContractionNet, lr=0.001, loss_function='BCEDice', num_epochs=100, batch_size=32, save_iter=True, save_dir=save_dir)

# start training
trainer.start()

After training is completed, the model parameters model.pt are stored in the save_dir.