fjson jpg

vignettes/manipulate_term_match_table.md

@@ -0,0 +1,190 @@
+Structure
+---------
+
+The term matching table contains links to the information needed to
+create the output table. Some general term matching tables can be
+created by the function `create_term_matching_table()` by specifying the
+used instruments and the origin key.
+
+This function falls back on the included list of data frames `tmt_list`
+where each table is designed to fit one instrument. By calling the
+function with only one instrument name it will just extract the specific
+data frame. If called with more than one instrument (ordinarily 2) it
+will bind the tables together.
+
+    tmt_LC_pump <- create_term_match_table(
+      instrument_list = c("Thermo EASY-nLC"))
+      # no origin key set
+
+The table always consists of 6 columns whose order is important. The
+count of rows differ depending on the choosen requirements and the type
+of instrument.
+
+    colnames(tmt_LC_pump)
+    #> [1] "term"         "term_verbose" "origin"       "handle_type" 
+    #> [5] "handle"       "example"
+
+The first column of the resulting table is always the `term`. It is a
+short and unique description of the row. While the second,
+`term_verbose` contains a more detailed and readable title.
+
+    head(tmt_LC_pump[1:2])
+    #>                term
+    #> 1   hplc_instrument
+    #> 2       hplc_vendor
+    #> 3        hplc_model
+    #> 4       hplc_column
+    #> 5 hplc_mobilephases
+    #> 6 hplc_samplevolume
+    #>                                               term_verbose
+    #> 1 High Performance Liquid Chromatography (HPLC) Instrument
+    #> 2                                              HPLC Vendor
+    #> 3                                               HPLC Model
+    #> 4                                    Chromatography Column
+    #> 5                             Chromatography Mobile Phases
+    #> 6                                   Injected Sample Volume
+
+The third collumn `origin` contains keys determining which requirements
+to satisfy. These keys were read in the function
+`create_term_matching_table()` and compared to the value of
+`origin_key`.
+
+    head(tmt_LC_pump[3])
+    #>                           origin
+    #> 1 author;miape;jpr_guidelines_ms
+    #> 2 author;miape;jpr_guidelines_ms
+    #> 3 author;miape;jpr_guidelines_ms
+    #> 4 author;miape;jpr_guidelines_ms
+    #> 5 author;miape;jpr_guidelines_ms
+    #> 6                   author;miape
+
+In the fourth column `handle_type` specifys how to interpret the fifth
+column `handle`. `"list_path"` indicates that `handle` is a path in the
+flattened json. `"literal"` leads to just copy the value of `handle`.
+With "parameter" the row stays empty because the information is not
+represented in the json.
+
+    head(tmt_LC_pump[4:5])
+    #>   handle_type                                                       handle
+    #> 1   list_path             Instruments.Thermo EASY-nLC.InstrumentFriendName
+    #> 2     literal                                            Thermo Scientific
+    #> 3   parameter                                                         <NA>
+    #> 4   parameter                                                         <NA>
+    #> 5   parameter                                                         <NA>
+    #> 6   list_path Instruments.Thermo EASY-nLC.Method.Sample pickup.Volume [µl]
+
+The last column shows an example of which value the row could have.
+
+    head(tmt_LC_pump[c(2,6)])
+    #>                                               term_verbose
+    #> 1 High Performance Liquid Chromatography (HPLC) Instrument
+    #> 2                                              HPLC Vendor
+    #> 3                                               HPLC Model
+    #> 4                                    Chromatography Column
+    #> 5                             Chromatography Mobile Phases
+    #> 6                                   Injected Sample Volume
+    #>             example
+    #> 1   Thermo EASY-nLC
+    #> 2 Thermo Scientific
+    #> 3              <NA>
+    #> 4              <NA>
+    #> 5              <NA>
+    #> 6              4.00
+
+Create an own combination of the available requirements
+-------------------------------------------------------
+
+First extract a term matching table for the used instruments without
+specifying the origin key.
+
+    full_tmt <- create_term_match_table(
+      instrument_list = c("Thermo EASY-nLC", "Q Exactive - Orbitrap_MS"))
+      # no origin key set
+
+Now it is possible to subset or delete some rows with r tools.
+
+    sub_rows <- c(1, 6:8, 10) # wanted rows
+    subset_tmt <- full_tmt[sub_rows,]
+
+    head(subset_tmt)
+    #>                 term
+    #> 1    hplc_instrument
+    #> 6  hplc_samplevolume
+    #> 7      hplc_gradient
+    #> 8      ms_instrument
+    #> 10          ms_model
+    #>                                                term_verbose
+    #> 1  High Performance Liquid Chromatography (HPLC) Instrument
+    #> 6                                    Injected Sample Volume
+    #> 7                                   Chromatography Gradient
+    #> 8                                    Mass Spectrometer (MS)
+    #> 10                                                 MS Model
+    #>                            origin handle_type
+    #> 1  author;miape;jpr_guidelines_ms   list_path
+    #> 6                    author;miape   list_path
+    #> 7  author;miape;jpr_guidelines_ms    function
+    #> 8  author;miape;jpr_guidelines_ms   list_path
+    #> 10 author;miape;jpr_guidelines_ms     literal
+    #>                                                          handle
+    #> 1              Instruments.Thermo EASY-nLC.InstrumentFriendName
+    #> 6  Instruments.Thermo EASY-nLC.Method.Sample pickup.Volume [µl]
+    #> 7                                    document_easy_nlc_gradient
+    #> 8     Instruments.Q Exactive - Orbitrap MS.InstrumentFriendName
+    #> 10                                                    QExactive
+    #>                     example
+    #> 1           Thermo EASY-nLC
+    #> 6                      4.00
+    #> 7                      <NA>
+    #> 8  Q Exactive - Orbitrap MS
+    #> 10                QExactive
+
+New rows can be added. It is mandatory to fill in `term_verbose`,
+`handle_type` and `handle` in their specific column. `term_verbose`
+should be a short desription for the column as it will show up as key in
+the final table.
+
+If `handle` contains a string that just needs to be copied to the output
+table the collumn `handle_type` should contain `"literal"`.
+
+    # create row
+    new_row <- data.frame(term = "example_line",
+                          term_verbose = "Example line",        # Term in the final table
+                          origin = "",
+                          handle_type = "literal",            
+                          handle = "this will be the value",    # Value in the final table
+                          example = "")
+    # add to subset
+    subset_tmt <- rbind(subset_tmt, new_row)
+
+If the row is meant to show an entry of the json `handle_type` needs to
+be `"list_path"` and `handle` should contain the path to the information
+in the flattened json after the group number.
+
+    # create the flattened json (explained in using_MARMoSET)
+    flat_json <- flatten_json(json = MARMoSET::testfile_json)
+
+    # choose/search for item of the flattened list, get path without group number.
+    fj_path <- stringi::stri_subset(names(flat_json), regex = "Flush")  %>% 
+    stringi::stri_replace_all_regex(pattern = "^Group.[:digit:].", replacement = "")
+
+    # create row
+    new_row <- data.frame(term = "second_example_line",
+                          term_verbose = "Second example, Autosampler flush volume",    # Term in the final table
+                          origin = "",
+                          handle_type = "list_path",            
+                          handle = fj_path,                                             # Value in the final table
+                          example = "")
+    # add to subset
+    subset_tmt <- rbind(subset_tmt, new_row)
+
+This so changed term matching table can be used with the function
+`match_terms()`.
+
+    subset_table <- one_group_match_terms(flat_json = flat_json, 
+                                             term_matching_table = subset_tmt, 
+                                             group_number = 1)
+    subset_table[5:7,]
+    #>                                       Term                  Value
+    #> 5                                 MS Model              QExactive
+    #> 6                             Example line this will be the value
+    #> 7 Second example, Autosampler flush volume                 100.00