.. highlight:: rest .. _user-guide: ============ User Guide ============ Guiding the user consists of explaining what can be found through the `web interface `_. At the moment the web interface should speak for itself since it's not terribly complicated but this guide will help if you are having any issues. Left Side Menu -------------- * **CPI Pilot Home** - takes you back to the home page. * **Browse Experiments** - shows you a page of all the experiments stored in the database. * **Development and Documentation** - leads you back here. * **Feedback** - allows feature requests and bug submissions through the source-forge `tracker `_ page. * **Contact** - asks you to email me with your questions. Searching --------- Besides browsing through individual experiments, searching is the only way to find the *entity* you desire. Knowing how it works is essential. .. image:: _static/user-guide/search.png Above the left side menu you will see the search bar. This search is highly flexible and finds any *entity* containing your search string. These *entities* currently include :ref:`Genes `, :ref:`Targets `, :ref:`Reagents `, :ref:`Phenotypes ` and :ref:`Experiments `. The results on the search depend on the number of entities and the number of types of entities found: * if multiple types of entities are found then the number of each type of entity found is shown, and clicking on the entity type yields a list matching the search criteria (as in the the next example). .. image:: _static/user-guide/dea-search.png .. image:: _static/common/greenRA.png :width: 50 .. image:: _static/user-guide/multiple.png click `here `_ to perform this search. * if multiple hits for one type of entity are found then a list matching the search criteria will display. .. image:: _static/user-guide/mad-search.png .. image:: _static/common/greenRA.png :width: 50 .. image:: _static/user-guide/many.png click `here `_ to perform this search. * if only one entity matches the search criteria then the entity page will display. .. image:: _static/user-guide/num-search.png .. image:: _static/common/greenRA.png :width: 50 .. image:: _static/user-guide/one.png click `here `_ to perform this search. Entity pages ------------ .. _gene-page: Gene Page ^^^^^^^^^ this page shows: * all :ref:`phenotype ` hits given by the experimenter for reagents that target transcript sequences of the :ref:`gene `. * all :ref:`transcripts ` of the :ref:`gene ` (currently only those indicated by an experimenter). * all the :ref:`reagents ` that target transcript sequences of the :ref:`gene `. All of the related entities are internally linked (light blue text) and clicking on any one of them will take you to the respective entity page. An example of the gene page is shown below: .. image:: _static/user-guide/gene-page.png .. _target-page: Target Page ^^^^^^^^^^^ this page shows: * the :ref:`gene ` related to the :ref:`target `. * all :ref:`phenotype ` hits given by the experimenter for targeting :ref:`reagents `. * all targeting :ref:`reagents ` and which experimenters claim this relationship. An example of the target page is shown below: .. image:: _static/user-guide/target-page.png .. _reagent-page: Reagent Page ^^^^^^^^^^^^ this page shows: * all the experimental data obtained using this :ref:`reagent `: .. image:: _static/user-guide/reagent-data.png the data source location column contains within it an image of an eye which, if clicked, links to the location's data. * :ref:`phenotype ` hits given by different experimenters for this :ref:`reagent `. * all the transcripts :ref:`transcripts ` targeted by this :ref:`reagent ` and which experimenters claim this relationship. An example of the target page is shown below: .. image:: _static/user-guide/reagent-page.png .. _phenotype-page: Phenotype Page ^^^^^^^^^^^^^^ this page is split into two tabs: The first tab shows: * All the :ref:`genes ` who have one more transcripts targeted by reagents that produce the :ref:`phenotype `. * All the transcripts targeted by reagent that produce the :ref:`phenotype `. An example of this page is shown below: .. image:: _static/user-guide/phenotype-page1.png The second tab shows all :ref:`reagents ` that produce the :ref:`phenotype `. An example of this page is shown below: .. image:: _static/user-guide/phenotype-page2.png .. _gene-phenotype-page: Gene/Phenotype Linkage Page ^^^^^^^^^^^^^^^^^^^^^^^^^^^ for a specific gene and a specific phenotype, this page links to all the raw data that link the gene to the phenotype. This includes which reagent is producing the phenotype and which targets related to the gene those reagents target. An example of this page is shown below: .. image:: _static/user-guide/gene-phenotype-page.png .. _data-page: Data Page ^^^^^^^^^ this page shows the image/movie data extracted from one well. This may or may not be the raw data due to web viewing efficiency concerns. An example of this page is shown below: .. image:: _static/user-guide/data-page.png .. _experiment-page: Experiment Page ^^^^^^^^^^^^^^^ this page shows: * Meta-data associated with the experiment. * A download button used to download all experimental information. More info :ref:`here `. * A list of experimenter defined :ref:`phenotypes `. An example of this page is shown below: .. image:: _static/user-guide/experiment-page.png Common Use Cases ---------------- .. At its current stage, the website supports two main use cases: Browsing by Gene ^^^^^^^^^^^^^^^^ A biologist can immediately check what phenotypes have been found for his gene of interest by searching for the gene using its HGNC symbol, Ensembl Transcript ID or NCBI refseq ID. The :ref:`gene page ` will list the phenotype hits across all experiments and by clicking on the eye image in the phenotype column, a list showing the location of every phenotype hit for the gene in every experiment is displayed. An example of this page is shown below: .. image:: _static/user-guide/linkage.png Browsing through this list by clicking again on the eye but this time in the location column will take the user to the data (images/movies) found extracted during the experiment at that location. This means a biologist has quick an easy access to cellular phenotype hits for his gene of interest and can verify that these hits meet his expectations by reviewing the original data. Browsing by Experiment ^^^^^^^^^^^^^^^^^^^^^^ By either searching for the experiment name or browsing through the experiments listed through the **Browse Experiments** link located on the sidebar, a user might be able to locate an experiment that is of interest to him. The :ref:`experiment page ` of interest will show a list of phenotypes. Clicking on a phenotype will take the user to the :ref:`phenotype page `, and from there it is possible to get to example experimental data by clicking on the eye image twice (on the phenotype page and on the following page). If a user is satisfied with the quality/relevance of the data then he can download all the raw data for that experiment for re-analysis (see :ref:`downloading-an-experiment`). Browsing by Other Entities ^^^^^^^^^^^^^^^^^^^^^^^^^^ Although infrequent, a user may want to find the genes/transcripts said to be targeted by a certain reagent. Browsing by phenotype can also be an option. .. _downloading-an-experiment: Downloading Experimental Data ----------------------------- On the :ref:`experiment page `, clicking on the "Download All Experiment Data" initiates a single zip file download which, when unzipped, will contains three sub folders: * **/export** - contains files in an :ref:`intermediate ` .csv format used when either exporting from or importing data to the database. * **/original** - contains the flat files originally submitted by the experimenter (everything except the raw data). * **/raw** - contains a text file with instructions on downloading all the raw data (normally many GBs worth) and resuming disconnected downloads At the moment a terminal/command line program called *wget* is used to do this. *wget* is very slow as in this application it goes through HTTP and a meeting is being setup with systems to discuss other transfer possibilities. * wget should be installed on all Unix machines. * wget can be obtained for mac OS X systems by downloading and installing mac-ports (google "mac-ports") then typing in "sudo port install wget" at the terminal. * wget can be also be downloaded and installed for windows (google "windows wget"). Once downloaded, the raw files will be stored in the hierarchy that they were when they were originally submitted by the experimenter. The file location can be retrieved from the **data.csv** file in the **/export** folder given the experimental location.