--- mount: /examples/03-data-overlay-upload/ name: Example 3 Custom data upload by registered users --- [Back to the "Overlays" in user manual](/user/visualisation/) [Back to the example list](/examples/index/) # Example 3 - Overlay data upload by registered users You will find here examples of data upload by registered users, for basic and advanced overlays. ## Basic format The file in basic format has two tab-separated columns **Name** and **Value** (see also [Upload user-provided overlay data](/user/visualisation/#user-provided-overlays)): - **Name** - names of elements to be coloured. - **Value** - a value from \[-1, 1\] range, to be transformed to red-blue colouring, with negative values coloured red, positive coloured blue; the saturation of the colour will be defined by the absolute value. ::: info-box [Note]{.box-header} Blue (for negative values) and red (for positive values) are configured [[in the admin panel (Overlays)]{.color-primary}](/adman/configuration/) and can differ between MINERVA instances. ::: [Click here to download **the basic overlay**](files/ex03/basic-overlay.txt), containing a custom colouring for [an example map](files/map_example.xml). To upload this dataset, do the following: 1. Make sure you have the privileges to generate overlays in the example map. - Go to **Projects** tab and **Edit** the example map. - In the **Users** tab, check the box in the **View project** column. 2. Open the example map from the **Projects** tab by clicking on its name (default: **map\_example**). 3. Make sure that you are logged in by checking the **Info** tab in the left panel. 4. In **Overlays > User-provided overlays** section - Choose **Add overlay** then press **Choose File**. - Select **basic overlay** file to upload. 5. In **Overlays > User-provided overlays** tab, click **View** checkbox to examine generated view. Examine the generated colouring and the uploaded dataset. Please see image below and note that: - All SNCA elements are coloured to the same colour because of by-name matching. - SNCA elements are red-coloured (the value in the file is -0.5). - PRKN is blue (the value in the file is 0.75) ![03\_basic\_format.png](../images/example-images/03_basic_format.png) ## Advanced format Advanced format foresees two parts of the uploaded dataset - header and body (see also [Upload user-provided overlay data](/user/visualisation/#user-provided-overlays)). The header lines start with `#`. It contains the following elements: - `#VERSION=xyz` - a version of this custom layout - `#NAME=xyz` - a name that will be automatically assigned upon upload - `#DESCRIPTION=xyz` - a description that will be automatically assigned upon upload The body is a table with [the following set of columns](/user/generic-overlays/). **Warning!** Colouring of the elements in different compartments works ONLY for separate (not nested) compartments. Setting a colour for elements in a compartment that encloses other compartments does not set the colour inside the nested compartments. ### By-identifier colouring [Click here to download **the advanced overlay (generic)**](files/ex03/advanced-overlay.txt), containing a custom colouring for an [example map](files/map_example.xml). Upload this dataset as in [basic format upload](#basic-format). Examine the generated colouring and the uploaded dataset. Please see image below and note that: - elements are coloured by their identifiers instead of their names, - SNCA elements in the *nucleus* elements are coloured red, *synapse* elements are coloured blue due to by-compartment colouring. - Phenotype UPS is not coloured as the smallest compartment UPS is contained in is *synapse*, not *cell*. ::: danger-box [Warning!]{.box-header} Colouring compartments works only for separate (not nested) compartments. For example: setting the colour for SNCA identifier in the *cell* compartment will not colour the contents of the nucleus and synapse. ::: Using SNCA colouring by-name overrides by-identifier colouring, the order of selection is as follows: - match by-name - match by-identifier - constrain by-compartment ![03\_adv\_format.png](../images/example-images/03_adv_format.png) ## Custom colors and interaction colouring User-defined colors can be assigned to both elements and interactions, using the hex code (e.g. #fffaaa). [Click here to download **the interactions overlay**](files/ex03/advanced-interactions-overlay.txt), containing a custom colouring for [**the example map**](files/map_example.xml). Upload this dataset as described above in [basic format upload](#basic-format). Examine the generated colouring and the uploaded dataset. Please see image below and note that: - **color** column replaces **value** for defining colours of interactions and elements; both parameters cannot be used simultaneously. - reaction id provided in **element\_identifier** it is not constraint by **compartment** (as more than one compartment can contain reactions line). ![03\_custom\_format.png](../images/example-images/03_custom_format.png) ### Remarks - The uploaded dataset must be a **text file**. - Column **Name** refers to the full name in the annotation panel; e.g., HGNC gene name for genes/proteins; ChEBI name for simple molecules or GO name for a Gene Ontology term. - Identifiers of the elements in the dataset have to follow the MIRIAM standard; e.g., HGNC: *11138*; Ensembl: *ENSG00000184845*; ChEBI: *CHEBI:18243*. - Most columns can be used simultaneously. If the same element is addressed in two different columns, it will be coloured with these two colors. - Restrictions: - Either a value or a color columns is necessary in the uploaded dataset, but they mutually exclusive. - Reactions to be coloured should be identified only by reaction id or PubMed. - If the **compartment** column is used, it is highly recommended to fill all its fields with a compartments name from the map. Element which does not have defined compartment will be coloured in the whole map. ::: info-box [Alternatively]{.box-header} You can also export a diagram of interest as a CellDesigner file, open it in CellDesigner and colour it there. :::