SarcGraphTools - Analysis

All demos are availble on GitHub at https://github.com/Sarc-Graph/sarcgraph/tree/main/tutorials.

To run demos with jupyter notebook check Installation Guide.

SarcGraph includes the tools which enable the recovery of basic sarcomere characteristics and the ability to run further high level analysis.

In this notebook we provide a tutorial on how to use the SarcGraph package using demos and examples. The focus is on the SarcGraphTools.Analysis class in the sg_tools module.

Initialization

Methods in the SarcGraphTools class need the information that will be saved by running SarcGraph.sarcomere_detection().

To showcase this we use samples/sample_1.avi.

import numpy as np
import matplotlib.pyplot as plt
import pandas as pd

from sarcgraph import SarcGraph

sg = SarcGraph(output_dir='../tutorial-results', input_type='video')
sarcomeres, _ = sg.sarcomere_detection(input_file='../samples/sample_1.avi')

sarcomeres.sample(5)

Frame 79: 91 trajectories present.

	frame	sarc_id	x	y	length	width	angle	zdiscs
783	63	9	100.959195	106.775141	24.390126	21.496951	0.622702	-35,-28
82	2	1	153.784835	64.936307	21.563298	25.762765	1.102697	-40,-22
5732	52	71	149.771889	188.185834	12.032297	10.872591	2.306348	68,89
3356	76	41	242.743014	250.967316	11.967362	9.383441	2.095774	2,6
5361	1	67	144.302499	178.563181	13.959253	8.317837	2.684629	49,68

By default sg.config.save_output=True and the following information will be saved in ../tutorial-results:

• raw video frames (grayscale)

• filtered video frames

• zdisc contours

• segmented zdiscs information

• tracked zdiscs information

• detected sarcomeres information

The next step is to run SarcGraphTools.TimeSeries() to apply GPR on timeseries data related to each sarcomere.

from sarcgraph import SarcGraphTools

sg_tools = SarcGraphTools(input_dir='../tutorial-results')
_ = sg_tools.time_series.sarcomeres_gpr()

This step is used for noise reduction as well as interpolating missing values of the timeseries (x_position, y_position, length, width, angle, length_normalized).

Characterization Analysis

Here is a list of available functions in the SarcGraphTools.Analysis class:

• compute_F_J(): Computes the average deformation gradient (F) and its jacobian (J) for the whole movie

• compute_OOP(): Computes Orientation Order Parameter (OOP) for the whole movie

• compute_metrics(): Computes (OOP, C_iso, C_OOP, s_til, s_avg) as defined in the SarcGraph paper

• compute_ts_params(): Computes (contraction time, relaxation time, flat time, period, offset, etc.) for timeseries

• create_spatial_graph(): Generates a spatial graph of tracked z-discs where edges indicate sarcomeres and edge weights indicate the ratio of the frames in which each sarcomere is detected

Note

Check the api reference for SarcGraphTools

To run these functions, create an instance of the SarcGraphTools class and set the input_dir to the directory used previously to save the output of sarcomere detection (in this case input_dir='../tutorial-results')

from sarcgraph import SarcGraphTools

sg_tools = SarcGraphTools(input_dir='../tutorial-results')

Now, any of the functions listed above can be executed. For examples, run the following for F and J computation:

F, J = sg_tools.analysis.compute_F_J()

This also saves F and J in the specified input directory input_dir if save_results=True in SarcGraphTools

Run the rest of the function:

OOP, OOP_vec = sg_tools.analysis.compute_OOP()

metrics = sg_tools.analysis.compute_metrics()

ts_params = sg_tools.analysis.compute_ts_params()

Note

create_spatial_graph() needs access to the original video/image file file_path or a dataframe that contains information of detected and tracked z-discs tracked_zdiscs. So, below we show two ways to run this functions:

1. Specifying file_path

sg_tools.analysis.create_spatial_graph(file_path='../samples/sample_1.avi')

Frame 79: 91 trajectories present.
output_dir = output
input_type = image
save_output = False
sigma = 1.0
zdisc_min_length = 10
zdisc_max_length = 100
full_track_ratio = 0.75
tp_depth = 4
skip_merge = False
num_neighbors = 3
avg_sarc_length = 15.0
min_sarc_length = 0.0
max_sarc_length = 30.0
coeff_avg_length = 1.0
coeff_neighbor_length = 1.0
coeff_neighbor_angle = 1.0
score_threshold = 0.1
angle_threshold = 1.2

2. Specifying tracked_zidscs

# loading saved tracked_zidscs from 'tutorial-results' folder
import pandas as pd

tracked_zdiscs = pd.read_csv(
    f"{sg_tools.input_dir}/tracked_zdiscs.csv", index_col=[0]
)

sg_tools.analysis.create_spatial_graph(tracked_zdiscs=tracked_zdiscs)

output_dir = output
input_type = video
save_output = False
sigma = 1.0
zdisc_min_length = 10
zdisc_max_length = 100
full_track_ratio = 0.75
tp_depth = 4
skip_merge = False
num_neighbors = 3
avg_sarc_length = 15.0
min_sarc_length = 0.0
max_sarc_length = 30.0
coeff_avg_length = 1.0
coeff_neighbor_length = 1.0
coeff_neighbor_angle = 1.0
score_threshold = 0.1
angle_threshold = 1.2
output_dir = output
input_type = image
save_output = False
sigma = 1.0
zdisc_min_length = 10
zdisc_max_length = 100
full_track_ratio = 0.75
tp_depth = 4
skip_merge = False
num_neighbors = 3
avg_sarc_length = 15.0
min_sarc_length = 0.0
max_sarc_length = 30.0
coeff_avg_length = 1.0
coeff_neighbor_length = 1.0
coeff_neighbor_angle = 1.0
score_threshold = 0.1
angle_threshold = 1.2

After running all functions the following files will be added to input_dir:

• recovered_F.npy

• recovered_J.npy

• recovered_OOP.npy

• recovered_OOP_vector.npy

• recovered_metrics.json

• spatial-graph.pkl

• spatial-graph-pos.pkl

• time_series_params.csv