rqi14 / phasescan Goto Github PK

1. SYSTEM REQUIREMENTS
The software has been tested on Windows 10 (64 bit) only, but it should be able to run on Linux and Mac OS.
Python 3.8.2 (64 bit) with the following packages:
wheel>=0.35.1
ipython>=7.18.1
commentjson>=0.9.0
matplotlib>=3.3.2
numpy>=1.19.2
opencv-python>=4.4.0.42
openpyxl>=3.0.5
pandas>=1.1.2
Pillow>=7.2.0
scikit-learn>=0.23.2
scipy>=1.5.2
six>=1.15.0
xlrd>=1.2.0
Cython>=0.29.21
opencv-rolling-ball>=1.0.1
scikit-image>=0.18.1
ipympl>=0.6.3
plotly==5.3.1

2. INSTALLATION GUIDE
Run `pip install -r requirements.txt` to install packages
Typical installation time should be less than 5 minutes

3. DEMO
a. Instructions to run on data
Please unzip the example data as well as the code (PhaseDiagram OO for submission).
Change the path at line 28 in noarg_executer.py to the sa_params.jsonc of your unzipped demo data.
Run noarg_executer.py with Python.
Windows will pop up for selecting the calibration samples.
Please select the regions that correspond to the concentration specified in the window title, according to the instruction in the console.

b. Expected output
A output folder named "Output_" should be created in the demo data directory.
Inside there is a combined_df.xlsx spreadsheet file that contains all the analysed results.
The information can be interpreted using the following notes.
Column				Meaning
img_num				number of image that the droplet belongs to.
local index			The index of droplet inside the image
radius				Radius of droplets in px
x				x coordinate of droplet in px
y				y coordinate of droplet in px
dark				Boolean value stating if the droplet is below dark threshold
feature				True: phase separated, False: mixed
uneven				Boolean value stating if the droplet looks uneven (faulty). True: droplet is problematic, False: normal.
signal_0_pv			signal intensity per px volume for channel 0 (in the order stated in parameters)
signal_0_sum			signal intensity of the whole droplet for channel 0 (in the order stated in parameters)
signal_1_pv			signal intensity per px volume for channel 1 (in the order stated in parameters)
signal_1_sum			signal intensity of the whole droplet for channel 1 (in the order stated in parameters)
signal_0_pv_cvt			concentration of species in channel 0. Generated by the cvt step
signal_1_pv_cvt			concentration of species in channel 1. Generated by the cvt step

Channel index follows the order specified in "channels" of the sa_params.jsonc file.

c. Expected run time for demo on a "normal" desktop computer
Typical run time should be less than 15 minutes.

4. INSTRUCTIONS FOR USE
How to run the software on your data.
1. Arrange your data files and directory to a way that is similar to the demo.
2. Make a copy of the sa_params.jsonc file to the directory of your data.
3. Change the parameters inside sa_params.jsonc according to the insturction inside
4. Rename the calibration files to include device height and sample concentrations according to the following:
Two types of data structure supported.
Type 1: separated capillary images
The images should be named as [Channel name]_[Concentration].[Format], e.g. 488_0.1.tif
If the background images were taken for individual capillary image, they should be named as follows.
The background images should be named as [Channel name]_[Concentration]_bkg.[Format], .e.g 488_0.1_bkg.tif
If background images for individual capillary do no exist, it automatically uses the background image specified in the
config file.
In this mode, the ROI must be selected for each of the images.
If you want to ignore some images, simply move them out of the folder, or rename them in a way that will not be detected
Type 2: combined PDMS images (PDMS device with multiple channels)
The images should be named as follows:
[Channel name]_[Concentration1]_[Concentration2]..._[Concentrationn]_some-extra-info_h[Height of device].[Format]
Note: h[Height of device] is optional for this type of images. If this does not exist, it will automatically use the
height specified in the config file.
Note2: A known issue in name matching is that after the last concentration there must be an underscore. For example,
488_5_0.tif won't work and 488_5_0_.tif will. This is important when no height is specified and no extra info provided
In this mode, if there is some concentration that does not exist, simply press ESC or close the window to skip it.