------------
DESCRIPTION
------------
HPLC-MS (High-Performance Liquid Chromatography-Mass Spectrometry) data is 
usually analyzed using commercial data analysis software. However, such software 
often ties users to a specific workplace and forces them to take illegal actions 
to create more convenient working conditions.

Using Microsoft Excel or other data visualization tools is not effective, either
because the analyzed files contain large volumes of data or because the software
has limitations in terms of graph design and image quality. Additionally, using
Microsoft Excel or related data analysis software can increase risk of data file
corruption due to human error of technical limitations.

To address this issue, a new GUI (Graphical User Interface) has been developed.

ChroMS_GUI is a free graphical user interface designed for the analysis of HPLC
and MS data using files generated by LabSolutions data analysis software. It 
enables users to analyze and visualize 3D HPLC and 2D MS data files and to save 
the generated graphs anytime and anywhere. Also, this tool offers basic graph 
design cusotmization features.

------------
INSTALATION
------------
ChroMS_GUI is compatible with Windows 7 and Windows 10 OS.
Additionally, it is supported on Linux operating systems (tested on Lubuntu
24.04.2 LTS distro).

If you are executing ChroMS_GUI as a Python script:
To ensure functionality of the ChroMS_GUI, make sure that you have
Python version 3.12.4 (for optimal functionality version should be >= 3.7.4) and 
packages with corresponding versions provided in 'requirements.txt' file.

Package versions (while running the code) should be at least:
numpy		1.21.5
matplotlib	3.5.3
tk		8.6.14

If you are using Python 3, tkinter should be already bound to your Python.
Otherwise you can use 'conda install tk' or 'pip install tk' in your 
terminal or cmd to install it.
For other packages you can use:

'conda install matplotlib' or 'pip install matplotlib'
'conda install numpy' or 'pip install numpy'

Download the ChroMS_GUI repository. The code files will be in ChroMS folder.

------------
SETUP AND EXECUTION
------------
Setting up and executing ChroMS_GUI:
x Execution of ChroMS_GUI:
---The provided code should not be modified - there are no user inputs before
   running the code.
   *Except 'DATA_FOLDER_NAMES' in the 'Main_GUI_parameters.py' file. You can
    provide several folder names in the working directory. The list should not
    be empty.
   *You take the responsibility for the errors you made by irresponsible
    behaviour in every .py file in 'ChroMS' folder.

---Default 'Main_GUI_parameters.py' file contents (old data):
   *The following script (no identations):
    TAB_1_NAME = "Blank Page"
    HPLC_TAB_NAME = "HPLC"
    MS_TAB_NAME = "MS"
    DATA_FOLDER_NAMES = ["data"]
    WINDOW_STATE = "zoomed"
    WINDOW_TITLE = "ChroMS_GUI"

---ChroMS_GUI execution possible by several methods:
   *Number 1 (Using terminal):
    -Run 'python ChroMS_application.py' in your terminal that has Python 
     installed.
    -Before that set your current working directory to 
     YOUR_PATH(change this part)/ChroMS_GUI/ChroMS using 'cd' function
    -YOUR_PATH is the path where the ChroMS_GUI project can be found.
   *Number 2 (Writing script in Jupyter notebook or including in other .py file
    that is executed):
    -The following script (no identations):
 
     from ChroMS_application import ChroMS_Application
     import Main_GUI_parameters as mgp
     app = ChroMS_Application(folder_name_list = mgp.DATA_FOLDER_NAMES,
                              window_state = mgp.WINDOW_STATE, window_title = mgp.WINDOW_TITLE)
     app.create_folders()
     app.create_application_body()

   *Number 3 (Number 2 code in .ipynb file):
    -Execute the program by running the code inside 'Notebook_script.ipynb'.

   *Number 4 (Use compiled project version):
    -Execute the program by running its executable file supported on your OS.
     #Windows 7
     #Windows 10
     #Linux
    -On Linux you can create a YOUR_NAME.desktop file to enable more convenient startup.
     Edit this file by adding the following lines (no identations):

     [Desktop Entry]
     Type=Application
     Name=YOUR_PROVIDED_NAME
     Exec=PATH TO THE EXECUTABLE FILE (ENDS WITH:  /ChroMS_GUI_Linux/chroms_gui/chroms_gui)
     Icon=PATH TO THE ICON FILE (ENDS WITH:  /ChroMS_GUI_Linux/chroms_gui/_internal/icons/ChroMS_icon.png)
     Terminal=false
 
------------
USAGE NOTES
------------
x Design / Selecting different tabs:
---The GUI has 3 different tabs inside - "Blank Page", "HPLC" and "MS"
   *Possibility to switch between all of the tabs without any data loss.
   *Every time when "HPLC" or "MS" tab is chosen, listbox widget (with files 
    inside) will take the focus. 
    -If there were any selections in listbox, they will be not changed. 
    -If there were no selections, the first file will be selected (but not 
     activated).
    -If there were no files, there will not be any selections.

x Tabs for HPLC-MS result analysis and their contents:
---"HPLC" and "MS" tabs consists of:
   *File Folder Manager (ffm)
    -Combobox for folder search
    -Button for folder browsing
    -Listbox for file browsing
    -Checkbuttons for file filtering by extension
    -Entry for file filtering by file names or specific pattern
   *Output Plot Manager (opm)
    -Radiobuttons for selecting which subplots to show
    -Text output which shows additional information (errors and etc.)
    -Diagram in which the processed data from the files will be plotted.
   *P.S. There are 2 ffms in the MS tab. They can be chosen by radiobuttons
    below file browsing button. Each provides different ffm which can be used
    to plot data from 2 different files. By default, MS1 files are supposed to
    be positive ionization files, while MS2 should be for negative ionization.
    However, you are completely free to plot any type of MS files in any 
    subplot you like.

File Folder Manager Functionality:
x Folder search:
---There are several different folder search methods:
   *Folder search through filedialog
    -Use Browse button
    -The filedialog default directory for the search is the first directory
     provided in 'FILE_FOLDER_NAMES' in 'Main_GUI_parameters.py' file.
   *Folder search manually
    -Write inside Folder search entry and press ENTER
   *Folder search by selecting item present in combobox
   *Automatic folder search
    -Every time by running ChroMS GUI with browsing history present

---Combobox which contains folder paths, can have up to 10 different items.
   Every time using previously described methods a folder will be selected. 
   During the selection, listbox containing files will be updated and the focus
   will be passed on the listbox.
   *Exceptions:
    -Providing path of non-existing folder. After pressing ENTER the focus will
     remain on the folder browsing entry.
    -Text output will be provided with an error.

---There are possible 3 different files containing folder browsing history for
   different ffms.
   *Types:
    -chrom_history.txt
    -ms1_history.txt
    -ms2_history.txt
   *Each of these files can be modified manually.
   *Non-existing folder paths inside the files are not loaded to the combobox.
   *Paths which were not found will be cleared after the first combobox 
    changes.
   *The latest used path will be at the top of the path list.
    -If there will be to many paths, only the last 10 will be used to update
     combobox.

---Browsing history '.txt' files will be updated every time after changes in
   combobox widget item list.
   *Includes:
    -Every operation which changes order of combobox items.
     #Even if there were no new paths added.
    -Every opperation which adds new paths.
   *Does not include:
    -Loading folder paths during startup.
    -Browsing for non-existing folder.

---Deleting file browsing history.
   *By searching for new folders which will replace the oldest one.
    - Manually or automatically (with Browse button).
    - Manually by deleting history text files.
      #All browsing history will be removed. At the next GUI startup there
       will be clear combobox.

x File browsing:
---There are several functions to navigate between files:
   *Using UP and DOWN arrows. Navigates up or down and executes the files
    immediately.
   *Using ENTER button. Executes currently selected file.
   *Using LEFT-CLICK of mouse. Executes file below the cursor.
   *Using LEFT-CLICK of mouse WITHOUT RELEASING. Goes throug the files
    currently present below the cursor and executes them.
   *Using LEFT and RIGHT arrows. Navigates through files without executing
    them. Useful for fast navigation. For execution use ENTER button.
    #Disadvantage - while using UP and DOWN arrows, the slider position will
     not be changed.

---There are sliders for listbox. You can have as many files as you like.
   However, the lenght of file names should be limited to maintain optimal
   functionality. With the file extension the file name should not be longer 
   than 68 characters. Otherwise, UP and DOWN arrows function will be corrupted
   by horizontal slider.

---During the file execution there will be either success message or warning
   provided in the text output. Also, the diagrams are plotted or not.

x File filtering:
---Filtering files by file extensions (checkbuttons):
   *Default option will be set with predefined file extensions to better
    navigate between different types of files. Different default checkbutton
    values for different ffms:
    -HPLC file		chromatogram_file_name_chrom.txt	(_chrom.txt)	
    -MS1 file		positive_ionization_file_name_ms_+.txt	(_ms_+.txt)	
    -MS2 file		negative_ionization_file_name_ms_-.txt	(_ms_-.txt)
   *You can show all the accessible files in the folder by selecting all
    checkbuttons or by deselecting the first checkbutton (in none of the others
    are selected)
   *Combined use with file filter entry.
   *Every time by checking checkbutton, the listbox contents will be updated.
    Also, the focus will be set on the listbox widget.

---Filtering files by file name (entry):
   *Default option - empty string ("")
   *Case insensitive!
   *Possible filtering by file name. You should provide specific part of the
    file which is present in the current directory.
    -The files can be filtered by writing their extensions inside.
    -You can filter file names by specific fragments of text and connecting
     them with "*" symbol.
     #Example: By writing "test*measurement*2024_*_10" the corresponding
      name would be found - "test_A_measurement_100_2024_10_10".
     #Writing "**" (or n times "*") instead of "*" will not change the 
      filtering result. "*" can also present empty string.
     #By using "*" the separated fragments will be searched in files for
      filtering in ordered manner: "c" will be searched after "b" which comes
      after "a" in the string "a*b*c".
   *Filtering by file name is executed in real-time by writing inside the
    entry.
   *Combined use with checkbuttons of file extension filtering.
   *You can use ENTER button to set the focus on the listbox object.

x Additional functionality in MS ffms:
---Radiobuttons for MS file selection:
   *By pressing them, ffm for specific MS file is selected
   *Because of that you can have 2 comboboxes, 2 listboxes, and 2 sets of file
    filtering features.
   *The latter structures are independent but works almost the same.
    -Exceptions: disabled radiobutton for subplot selection and the subplot
     which is used for drawing.
   *During the startup of ChroMS ffm for MS1 file is shown and ffm for MS2 file
    is hidden
   *While hiding MS1 or MS2 ffm, one of radiobuttons for subplot selection is
    also hidden (Subplot1 or Subplot2 respectively).
    -This behaviour changed by selecting other ffm.
   *If subplot selection radiobutton is set to Subplot1 or Subplot2, activating
    different ffm will change active subplot selection radiobutton and will
    redraw the graph.
    -If Both subplots option is selected then there will not be such changes.
   *Changing ffms also sets the focus on the listbox widget.

---There are several different folder search methods:
   *Folder search through filedialog
    -Use Browse button

Output Plot Manager Functionality:
x Radiobuttons for subplot selection:
---Posibility of selecting specific subplots to draw:
   *Both suplots
   *Subplot1 (HPLC: 'Heatmap', 		MS : 'MS1')
   *Subplot2 (HPLC : 'Chromatogram', 	MS : 'MS2')

---By selecting specific radiobutton the diagram will be redrawn by provided
   option automatically.
   *For one HPLC and one MS ffm both graphs will be drawn if Both subplots
    option is selected.
   *However for HPLC files there are 2 datasets to visualize while in MS files
    there is only one - so only one subplot will be updated with new data.
    Another will be unchanged.
   *You can even plot the diagram which has initial state alone.
   *Using these radiobuttons will set focus on the listbox object.

---The radiobuttons are affected by MS ffm selecting radiobuttons as described
   previously in "Additional functionality in MS ffms".

x Text output for additional information / errors:
---Provides information about:
   *Initial greeting
   *Folder search (success).
   *File execution (success).
   *Errors during folder search or file execution.
    #Disadvantage - no output during diagram redraw while changing MS ffms or
     selecting different subplot selection option.

---There are 3 different types of output:
   *Greeting message is inserted inside two lines of "#" symbols
   *Success message is inserted inside two lines of "+" symbols
   *Warning message is inserted inside two lines of "?" symbols

---The message can contain information about:
   *Consistent output:
    -2 lines of "#" or "+" or "?" symbols
    -Current time (in YYYY/MM/DD hh:mm:ss format)
   *Other outputs are more dynamic:
    -Folder path (if folder browsing was executed)
    -File path (if file was executed)
    -Calculated time for data reading and drawing (3 digits after decimal) (if
     file was executed successfully through selecting option in listbox)
    -Was the event successful or not
   *Sometimes the output can contain only message about error (for example -
    selecting in empty listbox).

---Every time when new lines of output are added to the end of the text, the
   scrollbar of text output widget is slided to the end.

---The text output is modified automatically and cannot be modified manually.

x Diagrams:
---Maximum - 2 subplots, minimum - 1 subplot:
   *Depends on selected radiobutton for subplot selection
   *X-axis between 2 subplots is shared.
   *Labels of X and Y-axes are predefined
    -Y-axis label of HPLC chromatogram is dynamic - changes according to 
     wavelength (cannot observed yet but it will be possible in the future).

---Every diagram has its own state
   *initial - no data drawn, text "Specimen" is shown.
   *not-initial - data is drawn

---Two possible diagram layouts:
   *None. Set when at least one of the subplots does not contain any data.
   *constrained. Set when all subplots has its own data.

---When a file execution error is observed, the graph for corresponding data
   file will be resetted to initial state and replotted.
   *Executed with all layout changes
   *Does not apply on folder search errors.

---Diagrams are interactive
   *Default matplotlib figure and toolbar features (with modifications):
    -Current x and y values are shown in the toolbar
    -Resetting to original view
    -Going back to previous view
    -Going forward to next view
    -Subplot draging
    -Subplot zooming
    -Saving the figure
   *Default feature Configure subplots was ommited because it was incompatible
    with constrained layouts.
   *However, its completelly enough to visualize and analyse HPLC-MS data.

HPLC-MS data file types:
x The correct file types are provided in data folder.
---They should include previously described file extensions:
   *chromatogram_file_name_chrom.txt		(_chrom.txt)	
   *positive_ionization_file_name_ms_+.txt	(_ms_+.txt)	
   *negative_ionization_file_name_ms_-.txt	(_ms_-.txt)

---For optimal functionality of the GUI, the provided file should have the
   following structure of reference lines:
   *For HPLC files:
    -[Header]
    -[File Information]
    -[Sample Information]
    -[Original Files]
    -[File Description]
    -[Configuration]
    -[Peak Table(PDA-Ch1)]
    -[Compound Results(PDA)]
    -[PDA 3D]
   *For MS files:
    -[MS Spectrum]
    -One of two possible lines marking the end of the file:
     #Event	1	(positive ionization)
     #Event	2	(negative ionization)

Additional information:
x There is 'data' (by default) folder in the working directory:
---You can test functionality of the GUI by executing these files.

x The folders 'data' (by default in 'DATA_FOLDER_NAMES' in 
  'Main_GUI_params.py') and 'my_browsing_history' can be deleted:
---They will be recreated during the program runtime.
---Loss of the old information!!!

x There might be some errors unrelated to data processing.
---Loading files or folders which are currently removed.
---Some bugs of data visualization are possible.

------------
AUTHOR
------------
Martynas Jakutis

Contacts:
martynasjk@gmail.com