==============================
Graphical User Interface (GUI)
==============================

FAUST has a basic graphical user interface (GUI) that will allow you to run FAUST without interacting with the API. 


The GUI can be started on the command line with the commands:

::

    faust gui

Note that this GUI will depend on the following additional dependencies

::

    matplotlib
    PySide6

Once you start the GUI, you will see a screen that looks like this: 

.. figure:: images/FaustScreenshot1.png
   :alt: FAUST GUI screenshot

Now you will have to load counts data. The FAUST GUI expects data to be in the format generated by `PoolQ <https://portals.broadinstitute.org/gpp/public/software/poolq>`_, which
is the typical output format you would receive your data if they were processed by the Broad Institute Gene Perturbation Platform (GPP). The relevant folder is usually the "ibar-counts" folder,
which will contain separate counts matrices for each distinct ibar, or UMI. Each count matrix will be a tab-delimited file with each row representing a distinct guide, and columns representing 
the counts for that guide (having the UMI corresponding to the file) in a particular sample.  


.. figure:: images/FaustScreenshot2.png
   :alt: FAUST GUI screenshot 2

Once you've done that, that top button will change color. Now, select your ".chip" file, which contains all the relevant metadata of your screen. Click the button that says "Select corresponding .chip file", and select the file with the screen metadata. 

.. figure:: images/FaustScreenshot3.png
   :alt: FAUST GUI screenshot 3

In the third button from the top, select the column of the .chip file that corresponds to the gene symbol you wish to use. Each entry with that gene symbol will be regarded as a single experimental class, to be compared with a control class (to be specified shortly).  In this case, you would usually select the column that specifies the gene that is targeted by each guide, but you could in principle study each guide individually (in the case that you have multiple guides that target a single gene, but want to separately analyze their effects; if you simply analyze by genetic targets, you might not notice if one gRNA behaves aberrantly relative to others targeting the same gene). 

.. figure:: images/FaustScreenshot4.png
   :alt: FAUST GUI screenshot 4

Now select the input type.  This can be either "single" or "matched." "Single" mode corresponds to a single input that applies to all samples (e.g., a pre-adoptive transfer aliquot).  "Matched" mode applies when each relevant output has a distinct input (e.g., when you want to compare matched lymph nodes and tumors). 

.. figure:: images/FaustScreenshot5.png
   :alt: FAUST GUI screenshot 5

Now, select the inputs.  In "single" mode, you can add these one by one, or as a selected group. Before you also select outputs, you'll see the "Comparisons" column populate with a "?" as a placeholder output. Once you add an output, you'll see a correct comparison populate the "Comparisons" column. In "matched" mode, add the matched input and output, and they will populate the "Comparisons" column. You can also select multiple inputs and outputs at a time in "matched" mode, but take care that the order you select the columns (by default from top to bottom if selecting a contiguous block of inputs or outputs) is the order that there are matched, and if the number of outputs exceeds the number of inputs (respectively, inputs and outputs), the excess will not be included in any comparison. When in doubt, simply add in individual input/output pairs one at a time. When you are done with this step, check the "Comparisons" column to ensure that the comparisons you are running are the intended ones. 

.. figure:: images/FaustScreenshot6.png
   :alt: FAUST GUI screenshot 6 

Now select your controls.  You can drag to select a larger group at once. 

.. figure:: images/FaustScreenshot7.png
   :alt: FAUST GUI screenshot 7

Now click "Run FAUST." You will be prompted to write a file name to save the output (can be .xlsx, .csv, .tsv, or .txt format). A progress bar will indicate progress for the calculation. When that is complete, you can plot a swarm/violin plot of top results by clicking "Plot top hits," or you can open the raw data (the .xlsx, .csv, .tsv, or .txt file from before) and explore it using the program of your choice.