search

ToReinberger / pyHeart4Fish

A heart beat analysis tool for zebrafish hearts
BSD 2-Clause "Simplified" License
5 stars 1 forks source link

readme

pyHeart4Fish - A Heartbeat Analysis Tool for Zebrafish

Please cite the original paper:

V. Vedder and T. Reinberger et al.
"pyHeart4Fish: Chamber-specific heart phenotype quantification of zebrafish in high-content screens"
Front. Cell Dev. Biol. Sec. Molecular and Cellular Pathology , Volume 11 - 2023 | doi: 10.3389/fcell.2023.1143852

<!README file was written according to: https://medium.com/analytics-vidhya/how-to-create-a-readme-md-file-8fb2e8ce24e3>

Content

  1. How to install pyHeart4Fish
  2. Tutorial - How to run pyHeart4Fish
  3. Troubleshooting and FAQ
  4. Licensing

How to install pyHeart4Fish

The pyHeart4Fish has been developed and tested in Windows 10 and 11!
If not done yet download and install python >3.7 on your computer, please! Check ADD TO PATH when asked.

Installation

Download pyHeart4Fish_scripts folder

  1. Download pyHeart4Fish_scripts folder from GitHub/ToReinberger/pyHeart4Fish
  2. Move the complete folder from ./downloads to a desired storage place
    (e.g., C:\Users\\Desktop\pyHeart4Fish_python)
  3. Open command line in Windows (e.g., by typing cmd in Windows search field)
  4. Move to the pyHeart4Fish folder by typing cd C:\Users\<YOUR_USERNAME>\Desktop\pyHeart4Fish_scripts
  5. Install required packages by typing pip install -r requirements.txt

Required python packages:

bug fixes

11-05-2023 1) CziReader from AICSImageIO has been fully replaced with the czifile package > now all image types can be loaded correctly 2) pxiel values of images are now normalied [0 - 255] using cv2.normalize method 3) .feather output per fish was replaced with .csv, as .feather cannot store single line outputs

Tutorial - How to run pyHeart4Fish

Step 1) Run heart_beat_GUI.py script

  1. OR right click on pyHeart4Fish_scripts/pyHeart4Fish_app.py > open with python
  2. OR in Windows console python <YOUR_STORAGE_PATH>/pyHeart4Fish_scripts/pyHeart4Fish_app.py
  3. OR start pyHeart4Fish_app.py in a Python IDE of your choice (e.g., Pycharm, KITE, Notepad++)

This Python script opens the main window of pyHeart4Fish (see Step 2)

Input data types:

Please check experimental requirements before using pyHeart4Fish:


Accepted file formats:

Output data files stored in the results folder:

Test data sets in >Test_data< folder

Test data can be found on OneDrive.
Please unzip data sets before analysis!

Step 2) Select input and output folder and set configurations

Main Window

Input folder: > Contains all movie-files/ images in sub-folders for one project/ experiment
> Choose file folder and click Open Folder
Output folder: > Is automatically created : Input + "_Results"
> Or click Change output to define a desired output folder
> Contains all configuration files, raw data, plots and excel sheets (see above)
Frames per second: > Should be > 15 for optimal results for optimal results,
but 10 f/s can be sufficient
Skip images: > Default 0, (0 - 10 possible)
> 1 = Every second frame is skipped
> Might accelerate the analysis as the number of images is cut in half
> Use only if frame rate is high enough!
Pixel size: > Please check the size of a pixel at your microscope;
in your metadata; or use a scale and ImageJ/Fiji to determine your pixel size [µm]
> A wrong pixel size will give wrong heart size etc.
> Relative values will still apply
Cut movie (sec): > The length of the movie should be at least 10 s
> Ensures that all movies have the same length
File format: > See Input data types
Overwrite data: > If data needs to be re-analyzed
> If unselected all analyzed hearts will be skipped in the project folder
Acquisition mode: > Fluorescence (chamber-specific): Fluorescent heart is required
and 10x magnification is desired
> Bright field (only heartbeat): The script is optimized for bright field movies /series
of frames of whole zebrafish in sagittal position (eyes included)

Start program

By clicking Start, the method StartConfigs.run_program is executed which iteratively
executes heart_beat_GUI_only_one_fish_multiprocessing.py
or heart_beat_GUI_only_one_fish_multiprocessing.py

for each zebrafish and combines all Excel sheets once all zebrafish have been analyzed.

In the bright field acquisition mode, all zebrafish will be analyzed automatically.
This will take a while, e.g., 20 to 30 min for 40 zebrafish depending on the computer performance.

Step 3) Rotate heart for fluorescent acquisition mode

Rotate the heart for chamber-specific fluorescent acquisition mode using the slider to position ventricle
at the top and atrium at the bottom. Click OK to continue.
You can orientate the fish in another direction.
However, the tool will later automatically re-rotate the video for analysis!

Rotate

Step 4) Define atrium and ventricle

To distinguish between background and heart define 1) atrium and 2) ventricle area by Drag-and-Draw. Click OK to start the analysis of all frames / images.
Best results yields a rough selection around respective heart chambers (see image below).
Make sure that the border encloses all parts of the atrium!

define_heart_areas

The first processed image is shown after the complete analysis. Press Yes to show heartbeat curves.

The number of analyzed fish hearts is shown in the top left corner (here: 1/2 analyzed)

progress_bar

show_Excel_sheet

Heartbeat curves

heartbeat_curve

freq: > Frequency / rate of heartbeats derived from fitted sine function (red dotted line)
fft_freq: > Frequency / rate of heartbeats derived from fast fourier transformation (FFT)
phase shift: > Shift between atrium and ventricle sine function
> A very small or very high phase shift can be a sign of arrhythmia / AV-block but 10 f/s can be sufficient
arrhythmia score: > The lower this value, the more regular the heartbeat.
> A value >0.7 is a sign of arrhythmia
av-block score: > The absolute difference of all frequencies (freq and fft_freq) between atrium and ventricle
> A value >0.5 is a sign for a conduction defect or atrial/ ventricle tachycardia or bradycardia

Excel sheet for all heart movies analyzed

Once all fish hearts have been analyzed you can choose to open the summary Excel sheet for all fish

open_excel

Output parameters:

Project_name > Name of the project folder
Condition > File name of of movie / image folder
Number_images > Number of images/ frames analyzed
Heart_size (µm^2) > Size of the heart (atrium + ventricle)
x_distance (µm) > Maximal horizontal distance
y_distance (µm) > Maximal vertical distance
Round_shape > Derived from x_distance-y_distance ratio (1 = round, 0 = stretched)
Atrium/ ventricle maximal dilated or maximal contracted chamber area > Minimal area = contraction; maximal area = dilatation
Atrium/ ventricle relative contractility (%) > Maximal difference in area normalized to maximal chamber area
Atrium/ ventricle ejection fraction (µm^3) > Absolute change in volume (cylinder approximation)
Atrium/ ventricle ejection fraction (µm^3) > Absolute change in volume (cylinder approximation)
Atrium/ ventricle fit_score > Correlation coefficient between raw data and fitted curve (red line)
Atrium/ ventricle Auto_Corr > Auto-Correlation coefficient for raw data
> The higher the value, the more regular the heartbeat
Freq, Freq_fft, phase_shift, arrhythmia score, av_block_score > see above


Heartbeat curve for bright field

heartbeat_curve_BF

Troubleshooting and FAQ

Installation issues

Analysis error

Please contact tobias.reinberger@uni-luebeck.de to report any issues

Licensing

BSD 2-Clause License

Copyright (c) 2022, Tobias Reinberger and Viviana Vedder. All rights reserved.

Cite as V. Vedder and T. Reinberger et al., pyHeart4Fish: Chamber-specific heart phenotype quantification of zebrafish in high-content screens, Front. Cell Dev. Biol. Sec. Molecular and Cellular Pathology , Volume 11 - 2023 | doi: 10.3389/fcell.2023.1143852

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

  1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
  2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.