IOCBioSarcomereLength.md

Introduction

IOCBio provides a C library libfperiod and Python package iocbio.fperiod with tools to determine the fundamental period of a signal with an application to estimating sarcomere length of a single cardiomyocyte from its microscopy image. The underlying theory of the method is described in a paper

• Pearu Peterson, Mari Kalda, Marko Vendelin. Real-time Determination of Sarcomere Length of a Single Cardiomyocyte during Contraction Am J Physiol Cell Physiol, 304(6):C519–C531, 2013.

This page describes how to use the provided software. Please file all found bugs and feature requests to Issues.

Usage from a C program

First, download libfperiod source code. The source code consists of three files:

• libfperiod.c - source code to be compiled and linked with your C program
• libfperiod.h - header file to be included by the C program
• demo.c - demo code illustrating the basic usage of determining the fundamental period of a sine function.

Second, study the demo program above that shows how to call the iocbio_fperiod function from your C program. Here follows an example session:

$ cc demo.c libfperiod.c -o demo -lm
$ ./demo 20 5.4
Signal definition: f[i]=sin(2*pi*i/5.400000), i=0,1,..,19
Number of repetitive patterns in the signal=3.703704
Detrend algorithm is disabled
Expected  fundamental period=5.400000
Estimated fundamental period=5.389328
Relative error of the estimate=0.197630%

The libfperiod API exposes the following functions to users (see libfperiod.h for C definitions):

• iocbio_fperiod - compute fundamental period of a sequence
• iocbio_fperiod_cached - same as iocbio_fperiod but with extra cache argument that can be used to avoid malloc/free cycle in repetitive computations of the fundamental period.
• iocbio_objective - evaluate the similarity measure that defines the fundamental period of a signal sequence as its first non-zero minimum point
• iocbio_detrend - apply detrend algorithm to a signal sequence

Usage from a Python program

First, you must install iocbio Python package version 1.3 or newer.

Here follows an example Python session using the iocbio.fperiod package:

>>> from iocbio import fperiod
>>> print fperiod.fperiod.__doc__
fperiod - Function signature:
  period = fperiod(f,[initial_period,detrend,method])
Required arguments:
  f : input rank-2 array('d') with bounds (m,n)
Optional arguments:
  initial_period := 0.0 input float
  detrend := 0 input int
  method := 0 input int
Return objects:
  period : float

>>> from numpy import sin, arange, pi
>>> N = 20; i = arange(N)
>>> P = 5.4
>>> f = sin(2*pi*i/P)
>>> Pest = fperiod.fperiod(f)
>>> print 'Estimated fundamental period:',Pest
Estimated fundamental period: 5.3893279719
>>> print 'Relative error of the estimate:',(1-Pest/P)*100,'%'
Relative error of the estimate: 0.197630149933 %