ESPERANTO User Guide
- 1. Aim
- 2. Guiding Principles
- 3. Cornerstone files
- 4. Getting Started
- 5. Workflow Interface Layout
- 6. Initialisation windows
- 7. Loading windows
- 8. GLP Mode
- 9. Structure Homogenisation
- 10. Session Management
- 11. Download Report
- 12. More Info
- 13. Tabs: Phenodata
- 14. Tabs: Vocabulary
- 15. Tabs: Updated Vocabulary
- 16. Tabs: Updated Phenodata
- 17. Tabs: Procedures/GLP
- 18. Tabs: Plotting Tool
- 19. Tabs: Multiple Integration Tool Check
At the same time, each operation is recorded, resulting in a detailed report about the entire curation of the processed dataset. Besides, the generated reports ensure the reproducibility of the curation of the processed dataset.
To strengthen its GLP compliance and reduce the impact of human subjectivity, this manual wants also to guide the user about specific considerations he/she may face during the curation. To make their identification easier, they are provided in italics.
Despite the starting version of the vocabulary being empty, each round of curation gives the opportunity to enrich the dictionary with new terms.
For reference, here are indicated the version of the used dependencies.
magrittr 2.0.3
dplyr 1.0.10
data.table 1.14.4
zeallot 0.1.0
collections 0.3.6
reshape2 1.4.4
tibble 3.1.8
shinyWidgets 0.7.4
stringr 1.4.1
readxl 1.4.1
DT 0.26
xlsx 0.6.5
tidyverse 1.3.2
shinycssloaders 1.0.0
kableExtra 1.3.4
knitr 1.40
plotly 4.10.1
shiny 1.7.3
shinyjs 2.1.0
shinyBS 0.61.1
shinyalert 3.0.0
shinyFeedback 0.4.0
shinydashboard 0.7.2
rhandsontable 0.3.8
If needed, you can download and install Docker by following the instructions at Get-Docker.
ESPERANTO Dockerfile is available here.
Once downloaded, open the terminal, select the folder containing the Docker image and launch it:
bash ./run_esperanto.sh
Open the browser and add the following line in the URL-bar.
localhost:3838
The input files to upload must be placed in the same folder where the Dockerfile is located.
cran_pkgs <- c("magrittr", "dplyr", "data.table", "zeallot", "collections", "reshape2", "tibble", "shinyWidgets",
"stringr", "readxl", "DT", "xlsx", "tidyverse", "shinycssloaders", "kableExtra", "knitr", "plotly",
"shiny", "shinyjs", "shinyBS", "shinyalert", "shinyFeedback", "shinydashboard", "rhandsontable")
cran_pkgs.inst <- cran_pkgs[!(cran_pkgs %in% rownames(installed.packages()))]
if(length(cran_pkgs.inst)>0){
print(paste0("Missing ", length(cran_pkgs.inst), " CRAN Packages:"))
for(pkg in cran_pkgs.inst){
print(paste0("Installing Package:'", pkg, "'..."))
install.packages(pkg, repo="http://cran.rstudio.org", dependencies=TRUE)
print("Installed!!!")
}
}
remove.packages(”rJava”)
If the error holds after the update/install of Java, it is probably originated by rJava and Java using different versions (i.e 32 vs 64 bits). In this case, the solution is to install the same Java version and update manually the Java path with the new Java version: i.e, version jre1.8.0_121 (64-bits).
Sys.setenv(JAVA_HOME='C:/Program Files/Java/jre1.8.0_121')
# Clone the git repository
git clone https://github.com/fhaive/esperanto ESPERANTOclone
# Start R session, set the folder where the clone was stored and run by using runApp()
setwd("./ESPERANTOclone")
library(shiny)
runApp(".")
Return to the index
For this reason, each variable is highlighted with a different color depending on whether the column needs (
It is possible to “Browse” multiple datasets to “Open” and “Import”. Once uploaded, a table listing the imported datasets and their entry size is displayed in the lower part of the popup window (Fig. 11). It is possible to inspect the content of each of them by simply clicking on the name of the dataset.
“Open Integration Support” closes the popup window and takes the user to the tab panel “Multiple Integration Tool Check” (par. 19). “Open Integration Support” also generates a unique sha-256 ID based on R package digest. This ID will be added to each file name, current session and to any report created, resulting in linking everything together in a univocal fashion.
Then, “Browse” the folders to retrieve, “Open” and “Import” the latest updated version of the reference vocabulary (Fig. 13).
2022-11-19_16-03-22_dataset_name_current_session.RData
Once clicked the “Open” button and the full progression of the uploading bar, it is possible to finally restore the session by pressing the “Load” button. A notification in the lower right corner informs the user about the success of the procedure.
At the same time, consistently with the restored session, sidebar buttons may change color becoming green and data may be displayed in the main "display area" (par. 5).
GLP mode should be enabled if the user wishes to enclose in the curation report not only the series of operations, but also the reasons motivating the actions performed to harmonise the metadata.
In order to speed the "Content Homogenisation" phase up as much as possible, the user should proceed along the list of operations, performing "Relabelling" and "Duplicate Removal" first.
Once one of the proposals is selected, the whole column is automatically shown below, allowing the user to evaluate the content and a conscious choice between “Accept” or “Reject” the suggestion (Fig. 18). As the action is selected, the procedural track in the lower right corner is filled with a dynamic message describing the performed operation. The button “**Add**”, encloses the message as a new step in the general report listing all performed operations ([par. 17](#17), “Procedures/GLP”).
Regardless of the type of operation, each click of the “Undo” button allows the user to undo the last operation. At the same time, a message characterised by “UNDO” tag is printed at screen (Fig. 19) and it is reported to the list of actions performed on the dataset downloadable in section “Procedures/GLP” (par. 17).
Due to the automatic nature of the retrieval during “Relabelling”, it is preferable to run this section before the “Duplicate Removal” and above all on the “Content Homogenisation” phase, where the user is actively involved not only in supervision but also in the modification of the entries.
As in par. 9.1, regardless of the type of the operation, each click of the “Undo” button allows the user to undo the last performed action. Each of them will be printed at screen (Fig. 21) and will also be included in the “Procedures/GLP” report par. 17 and highlighted by an “UNDO” tag at the beginning of the message.
This section is particularly important in case of GEO metadata. In fact, they often present identical columns with different column names, or where the content differs for a starting word related to the type of content (see the table in Fig. 20).
The considerations did in the “Relabelling” section still holds and provides a consistent renaming of the columns for the following evaluation of potential duplicates. At the end, the user should consider duplicate removal as a powerful way to simplify and accelerate the “Content Homogenisation” step through a direct recoding of the entries by the user.
At first, on the top of Fig. 22, the current column name is shown in an box editable from the user (“Recoded column name”).
Right below, there is a dropdown menu enlisting a recoding map structured according to the following pattern:
The association between each unique column content (“Current_content”) and “Suggestion” is determined by the cross-comparison between dataset and vocabulary. It is equal to:
- Reference content of the vocabulary if it matches the current content;
- Reference content of the vocabulary if current content is identical to one of the reference content´s synonyms;
- Current content, if cross comparison returns no hits.
Once one of the entries of recoding-map is selected, the correspondent “suggestion” is shown in “Recoded unique content”, where it is freely editable.
The colours around the boxes “Recoded column name” and “Recoded unique content” work as hint for the user. They follow the same principle of the recoding map, where the label/content currently selected can match a vocabulary reference label/content (
Just below the recoding boxes, there are a vocabulary consultation panel and a barplot, described in more detail in par. 9.3.1.1 and 9.3.1.2.
As in par. 9.1 and 9.2, regardless of the type of operation, each click of the “Undo” button allows the user to restore the last operation. Each of them will be printed at screen and will also be included in the performed actions report (par. 17, “Procedures/GLP”) and highlighted by an “UNDO” tag at the beginning of the message.
At the bottom of the page, it is possible to decide the type of action to perform on the selected data, such as “Delete”, “Modify and/or Save”, “Specials”. A “Next” button leads to a second Content Homogenisation window.
Alternatively, the box remains in the configuration shown in Fig. 22 and the user can self-search labels and contents.
By pressing “Ok”, a new popup window displays a descriptive message recorded to the “Procedures/GLP” final report once clicked “Add” (Fig. 28).
The "Undo" button nullifies the previous operation, prints at screen a message and records the action on the procedural track (Fig. 29).
It is important to notice that the content color can differ from the one in the previous window. There, a red content means a newly edited reference content for that specific reference label; here in the current window, if the edited content appears green, it implies the content is already present in the vocabulary as reference content. Despite being confusing at a first glance, it invites the user to pay attention to the consistency of the editing. The same dualism may occur with labels.
The two buttons identify the type of action to perform. “Save” allows the user to recode label and content with their edited versions; “Skip full column recoding” if the user wants to use the edited label but confirm the whole column content.
It is possible to conclude that differences in colour aim to get user´s attention for a double check. When colours match, they just supports the choices of the user.
Green leads directly to the next step.
Blue means that the editing job should be refined: the user should return to the previous window, eventually consult the vocabulary to identify the reference value of the blue one and edit it in the correspondent “Recoded unique label (or content)” box(es).
If consciously edited, the red suggests that it is probably useful to store one or both edited and original label(s) and/or content(s) in a sort of pre-vocabulary structure (more details in par. 9.3.3.2). The user should be careful to understand if the red is due to the “new-term-status” or to some mistake, or wrong allocation (i.e. missing identification of the correct label/content to allocate the new term in).
As mentioned before, the "Undo" button restore the phenodata state to the previous operation. A message is displayed and recorded.
This sub-panel determines whether the user wants to store the original label and/or content versions.
The two boxes in the first row automatically show the original version of the edited label/content. The radiobuttons below determine how to store the original value: “as Label Synonym”, “Do not store” (equivalent options are available for contents). Please note that the edited versions are automatically taken as reference values.
The panel design changes according to “Save” or “Skip full column recoding” selection. The former is shown in par. 9.3.3.1, the latter is here in Fig. 32. In fact, despite the selection of “Skip full column recoding”, the user may want to store one or more original contents through the checkbox. Only in this specific case, the user should be aware that the selected contents are allocated as reference entries and not as synonyms(“as Reference Content” substitutes “as Content Synonym”.
The selection made in this panel also determines the type of message shown in the “Procedural track” box below. “Store” button will store the label and/or content.
It is of extreme importance to maintain the consistency of the vocabulary. For this reason, the user is requested to authorise the incorporation of new terms in another section of ESPERANTO, “Updated Vocabulary” (par. 15). The current section builds a temporary pre-vocabulary structure, later used as input in “Updated Vocabulary” section.
If the user is aware that the original values are already present in the vocabulary, it is preferable to “Do not store” them. In this case, the lower amount of combinations of words will shorten the time required for the analysis of the temporary pre-vocabulary structure.
Generally speaking, the first two lines of the message report edited/confirmed label and content. In case of skipping the full column recoding, here are indicated the number of contents temporarily stored, leaving their explicit citation to the following lines. The last two lines describe if and how the original dataset column name and content were stored in the pre-vocabulary structure.
.
Since the splitting is targeted on a specific pattern, the button “Test” allows to verify the correct separation of the string. If it is correct, “Save” adds the newly generated columns into the phenodata. Otherwise, it is possible to “Reset” the simulated splitting test table on the right of the window.
As "Save" is clicked, the “Procedural Track” box displays the message reporting the outcome of the operation, while "Add" records it into the final procedural report (par. 17).
As the “Add” button on the right is clicked, the “Procedural track” frame shows the related message. As mentioned for any other “Procedural track” box, its “Add” button records the message to the final report in “Procedures/GLP” section.
. This window allows to split the content of the selected column by means of a “Separator” or a “Regular expression”. On the left a link opens a popup window with some info about the splitting methods.
If “Separator” is selected, the user is required to choose the type of separator to use as splitter. There are some predefined, but in alternative the user can highlight “Other” and write a new separator in the newly-appeared box right next to "Type of Separator" menu.
The user can accept to name the new columns by ticking the correspondent checkbox and supplying the new column names separated only by comma. If “Regular Expression” is selected, the correspondent regular expression must be entered, together with the new column names (always separated only by comma). The regular expression section is build on regex parameter of function extract of R package tidyr: so it is important to provide the regular expression according to the rules of "extract" function.
For both splitting methods, “Test” button allows to verify the correct separation of the string. If the splitting is correct, “Save” the newly generated columns are added to the phenodata. Otherwise, it is possible to “Reset” the simulated test table on the right of the window.
Below the buttons, there are two tables, showing on the left the selected column and on the right the columns resulting from the splitting.
The procedural track and its “Add” button, works like the equivalent in other sections of ESPERANTO, showing and recording a message describing the operation performed.
.
The option based on separator is more suitable for simple splitting, while regular expression offers more complex solutions.
.
Due to the higher complexity, the user has the possibility to test if the set regular expression works properly before effectively modify the data and save the result.
Despite of the stability of the software, it is advised to save the session relatively often. The files do not only allow to rebuild the progress of the curation, but they offer also a fully working backup if needed.
Once "Reset Session" is clicked (Fig. 37), the popup window shown in Fig. 38 is launched. It notifies the user the risk of proceeding further by pressing button "Reset".
In alternative, every single report can be downloaded in the corresponding section of ESPERANTO.
In the middle of Fig. 41, it is possible to see 2 rows of boxes, for the majority initially red.
The first row identifies the file/reports that are always present in that specific working mode and are those above the blue line in the table. The main report summarises the whole process, by synthesizing the features of the starting files, the type and number of performed operations. It reports the unique sha-256 ID, the name of all Curators and Arbiters judging the entries which will generate the files in the second row. Also, the first rows of these latter files will be enlisted, together with the procedural track. The ID will be added to any downloaded file name to supply them a univocal link. The second row depends not only on the working mode, but also on the outcomes of the analysis. If one of the boxes is grey, it means that no entries were allocated there and no file will be downloaded. More details about the type of files will be given in the next paragraphs (par. 15 for single- and par. 19 for multiple-mode).
By clicking “Download All” button on the left corner, a cascade download is triggered, turning the red boxes into green as the progress bars complete, as shown in Fig. 42. “Reset Windows Setting” allows the user to stop the download and reset the parameters as soon as the current partial download is over.
This tab is active only when the “Type of Metadata” (par. 6.3) is set on “Single” and it requires the upload of a reference vocabulary.
This section is structured similarly to “Multiple Integration Tool Check” (par. 19) using also a similar color-code to guide the user through the evaluation of the candidates temporarily stored during the recoding phase (in par. 9.3.3.2).
“Load new terms suggestions” processes and categorises the entries according to the loaded vocabulary. The cross-comparison assesses whether the paired candidates are already present in the reference vocabulary. In case of a positive result, the word is color-coded in ${\color{green}green}$, ${\color{red}red}$ otherwise.
The hit-map generated by those allocations originates the three categories “Safe”, “Fast check” and “Slow check” enlisted in the “Potential outcomes” dropdown menu (Fig. 46). If one is missing, no entries were allocated.
Once one of the categories is selected, a table enlisting the color-coded candidates appears. This table just shows the reference labels (and their synonyms if present) and reference contents (with their synonyms if present), hiding the rest of the information related on how the user wanted to store the original label/content par. 9.3.3.2), which will be later used to generate the updated version of the vocabulary.
Entry appears red because of:
- being new (i.e. a word the user never encountered and evaluated before for enrichment)
- being inconsistent with the vocabulary reference values due to the nature of the entry (i.e. same content but they refer to different labels)
- being inconsistent with the vocabulary reference values due to minor issues (i.e. character mismatch).
As one of the rows is selected, a small box opens above the table, “Correspondent entry retrieved from the dictionary” (Fig. 49). It shows the outcome of the search in the reference vocabulary of the candidate label, so that the user can see the current state in the vocabulary of that specific label, its contents and all their synonyms.
The user evaluates candidate table rows one by one, judging whether it must be “Accepted” (Store Entry), “Discarded” (Discard) or re-curated (Issue) (Fig. 50).
Besides par. 11, also in this section it is possible to download the single reports, providing a synthesis about the categorisation of the different entries (Fig. 50).
In collaboration with the procedural track, these reports ensure the reproducibility of the decisions regarding the entry allocation process during the recoding phase.
For example, here are shown two rows of the “Store Entry” report.
| ID | Label Storing | Label | Label Syn. | Content Storing | Content | Content Syn. | Decision | Curator | Arbiter |
|---|---|---|---|---|---|---|---|---|---|
| 5 | 2 | organism | 4 | homo_sapiens | Accepted | SimoI | SimoI | ||
| 30 | 2 | disease | 3 | healthy_control | control | Newly Accepted | SimoI | SimoI |
ID identifies the operation number.
Referring to the table above, the numbers in “Label-” and “Content storing” encode how the entry was allocated in the intermediate temporary vocabulary. In the “Vocabulary Enrichment” panel, for example the user could choose to store the original value “as Synonym” or “Do not store”. For Label, these options were coded by “1” and “2”, while for Content “3” and “4”. This stands also in the case of “Skip full column recoding” described in par. 9.3.3.1. Recalling it shortly, the user may wish to recode only the label and skip modification of the contents. In the case where one or more of those pristine contents is of interest for vocabulary enrichment, the user can select “as Reference Content” which is also coded as “3” and requires the “Procedural track” support to distinguish from the “as Synonym Content” case.
Tags listed in Decision can be “Accepted”, “Newly Accepted”, “Issue” or “Discard”. They are self-explicative, but the distinction between “Accepted” and “Newly Accepted” lies on the fact that the first (row 1, “Safe” category) presents values already in the vocabulary, while the second has at least one new term for potentially updating the vocabulary.
For documentation purposes, each entry is enriched with the name of the “Curator” and also of the appraiser as “Arbiter” of the decision.
Once all the entries have been evaluated, the user can “Generate Updated Vocabulary” and download the updated version.
The consistency of the vocabulary is fundamental for the correct functioning of ESPERANTO. Hence, the user should be extremely careful in evaluating which new terms incorporate in the reference vocabulary. This “vocabulary curation” is an occasion to review the curation of the processed dataset, identifying potential errors and inconsistencies.
If the “GLP mode” was active (par. 8), each recorded action is followed by the tag "COMMENT:" and the related compulsory justification provided by the user during the curation.
Procedural track report is downloadable not only in par. 11, but also through the button “Download” in the current window. It is revealed only if the report version printed at screen is the most recent. Otherwise, the updating is ensured by clicking the “Update to Download” button (Fig. 51).
Once selected whether the plot would be based on a single or on multiple datasets, the variable can be associated to Abscissa, Ordinate or Grouping Condition (Fig. 53).
The user should also characterise the type of plot (“Stacked”, “Grouped” or regarding grouping “No condition”). It can also be useful to specify if the ordinate axis should be in percentage, and if the legend should be included; at last, the user can enter axis and legend labels (Fig. 54).
Once all settings are specified, the button “Plot” originates the correspondent image (Fig. 55). This is achieved by plotly package, so different actions can be performed on the image by using the plotly self-hiding command bar above the picture (i.e. zooming, downloading).
The user should be aware that despite the personalisation, this section was mostly designed to ensure a quick way to examine data and not necessarily plot an image ready for publishing.
This tab is active only when the “Type of Metadata” (par. 6.3) is set on “Multiple” and it requires the upload of a reference vocabulary.
The metadata table is cross-compared to the vocabulary to assess whether the entries of the first are consistent with the reference vocabulary values. In case of a positive result, the word is shown in ${\color{green}green}$, ${\color{red}red}$ otherwise.
The results of this “consistency map” are also the base for the “Potential outcomes” dropdown menu: “Safe”, “Fast check”, “Slow check” (Fig. 56). If one is absent, there were no entries allocated.
If the user had previously curated the single datasets now integrated together, he/she had enriched the reference vocabulary by making a certain number of new entries available and evaluating their inclusion.
If this was done, the red entry may be due to:
- an inconsistency with the vocabulary reference values due to the nature of the entry;
- an inconsistency with the vocabulary reference values due to minor issues (i.e. character mismatch);
- the type of entry (i.e. a word the user did not want to include in the vocabulary for some reason).
If the vocabulary enrichment was not done, the user should upload the saved session of the correspondent single dataframe and perform it.
For all the reasons discussed above, the user should be extremely careful in processing the entries of this category, which explains the name (“Slow check”) and the red color.
Once selected the “Potential Outcome”, the labels of the columns included in the chosen category are listed on the left. By clicking one of them, on the right, the corresponding content is shown. All entries are color coded in agreement with the “consistency map” mentioned above in this paragraph.
The user can evaluate the entry and classify it as “Consistent” or “Issue”, ensuring in the latter case a report the user can use as a guide to retrieve the critical entries in the correspondent dataset and fix them. For documentation purposes, ESPERANTO stores as “Arbiter” of the classification the user identity. The lists of the entries allocated in the two categories can also be downloaded with the download buttons at the bottom of the window.
The message describing the decision is automatically shown in the “Procedural Track” box and appended to the “Procedures/GLP” report (par. 17) through “Add”. The example of messages in case of entry classified as "Consistent" (Fig. 59) or "Issue" (Fig. 60)are shown here.
As for previous sections, it is possible to undo the classification of the entry by pressing the "Undo" button. By undoing the operation, a message similar to the one in Fig. 61 is printed at screen and recorded in the "Procedural Track".
The user should be extremely careful in this step. It finalises all the work done during the single dataset curation sessions for each dataset loaded in the multiple mode, but also the incorporation of the new reference and synonyms entries in the vocabulary. For these reasons, even if this step may sound redundant, it is an occasion to verify the consistency of the previous work and easily correct potential mistakes. The tool just supports the user in the whole process and automatises what is possible, but the user must examine all entries with full attention to ensure the consistency in merging multiple datasets.