Package: sarcgraph
SarcGraphTable of ContentsProject SummaryInstallation InstructionsContentsTutorial-NotebooksValidationReferences to Related WorkContact InformationAcknowledgementsProject SummarySarcGraphis a tool for automatic detection, tracking and analysis of
z-discs and sarcomeres in movies of beatinghuman induced pluripotent stem
cell-derived cardiomyocytes (hiPSC-CMs).SarcGraph was initially introduced inSarc-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 visitSarcGraph documentation.Installation InstructionsStable VersionFrom CondaFollow the instructions to installAnacondaorMiniconda.Create a new Conda envirnoment and install sarcgraph.condacreate--namesarcgraph-env-cconda-forge-csaeedmhzsarcgraphNote:Typeyand pressEnterwhen prompted.Activate the environment.condaactivatesarcgraph-envFrom PyPIPlease check theGetting Startedsection in the documentation.Developer's VersionGet a copy of theSarcGraph repositoryon your local machineYou can do this by clicking the green<> codebutton and selectingDownload Zipor by running the following command in terminal and move to the directory of thesarcgraphrepository.:gitclonehttps://github.com/Sarc-Graph/sarcgraph.gitcdsarcgraphCreate and activate a conda virtual environmentInstallAnacondaon your local machine.Type the following command in terminal to create a virtual envirnoment and install the required packages:condaenvcreate--file=environment.ymlActivate your virtual environment.condaactivatesarcgraphInstall SarcGraphInstall SarcGraph in editable mode:pipinstall-e.Contents|___sarcgraph||___docs/||___figures/||___*.png||___samples/||___sarcgraph/||_____init__.py||___sg.py||___sg_tools.py||___tests/||___tutorials/||___*.ipynbTutorialThis GitHub repository contains a folder calledtutorialsthat contains demos to extensively show how this package can be used to analyze videos or images of hiPSC-CMs.Package ContentsThe package contains two seperate modules:sgfor sarcomere detection and tracking andsg_toolsfor running further analysis and visualizations.sarcgraph.sgsarcgraph.sgmodule 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:Z-disc Segmentation,Z-disc Tracking,Sarcomere Detection.Here is a list of functions developed for each task:zdisc_segmentation: Detect z-discs in each frame of the input video/image and saves the following information into a pandasDataFrame:frame: (frame number)xandy: (X and Y position of the center of a z-disc)p1_x,p1_yandp2_x,p2_y: (X and Y position of both ends of a z-disc)zdisc_tracking: Tracks detected z-discs in the input video over all frames and adds the following information to the pandasDataFrame:particle: (z-disc id)freq: (number of frames in which a z-discs is tracked)
frame,sarc_id,x,y,length,width,angle,z-discssarcomere_detection: Detects sarcomeres in the input video/image using tracked z-discsDataFrameand saves the following information into a new pandasDataFrame:frame: (frame number)sarc_id: (sarcomere id)xandy: (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_toolssarcgraph.sg_toolsmodule consists of 3 subclasses:TimeSeries: Process timeseries of detected and tracked sarcomeressarcomeres_gpr(): Applies Gaussian Process Regression (GPR) on each recovered timeseries characteristic of all detected sarcomeres to reduce the noise and fill in the missing dataAnalysis: Extract more information from detected sarcomeres characteristics timeseriescompute_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 theSarcGraph papercompute_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 detectedVisualization: Visualize detected sarcomeres informationzdiscs_and_sarcs: Visualizes detected z-discs and sarcomeres in the chosen framecontraction:Visualizes detected sarcomeres in every frame as a gif filenormalized_sarcs_length: Plots normalized length of all detected sarcomeres vs frame numberOOP: Plots recovered Orientational Order ParameterF: Plots recovered deformation gradientJ: Plots recovered deformation jacobianF_eigenval_animation: Visualizes the eigenvalues of F vs frame numbertimeseries_params: Visualizes time series parametersdendrogram: Clusters timeseries and plots as a dendrogram of the clustersspatial_graph: Visualizes the spatial graphtracked_vs_untracked: Visualizes metrics that compare the effect of tracking sarcomeres in a video vs only detecting sarcomeres in each frame without trackingTo use this module an object of the classSarcGraphToolsshould be created by setting theinput_dirto the folder that contains the output saved from running full sarcomere detection and timeseries processing on the input data.ValidationTo 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 WorkZhao, B., Zhang, K., Chen, C. S., & Lejeune, E. (2021). Sarc-graph: Automated segmentation, tracking, and analysis of sarcomeres in hiPSC-derived cardiomyocytes. PLoS Computational Biology, 17(10), e1009443.Allan, D. B., Caswell, T., Keim, N. C., Wel, C. M. van der, & Verweij, R. W. (2023). Soft-matter/trackpy: v0.6.1 (Version v0.6.1). Zenodo.https://doi.org/10.5281/zenodo.7670439Toepfer, C. N., Sharma, A., Cicconet, M., Garfinkel, A. C., Mücke, M., Neyazi, M., Willcox, J. A., Agarwal, R., Schmid, M., Rao, J., & others. (2019). SarcTrack: An adaptable software tool for efficient large-scale analysis of sarcomere function in hiPSC-cardiomyocytes. Circulation Research, 124(8), 1172–1183.Morris, T. A., Naik, 94 J., Fibben, K. S., Kong, X., Kiyono, T., Yokomori, K., & Grosberg, A. (2020). Striated myocyte structural integrity: Automated analysis of sarcomeric z-discs. PLoS Computational Biology, 16(3), e1007676.Pasqualin, C., Gannier, F., Yu, A., Malécot, C. O., Bredeloux, P., & Maupoil, V. (2016). SarcOptiM for ImageJ: High-frequency online sarcomere length computing on stimulated cardiomyocytes. American Journal of Physiology-Cell Physiology, 311(2), C277–C283.Ribeiro, A. J. S., Schwab, O., Mandegar, M. A., Ang, Y.-S., Conklin, B. R., Srivastava, D., & Pruitt, B. L. (2017). Multi-imaging method to assay the contractile mechanical output of micropatterned human iPSC-derived cardiac myocytes. Circulation Research, 120(10), 1572–1583.https://doi.org/10.1161/CIRCRESAHA.116.310363Contact InformationFor information about this software, please get in touch withSaeed MohammadzadehorEmma Lejeune.Acknowledgements