Update README.md for v2.7 GUI

FabbriniMarco · Sep 27, 2024 · 5bbfb89 · 5bbfb89
1 parent a3b1d22
commit 5bbfb89
Showing 1 changed file with 77 additions and 21 deletions.
diff --git a/README.md b/README.md
@@ -1,25 +1,85 @@
-# Generate MiSeq Manifest
+<div align=center>
+  <img width="196" alt="Circle logo" src="https://github.com/user-attachments/assets/4e9887af-3bd1-4a20-bfa6-dd3f73f04da6" height="186">
+</div>
+
+# Generate-MiSeq-Manifest
 Quickly produce a .csv manifest file to import samples into Illumina MiSeq machine for the sequencing run, starting from 96-well plates of samples with matched index codes
 
+### Warning: This script works only with Illumina Nextera XT Index v2 (sets A,B,C and D)  
+
+If you are unsure about the index sequence you are using, consult the manufacturer of your library prep kits and check the ```index_database.tsv```.  
+
+<br>
+
+
+## Table of contents
+1. [GUI program portables](#gui-program-portables)
+   - [Windows 10/11 users](#windows-users)
+   - [MacOS users](#macos-users)
+2. [Run the GUI from command line](#run-the-gui-from-cli-windows-macos-linux)
+3. [Run the legacy Rscript](#run-the-legacy-rscript)
+   - [Requirements](#requirements)
+   - [Download the script and the required files](#download-the-script-and-the-required-files)
+   - [Legacy CLI execution for Linux and MacOS](#legacy-cli-execution-for-linux-and-macos)
+   - [Legacy CLI execution for Windows 10/11](#legacy-cli-execution-for-windows)
+   - [Additional details for the legacy CLI](#additional-details-for-the-legacy-cli)
+4. [Citation](#citation)
+
 <br>
 <br>
 
-  ## Warning: This script works only with Illumina Nextera XT Index v2 (sets A,B,C and D)  
-
-  Before using the script consider looking at the _index_database.tsv_ file to check whether your indexes are included.  
-
+
+# GUI program portables
+## Windows users
+[Download the ```.exe``` executable](https://github.com/FabbriniMarco/Generate-MiSeq-Manifest/releases/download/v2.7/GenerateMiSeqManifest.exe) in the Release section of this repo.
+Simply double click the executable. You will get a warning as the executable file is not signed, but you can proceed and a GUI as follows will appear:
+
+<div align=center>
+  <img width="396" alt="GUI example" src="https://github.com/user-attachments/assets/6da3fe5e-50e7-4028-9008-df54e9b28522" height="360">
+</div>
+
+You can click the ```Get Example Plate File``` button at the bottom and point a place where to save the EXAMPLE_PLATES.xlsx file. This is a template excel file with the plates, that you can fiill in accordingly to the samples and plates you have prepared, sticking to the template.
+After compiling the text box fields ```Project Name```, ```Project Date``` in YEAR-MONTH-DAY format and ```Number of Plates``` you have to provide the excel file in the prompt that opens when clicking the ```Select Excel File``` and you're good to go! Just press the ```Generate Manifest``` and specify an output directory where to save your sample sheet for the sequencing run.
+
+<br>
+
+## MacOS users
+MacOS users can [download the ```.app```](https://github.com/FabbriniMarco/Generate-MiSeq-Manifest/releases/download/v2.7/GenerateMiSeqManifest-MacOS-arm.zip) in the ZIP archive in the Release section of this repo. The program shouuld work on MacOS with ARM processors (M!, M2, M3) but has not been tested. Please raise any Issue through the Issue section of this repo.
+<br> Alternatively MacOS user can run the .py script from the Terminal (see next section).
+***
+
 <br>
 <br>
 
-## Requirements:
-The script requires R to be installed (look at the [Comprehensive R Archive Network](https://cran.r-project.org/) if you don't have R installed)  
+# Run the GUI from CLI (Windows, MacOS, Linux):
+The script requires a valid ```python``` installation as well as several dependancies libraries. Then, clone this repo and launch the python script locally.
+
+```bash
+pip install pandas tk ttkbootstrap
+
+git clone https://github.com/FabbriniMarco/Generate-MiSeq-Manifest
+
+cd Generate-MiSeq-Manifest
+
+python ./GenerateMiSeqManifest.py
+```
+***
+
+<br>
+<br>
+
+
+# Run the legacy Rscript
+If you want to run the legacy Rscript you can. It has been moved inside the  [Legacy R Script](https://github.com/FabbriniMarco/Generate-MiSeq-Manifest/tree/main/Legacy%20R%20script) folder of this repo. <br>
+
+## Requirements
+The legacy version of this script requires R to be installed (look at the [Comprehensive R Archive Network](https://cran.r-project.org/) if you don't have R installed)  
 The readxl package is required. It can be installed automatically during the first run of the script or manually running the following line of code in R/RStudio:  
 
 ```R
 install.packages("readxl")
 ```
 
-<br>
 <br>
 
 ## Download the script and the required files  
@@ -31,18 +91,17 @@ In order to download the files in this repository you can open your Terminal on
 Or you can click on the green "Code" button on top of this page and select the "Download ZIP" option;  
 Or you can download the release .zip file from the [Releases](https://github.com/FabbriniMarco/Generate-MiSeq-Manifest/releases) section
 
-<br>
 <br>
 
-## Tutorial for Linux and MacOS:  
+## Legacy CLI execution for Linux and MacOS  
 
 Open your Terminal app and head to the folder containing this script and the plates for the run, using the "cd" command, for example:  
 
 ```Bash
 cd /User/myusername/Downloads/Generate_MiSeq_CSV-2.7
 ```
 
-If you don't know your PATH you can also type "cd " and drag-and-drop the folder from the Finder/FileExplorer inside the terminal.
+If you don't know your PATH you can also type ```cd ``` and drag-and-drop the folder from the Finder/FileExplorer inside the terminal.
 
 Paste this in your Terminal, changing the parameters accordingly  
 ```Bash
@@ -55,10 +114,9 @@ You need to change the number "4" - the one between the date and the excel file
 You need to change the "EXAMPLE_PLATES.xlsx" excel file with the plates accordingly to the samples and plates you have prepared, sticking to the template  
 
 <br>
-<br>
 
 
-## Tutorial for Windows 10 and Windows 11:
+## Legacy CLI execution for Windows
 Open your Terminal app or Windows PowerShell by searching for "Terminal" or "Powershell" in your Start menu.  
 If you have problem finding your terminal, you cen press the keys Win+R and a "Execute" window sill pop out in the bottom-left screen. Type "powershell" and hit Enter.  
 Now head to the folder containing the script and the plates for the run, using the "cd" command. Remember to use single quotes for the path. For example:  
@@ -83,11 +141,9 @@ You need to change the number "4" - the one between the date and the excel file
 You need to change the "EXAMPLE_PLATES.xlsx" excel file with the plates accordingly to the samples and plates you have prepared, sticking to the template  
 
 
-<br>
 <br>
 
-
-## Additional details:
+## Additional details for the legacy CLI
 
 * Items meaning:
   * 1st argument contains the index database supplied
@@ -103,18 +159,18 @@ You need to change the "EXAMPLE_PLATES.xlsx" excel file with the plates accordin
   * Column names and row names MUST contain index codes (N- in the columns, S- in the rows) OR 'empty'
   * The inner part of the table must contain sample's name. Avoid name starting with numbers or containing special characters
   * In case of an empty cell you MUST fill the cell with the term: _**empty**_
-
+***
 
 <br>
 <br>
 
-## Cite this tool if you want:  
-
-
+***
+## Citation
+If you use this tool please cite: <br>
 
 ```
 @Manual{,
-  title = {Generate MiSeq Manifest: Quickly produce a .csv manifest file to import samples into Illumina MiSeq machine},
+  title = {Generate-MiSeq-Manifest: Quickly produce a .csv manifest file to import samples into Illumina MiSeq machine},
   author = {Marco Fabbrini},
   year = {2023},
   note = {version 2.7},