rhythmidia 0.4.1

Race tube image analysis and period elucidation in Python.

Rhythmidia

Race tube image analysis for circadian period elucidation in Python.

---

Installation and Program Launch

1. Rhythmidia must be installed in a Python environment running Python 3.11 or higher using pip. Rhythmidia runs on Unix-like operating systems including macOS and Linux. In order to install Rhythmidia, simply run the command:

pip install rhythmidia

2. To run Rhythmidia run the command

rhythmidia

NOTE: The terminal window used to launch Rhythmidia must remain open while the program is in use.

---

Rhythmidia Right Out of the Box

1. The first time you open a new installation of the program, you will be prompted to select a working directory. From this directory, the program will, by default, look for race tube images, and will by default, save data
   a. This can be changed later at any time
   b. You are not restricted to using this directory, it is purely for your convenience
   c. This is where analysis data will be exported by default
   
2. That’s it! You can start analyzing images immediately.
   NOTE: On some newer Mac laptops with variable-force-click trackpads, you may find that some clicks are not picked up effectively unless you click with full force.

---

Preprocessing of Race Tube Images

1. Crop your scanned race tube image as desired, in the image viewer program of choice, leaving a small amount of background on either long edge
2. No need to make your image greyscale, fix its rotation, or increase contrast- Rhythmidia will take care of all of this internally!
3. Race tube images can be .png, .tif, .tiff, .jpg, .jpeg, or .svg

---

Uploading and Analyzing an Image

1. Upon opening the software, you will be greeted with the “Home” tab, which will look like this:

NOTE:If you want to add tubes to an existing experiment file, go to File -> Open experiment File (or press ⌘O), although this is not necessary 2. To upload a new race tube image, click the button labeled “Upload Race Tube Image”

a. Your image will appear in the center of the screen
b. Uploading an image enables the options to rotate and to lock & analyze your image
3. Rotate your image so that the growth direction of the tubes is from left to right across your screen
a. To rotate your image 90 degrees clockwise, click the button labeled “Rotate”
4. If necessary, update the Time Sheet table to correspond to the times at which you marked your race tubes, located to the left of the image box a. Time Sheet entries are in days:hours:minutes, starting at 0:00:00 at the first time mark b. Entries past the greatest number of identified time marks in a single tube will be ignored, so there is no need to address them 4. When you are satisfied with your image’s orientation, click the button labeled “Lock & Analyze Image” 5. Rhythmidia will try to identify horizontal lines corresponding to the horizontal boundaries of the tubes in your image, including the lower and upper bounds below and above the final and first tubes a. One line between each two tubes

6. You will be directed to verify these lines:
a. To remove an incorrect line, simply click on the line
b. To add a missing line, simply click in an unoccupied position on the image
7. When you are satisfied with the positions of all tube demarcation lines, click the button labeled “Proceed” 8. Repeat steps 6-8 for time marks (red) and for bands (orange)

NOTE: At any time before saving tubes to the file, you may click the button labeled “Cancel image analysis”, which will reset the image analysis process and remove your uploaded image, while leaving open any open experiment file
NOTE: Be certain to record any differences in marking times in the mark sheet (left) before proceeding further. If tubes were marked at the same time every day, leave as the default setting (0 for all)
NOTE: The time marks will temporarily disappear while marking conidial peaks. 9. After you are satisfied with the positions of the bands and click “Proceed”, you will be able to see a preliminary calculation of the period of each tube below
NOTE: if there is an issue at this stage (i.e. a missed or duplicated identifier) cancel image analysis and reload the image

10. You will now have the option to click the button labeled “Save Tubes to File”
a. This will bring up a popup asking for a name for the pack of tubes in the current image before it saves them to file

b. If you are working within an existing experiment file, this will simply add this pack to the file and update it
c. Otherwise, you will be prompted to Save As a new experiment file for these tubes

The Experiment Tab

1. Whether opening an existing experiment file or working from a new pack image, granular experiment data, plots, and statistical analysis data are located on the Experiment tab

2. Experiment data (Entry, Pack, Tube # in pack, Period calculated 3 ways, and Growth rate) is located in the table in the top left

3. In the top right is the frame for statistical analysis of any number of tubes:

a. Select packs, tubes, and a method of period analysis in the 3 lists
b. To select multiple packs or tubes, use control-click
c. Click the button labeled “Analyze” to generate mean period, standard deviation, and standard error
d. Click the button labeled “Export Data” to export a .csv of the data for each tube selected
e. Click the button labeled “Export Analysis” to export a .csv of the analysis of the selected tubes
4. In the bottom half is the plot frame for plotting densitometry and a periodogram of a single tube:

a. Select pack, tube, and type of periodogram in the 3 lists
b. Click the button labeled “Plot” to generate a densitometry plot and periodogram of the selected data
c. Click the button labeled “Save Plot” to save an image of the dual plot in file format of choice
d. Click the button labeled “Save Densitometry” to save a .csv of the densitometry data
e. Click the button labeled “Save Periodogrammetry” to save a .csv of the periodogrammetry data
5. At the bottom left is a button labeled "Display Pack Image" a. This button will display a popup window containing the greyscale version of the image corresponding to whichever pack is selected in the bottom left list that was the exact image used for analysis

Functions Overview

Open Experiment File (⌘O)
Close Experiment File (⌘C)
Save File (⌘S)
Save as… (↑⌘S)
Set working directory (⌘D)
Open graphics preferences (⌘P)

---

Changelog

v0.4.1: Corrected major bugs in implementation of time-windowed analysis. Corrected minor bugs in graphics options.

v0.3.1: Added further experimental features for bulk data handling. Minor updates to documentation.

v0.3.0: Made minor changes to allow for analysis of 'free-run' experiments. Minor bugfixes. Added functionality to remove band markers from plots. Added experimental functionality to save all plots from an experiment file at once.

v0.2.4: Constrained calculation of Sokolove-Bushell period to a reasonable range.

v0.2.1: Fixed a failure to save experiment files introduced by a change in a dependency. NOT backwards compatible with experiment files generated pre-v0.2.1.

v0.1.1: Changed calculation of growth rate to scale with dynamic time windows. Minor bugfix re: dynamic time window selection UI. Temporarily removed "Edit Packs" feature pending improvements. NOT backwards compatible with experiment files generated pre-v0.1.1.

v0.0.5 - V0.0.13: Documentation update to display images in PyPI documentation.

V0.0.2 - V0.0.4: Documentation update to create readthedocs files.

V0.0.1: First public, stable release concurrent with upload to PyPI.

---

Copyright

Copyright (c) 2024, Pelham Lab - Washington University School of Medicine

Acknowledgements

Project based on the Computational Molecular Science Python Cookiecutter version 1.1.

Logo adapted from a DALL·E-generated image.