Package: pyGUS-bio
pyGUSQuick startDownloadthe package,
unzip, and then double-clickpyGUS.exeorpyGUS.ORMake sure you havePython(3.8 or higher) installed.Open terminal, run# Install, using pip (recommended)
pip install pyGUS_bio --user
# Or, use conda
conda install -c wpwupingwp pyGUS_bio
# Run
# Windows
python -m pyGUS
# Linux and MacOS
python3 -m pyGUSTable of ContentsQuick startFeaturePrerequisiteHardwareSoftwareInstallationPortableInstall with pipUsageDesktopCommand linePhoto tipsInputOutputUtilitiesextract_info.pystats.pyPerformanceCitationFlowchartFeature:heavy_check_mark: Quantify GUS expression in stain images for multiple species.:heavy_check_mark: Identify expressed regions and no expressed regions.:heavy_check_mark: Use negative and positive references to calibrate expression
value.:heavy_check_mark: Support Macbeth color checker to calibrate color bias.PrerequisiteHardwareThe program could run in normal computers and have no extra requirements for
memory, CPU, et al.Currently, macOS, Linux and Microsoft Windows systems are supported.SoftwareFor the portable version, nothing needs to be installed manually.For installing from pip,Pythonis
required. Notice that the python version should be3.8or higher.:white_check_mark: All third-party dependencies will be automatically
installed with the Internet, includingopencv-contrib-python,numpy,scipy,matplotlib,coloredlogs(python packages).InstallationPortableDownload from thelink,
unpack and run.Install with pipInstallPython.3.8 or neweris
required.Open the command line, runpip3 install pyGUS_bio --userUsageDesktopIf installed with pip,# Windows
python -m pyGUS
# Linux and MacOS
python3 -m pyGUSIf you use the portable version, double-click thepyGUS.exe. Then click the
button to choose which mode to run.Command line:exclamation: In Linux and macOS, Python2 ispythonand Python3 ispython3. However, in Windows, Python3 is calledpython, too. Please
notice the difference and make sure you usePython 3instead ofPython 2.Show help information# Windows
python -m pyGUS -h 
# Linux and MacOS
python3 -m pyGUS -hRun# Windows#   mode 1python-mpyGUS-mode1-ref1[file1]-ref2[file2]-images[files3] [file4]...#   mode 2python-mpyGUS-mode2-ref1[file1]-images[file2] [file3]...#   mode 3python-mpyGUS-mode3-ref1[file1]-ref2[file2]-images[files3] [file4]...#   mode 4python-mpyGUS-mode4-images[file1] [file2]...# Linux and macOS#   mode 1python3-mpyGUS-mode1-ref1[file1]-ref2[file2]-images[files3] [file4]...#   mode 2python3-mpyGUS-mode2-ref1[file1]-images[file2] [file3]...#   mode 3python3-mpyGUS-mode3-ref1[file1]-ref2[file2]-images[files3] [file4]...#   mode 4python3-mpyGUS-mode4-images[file1] [file2]...InputAll images should use white background.Negative referenceOne plant (whole or partial) with low expression or no expression.Positive referenceOne plant (whole or partial) with high expression.Target imagesPlant images for  analysis.Photo tipsThese tips are for better results, not strict rules.EquipmentCameras and stereo microscopes are recommended. Smartphones with camera
functions are not recommended, especially models with built-in color grading.
To reduce the effects of perspective distortion, lens with medium focal length
(e.g. 50 mm in full-frame) is recommended. Make sure lens and camera sensor
are free of stains.BackgroundWhiteboard orwhitepaper with no debris, no wrinkles, no obvious
reflectionLightingIt is recommended to use the bottom lighting of the whiteboard. When
using indoor lighting, the international standard color rendering index (Ra
index) of the bulb is required to be no less than 85, and the color
temperature is between 4000 k to 7000 k; when using sunlight, avoid morning
and evening. Close overhead lighting can cause significant reflections and is
not recommendedFocusThe whole subject is not out of focus. Narrow down the aperture when
shooting with a camera; adjust focus and magnification when using a stereo
microscope to ensure that the edges of the subject are sharpWhite balanceThe recommended color temperature is around 6500k, with a
minimum of 4000k and a maximum of 7000k. When the color temperature cannot be
adjusted, adjust other parameters until the background is displayed in white
without obvious color cast.Exposure compensationWhen using camera, the exposure compensation can be set
to +1EV or +2EV to reduce the color cast of the paper. It could also reduce
the influence of the transmittance of color cards or plantsLayoutBased on the size of the plant, adjust the lens-to-plant distance to make the
plant cover the frame more than 50%. The main body does not cross the border,
and the distance is not less than 10% of the screen width.When there is only a single subject, place it in the center of the frame. When
two subjects (two plants or plants with color card), place them on the left
and the right, with interval between them not less than one-third of the width
of the plant. They do not intersect, and they are not surrounded by each other
(especially one with the long roots); there is no breakage, and the leaves do
not overlap as much as possible.FileNo toning processing. The recommended minimum resolution is 500*500 px. When
shooting with the camera, vignetting and distortion compensation can be turned
on, and other adjustments (including white point, black point, contrast,
brightness, style, etc.) should be turned off.ModeNormal modeThenormal moderequiresnegative reference(-ref1),positive reference(-ref2) and target images (-images, one or more). Each image only have one
object.This mode requires users to add marks on the image:left click mouse to addwhitedots on the target plantright click mouse to finish or pressEscto reset dotsdrag to draw a boxaroundthe target plant. Do not cross over the plant.
Do not draw near the border of the image, too.right click mouse to finish or pressEscto reset the boxWith reference modeThewith reference moderequires one reference image (-ref1) withnegative
reference on left and positive reference on right. In each target images
(-images, one or more), target plants are on left, positive references are on
right separately.This mode requires users to add marks on the image:left click mouse to addwhitedots on the target plant and the reference.right click mouse to finish or pressEscto reset dotsdrag to draw a boxaroundthe target plant and the reference. Do not cross
over the plant. Do not draw near the border of the image, too.right click mouse to finish or pressEscto reset the boxWith color checker modeThewith color checker moderequiresnegative reference(-ref1),positive reference(-ref2) and target images (-images, one or more).
In each image, the plant is on left and a Macbetch color checker is on right.This mode requires users to add marks on the image:left click mouse to addwhitedots on the target plant and the color
checker.right click mouse to finish or pressEscto reset dotsdrag to draw a boxaroundthe target plant and the color checker. Do not
cross over the plant. Do not draw near the border of the image, too.right click mouse to finish or pressEscto reset the boxManually modeTheManually moderequires one or more target images (-images). Users select
two references and target regions by mouse and press any key to continue to next
image or to start running.Output.csvfiles:csvformat table. Storage all analysis results.-masked.pngfiles: Original image with alpha channel. Background is set to
fully transparent, expressed regions are set to fully opaque.-select.pngfiles: In mode 4, the selected regions were filled with different
color.Redrepresents negative reference,yellowis for positive reference,
andcyanis for the target region.-calibrate.pngfiles: Images calibrated with color checker.-fill.pngfiles: Images filled with different colors.Bluemeans target,redmeans background,yellowmeans regions inner target but have different expression,greenmeans darker regions
inner target.Utilitiesextract_info.pyThis program can extract the alpha channel information stored in the image
output by pyGUS and generate a black and white image. Among them, black
represents the background part of the original image recognized by pyGUS, gray
represents the plant part, and white represents the part with GUS signal
recognized by the program.Usage:# Windowspythonextract_info.py[image filename]# Linux and macOSpython3extract_info.py[image filename]stats.pyThis program is used to statistically analyze the difference in GUS signals
between different groups of sample photos and perform significance test (t-test).
Considering that users may prefer different statistical tools, this program is
an auxiliary tool and is not integrated into the pyGUS. The program requires the
user to provide a CSV format (exportable from Microsoft Excel, Notepad or any
other text editor) list as input, with the following format:Filename3,Sample1,Group1
Filename4,Sample2,Group1
Filename5,Sample3,Group2
Filename6,Sample4,Group2Filenamerepresents filename of pyGUS input images,Sample1represents
sample ID andGroup1represents the group of samples. Sample IDs should be
unique.Note that please do not contain comma or space in each column. For example:A1.png,A1,control
A2.png,A2,control
A3.png,A3,control
B1.png,B1,treatment
B2.png,B2,treatment
B3.png,B3,treatmentUsage:# Windowspythonstats.py[filename]# Linux and macOSpython3stats.py[filename]#>PerformanceIt depends on hardware and image size. Normally one image cost seconds or no
more than one minute. The program could detect and utilize multi cores of CPU.CitationUnpublished.LicenseThe software itself is licensed underAGPL-3.0(not include third-party software).Q&APlease submit your questions in theIssuepage :smiley:Q: I got the error message that I don't havetkintermodule installed.A: If you want to run GUI on Linux or macOS, this error may happen because the
Python you used did not include tkinter as default package (kind of weird). Run# Debian and Ubuntu
sudo apt install python3-tk
# CentOS
sudo yum install python3-tkmay help.For macOS users or linux users without root privilege, please try to install the
newest version of Python or to use conda, seecondaandPythonfor details.Q: It says my input is invalid, but I'm sure it's OK!A: Please check your files' path and filename. Thespaceor Chinese
characters in the folder name or filename may cause this error.Flowchartflowchart TB
    subgraph Input
        m1((Normal mode))
        m2((With reference mode))
        m3((With color checker mode))
        m4((Manually mode))
        targets[Target images]
        c[Macbeth Color checker]
        ref1[Positive reference]
        ref2[Negative reference]
        ref3[Negative and Positive reference]
        targets
        ref1 & ref2 & targets --> m1
        ref3 & targets --> m2
        m3 --> c --> ref1 & ref2 & targets
        m4 --> ref1 & ref2 & targets
        style c fill:#399
        style m1 fill:#393
        style m2 fill:#393
        style m3 fill:#393
        style m4 fill:#393
    endflowchart LR
    subgraph Process
        g1[Read image]
        g1.5[[Color calibration]]
        g2[Split to R, G, B channels]
        g3[Generate gray copy]
        g4[Get edge]
        g7[Calculate]
        g8[Output table and figure]
        g1 --> g1.5 --> g2 --> g3 --> g4 --> g7 --> g8 
        style g1.5 fill:#59f
        style g7 fill:#557788
        style g8 fill:#59f
    end
    subgraph g1.5[Color calibration]
        direction TB
        c1[Detect Macbeth color checker]
        c2[Generate CCM matrix]
        c3[Apply matrix to original whole image]
        c4[Generate calibrated image]
        c1 --> c2 --> c3 --> c4
    end
    subgraph g4[Get mask]
        direction LR
        g41[cfm] --> g42[binary] --> g43[split]
    end
    subgraph g7[Calculate]
        direction LR
        neg & pos --> target --- Mean & Area & Ratio
    end