GUI software written in Julia to analyze drop freezing spectra from ice nucleation cold-stage measurements.
This is a Julia language implementation of the Drop-Freezing-Detection MATLAB code. The goals for the rewrite was as follows:
- Removal of the need to purchase a MATLAB license to run the code
- Application of a proper GUI toolkit
- Significant speedup of the data processing
- Exposition of hyper parameters through the GUI
- Improved tracking of meta data without the need to edit code files
- Storage of results using a non-proprietary data format
- Faster validation of results through graphical groupings
This work was supported by grant NSF AGS-2112978.
Below are generic instruction assuming that you have access to a regular terminal. Scroll to the end of this page for MS Windows specific notes
Download the software and extract the files. Alternatively, clone the directory using git
[user@host ~]$ git clone https://github.com/CIF-Cold-Stage/DropFreezingDetection.jl.gitThe software is written in the Julia language. It should work on all platforms. The GUI toolkit is Gtk, which works best under Linux. To install, download the current stable release https://julialang.org/downloads/ and install it on your computer.
Using a terminal emulator, navigate to the directory DropFreezingDetection/src and start julia with the project flag.
[user@host ~]$ cd DropFreezingDetection/src
[user@host src]$ julia --project _
_ _ _(_)_ | Documentation: https://docs.julialang.org
(_) | (_) (_) |
_ _ _| |_ __ _ | Type "?" for help, "]?" for Pkg help.
| | | | | | |/ _` | |
| | |_| | | | (_| | | Version 1.7.2 (2022-02-06)
_/ |\__'_|_|_|\__'_| | Official https://julialang.org/ release
|__/ |
julia> Next use the closing square bracket ] followed by enter to start the package manager.
julia> ] <PRESS RETURN>
pkg>Next instantiate the project using the instantiate command. This will download all of the required dependencies. This step only needs to be performed once.
pkg> instantiateTo return to the Julia REPL hit the delete key.
pkg> <PRESS DELETE>
julia>To exit Julia press .
julia> <PRESS CTRL-d>
[user@host src]$To run the program from the shell run the following command:
[user@host src]$ julia --project main.jl
Step 0: Welcome. Please use the GUI to enter the metadata
The first time this will be slow due to the just in time compiler. Using a custom system image explained further below will address this. After a short while the following greeter will pop up.
Select a folder with drop images. For example exampledata/level 1/Experiment 1
In addition, fill out the metadata, including the operator, cooling rate, drop volume, and sample tag. Use the calendar to set the date of sample collection.
Press Next after filling up the metadata. Now the software will parse the image and guess the location of each drop in the image.
[user@host src]$ julia --project main.jl
Step 0: Welcome. Please use the GUI to enter the metadata
Step 1: Calculating drop centers. Please be patient.The following screen will appear.
Each red circle corresponds to an identified drop. Some drops are missing a circle, some drops have two or more circles.
Click on a drop to manually add circles as needed. Toggle the switch on the top left of the header bar to off. Now clicks will remove the nearest neighbor circle. Remove all doublets (two in this image). If you remove too many circles, toggle and add them back in. You do not need to mark all circles. Removing a circle will effectively ignore the drop in the subsequent processing.
The figure to the right shows the identified edges. Depending on the image contrast, illumination, and droplet size, this edge detection may be insufficient, leading to too many edges and lots of false positive drop detection. The spin button with the value 25 is a hyper parameter that sets the spatial scale in the edge detection algorithm. You can change the value and press Recalculate Edges to try to improve the center detection. If it performs poorly, you can also press Delete All and then add all drops manually.
Press Next when you are happy with the drop centers. Now the software will load and tile all images, and transform the data into a stack. It will then search through the stack and identify freeze events.
[user@host src]$ julia --project main.jl
Step 0: Welcome. Please use the GUI to enter the metadata
Step 1: Calculating drop centers. Please be patient.
Step 2: Loading and tiling files. A progress bar will appear shortly.
Progress: 100%|█████████████████████████████████████████| Time: 0:00:46
Step 3: Searching for freeze events.
Progress: 100%|█████████████████████████████████████████| Time: 0:00:01The following validation window will appear
The freeze detection tries to identify changes in the image that correspond to freezing (indicated by opaque drop). The triplets correspond to an image sequence with suspected freezing. The droplet should turn from clear to opaque either in the second or third image. Sometimes the freeze detection is an error. For example the second triplet in the left most column. These can be manually removed as false positives. Click twice on the triplet to remove it.
A white line will appear and indicate that the drop is removed. Note that the first click has no effect and you will need to click twice.
If a triplet is accidentally removed, it can be undone by switching the toggle button in the header bar and clicking on the triplet once more.
Not all drops fit on a single page. Use the spin button on the top right to toggle through all drops.
Press Finished. Next the software will create a quick look and write processed data and metadata to the exampledata/level 2/Experiment 1/ folder.
The quicklook shows INP/L water (left) and activated fraction (right). The image is written to the level 2 folder. Also written is a .csv file with drop centers and freezing temperature, a .csv file with the activated fraction and INP concentration vs. temperature, as well as image files that indicate the selected drops, drop centers, accepted drops, and discarded drops.
Press Close to exit the program.
Running the raw version of the software has some small but noticeable just-in-time compilation lag. To eliminate the lag, run the following. This only needs to be done once.
[user@host src]$ julia --projectjulia> include("make_sysimg.jl")The software will run as described above. Perform a normal processing, e.g. using one of the example data sets. This will write a file with precompile instructions. At the end the PackageCompiler will create a machine dependent custom system image that can be invoked at startup. This will take several minutes.
[ Info: PackageCompiler: Executing /home/petters/Documents/Research/NSF-AGS-2112978 (CIF)/DropFreezingDetection.jl/src/main.jl => /tmp/jl_packagecompiler_YaHfa4/jl_O37nT8
Step 1: Calculating drop centers. Please be patient.
Step 2: Loading and tiling files. A progress bar will appear shortly.
Progress: 100%|█████████████████████████████████████████| Time: 0:00:46
Step 3: Searching for freeze events.
Progress: 100%|█████████████████████████████████████████| Time: 0:00:01
[ Info: PackageCompiler: Done
✔ [05m:59s] PackageCompiler: compiling incremental system imageAfter a system image is created, the software can be started as follows
[user@host src]$ julia --project --sysimage sys_daq.so main.jlThe software works just fine on MS Windows. However, terminal support on Windows is not that great. It is recommended to install git bash for Windows: https://git-scm.com/downloads
Download the current stable release for Windows from https://julialang.org/downloads/ and install it on your computer.
Run the git bash and clone the directory. In the example below it will be cloned into the Documents folder.
$ cd Documents/
$ git clone https://github.com/CIF-Cold-Stage/DropFreezingDetection.jl.gitChange into the directory and invoke the Julia executable. You will need to adjust the path for your user name and Julia version.
$ cd Documents/DropFreezingDetection/src/
$ 'C:\Users\Markus Petters\AppData\Local\Programs\Julia-1.6.5\bin\julia.exe' --projectThe program can now be invoked using
julia> include("main.jl") and otherwise executed as described above. The system image can also be compiled as described above
julia> include("make_sysimg.jl") 
The optimized installation can be called via
$ cd Documents/DropFreezingDetection/src/
$ 'C:\Users\Markus Petters\AppData\Local\Programs\Julia-1.6.5\bin\julia.exe' --sysimage sys_daq.so --project main.jl