search

Sarc-Graph / sarcgraph

MIT License
2 stars 2 forks source link

readme

SarcGraph

python os license

flake8 codecov Documentation Status

Binder DOI DOI

Table of Contents

Project Summary

SarcGraph is a tool for automatic detection, tracking and analysis of z-discs and sarcomeres in movies of beating human induced pluripotent stem cell-derived cardiomyocytes (hiPSC-CMs).



SarcGraph was initially introduced in Sarc-Graph: Automated segmentation, tracking, and analysis of sarcomeres in hiPSC-derived cardiomyocytes. This package is created to make SarcGraph more accessible to the broader research community.

For more information visit SarcGraph documentation.

Installation Instructions

Stable Version

From Conda

Follow the instructions to install Anaconda or Miniconda.

Create a new Conda envirnoment and install sarcgraph.

conda create --name sarcgraph-env -c conda-forge -c saeedmhz sarcgraph

Note: Type y and press Enter when prompted.

Activate the environment.

conda activate sarcgraph-env

From PyPI

Please check the Getting Started section in the documentation.

Developer's Version

Get a copy of the SarcGraph repository on your local machine

You can do this by clicking the green <> code button and selecting Download Zip or by running the following command in terminal and move to the directory of the sarcgraph repository.:

git clone https://github.com/Sarc-Graph/sarcgraph.git
cd sarcgraph

Create and activate a conda virtual environment

  1. Install Anaconda on your local machine.

  2. Type the following command in terminal to create a virtual envirnoment and install the required packages:

conda env create --file=environment.yml
  1. Activate your virtual environment.
conda activate sarcgraph

Install SarcGraph

Install SarcGraph in editable mode:

pip install -e .

Contents 

|___ sarcgraph
|        |___ docs/
|        |___ figures/
|                |___ *.png
|        |___ samples/
|        |___ sarcgraph/
|                |___ __init__.py
|                |___ sg.py
|                |___ sg_tools.py
|        |___ tests/
|        |___ tutorials/
|                |___ *.ipynb

Tutorial

This GitHub repository contains a folder called tutorials that contains demos to extensively show how this package can be used to analyze videos or images of hiPSC-CMs.

Package Contents

The package contains two seperate modules: sg for sarcomere detection and tracking and sg_tools for running further analysis and visualizations.

sarcgraph.sg

sarcgraph.sg module takes a video/image file as input (more details in tutorials). This module then processes the input file to detect and track z-discs and sarcomeres through running 3 tasks:

Here is a list of functions developed for each task:

  • frame: (frame number)
  • x and y: (X and Y position of the center of a z-disc)
  • p1_x, p1_y and p2_x, p2_y: (X and Y position of both ends of a z-disc)
  • particle: (z-disc id)
  • freq: (number of frames in which a z-discs is tracked) frame,sarc_id,x,y,length,width,angle,z-discs
  • frame: (frame number)
  • sarc_id: (sarcomere id)
  • x and y: (X and Y position of the center of a sarcomere)
  • length: (sarcomere length)
  • width: (sarcomere width)
  • angle: (sarcomere angle)
  • zdiscs: (ids of the two z-discs forming a sarcomere)

sarcgraph.sg_tools

sarcgraph.sg_tools module consists of 3 subclasses:

  • sarcomeres_gpr(): Applies Gaussian Process Regression (GPR) on each recovered timeseries characteristic of all detected sarcomeres to reduce the noise and fill in the missing data
  • compute_F_J: Computes the average deformation gradient (F) and its jacobian (J)
  • compute_OOP: Computes the Orientation Order Parameter (OOP)
  • compute_metrics: Computes {OOP, C_iso, C_OOP, s_til, s_avg} as defined in the SarcGraph paper
  • compute_ts_params: Computes timeseries constants (contraction time, relaxation time, flat time, period, offset)
  • 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
  • zdiscs_and_sarcs: Visualizes detected z-discs and sarcomeres in the chosen frame
  • contraction:Visualizes detected sarcomeres in every frame as a gif file
  • normalized_sarcs_length: Plots normalized length of all detected sarcomeres vs frame number
  • OOP: Plots recovered Orientational Order Parameter
  • F: Plots recovered deformation gradient
  • J: Plots recovered deformation jacobian
  • F_eigenval_animation: Visualizes the eigenvalues of F vs frame number
  • timeseries_params: Visualizes time series parameters
  • dendrogram: Clusters timeseries and plots as a dendrogram of the clusters
  • spatial_graph: Visualizes the spatial graph
  • tracked_vs_untracked: Visualizes metrics that compare the effect of tracking sarcomeres in a video vs only detecting sarcomeres in each frame without tracking

To use this module an object of the class SarcGraphTools should be created by setting the input_dir to the folder that contains the output saved from running full sarcomere detection and timeseries processing on the input data.

Validation

To validate our methods and ensure correct implementation, we generated challenging synthetic videos with characteristics similar to beating hiPSC-CMs. We used these videos to evaluate the sarcomere detection algorithm by comparing recovered metrics to their known ground truth. The figure shows this process for one of many tested validation examples.



References to Related Work

Contact Information

For information about this software, please get in touch with Saeed Mohammadzadeh or Emma Lejeune.

Acknowledgements