diff --git a/vignettes/fjson_screenshot.JPG b/vignettes/fjson_screenshot.JPG new file mode 100644 index 0000000..041f392 Binary files /dev/null and b/vignettes/fjson_screenshot.JPG differ diff --git a/vignettes/manipulate_term_match_table.md b/vignettes/manipulate_term_match_table.md new file mode 100644 index 0000000..e3d18c9 --- /dev/null +++ b/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 + #> 4 parameter + #> 5 parameter + #> 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 + #> 4 + #> 5 + #> 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 + #> 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