Tutorial: creating a document from a table
Source:vignettes/articles/create_document_from_table.qmd
Before you start
In this tutorial, we describe how to create an RSpace structured document from a delimited file format, such as Excel, TSV or CSV. We advice you to read vignette("rspacer") to make sure that you are ready to use this upload document. You need to install rspacer and set up your API url and API key before the start of this tutorial.
Load R libraries
Check if the API is available
This code checks if the API is available. The API status should be OK.
(res <- api_status())## $message
## [1] "OK"
##
## $rspaceVersion
## [1] "1.115.2"
stopifnot(res$message == "OK")Create a structured document in RSpace
Create a Template from a Form with four text Fields named “Title”, “Date”, “Main part” and “Conclusion”. Write down the unique Structured Document identifier, you will need it later. For us, this identifier was SD377682. Instructions to design a Template in RSpace can be found here.
Create a small example document
Open Excel and create a csv file or run the code chunk below to create a small example file. It should have two columns. The first one should have all fields exactly the same as the template. The second column should have the content of each field in the correct format. If you use Excel, make sure that dates are saved as a string in the format dd-mm-yyyy.
df_to_upload <- data.frame(
name = c("Title", "Date", "Main part", "Conclusion"),
content = c("example title", "23-12-2024", "This is example text.",
"ready for uploading.")
)Upload the data
To upload the data to the API inbox, this code chunk is sufficient and returns the created document. It creates a document from your Template_example.csv. The function works with CSV, TSV and XLSX file formats. Make sure that the template_id is the identifier of the template that you previously made in RSpace.
document_create_from_tabular(
df = df_to_upload,
template_id = "SD377682"
)## Document created: <https://leiden.researchspace.com/globalId/SD426706>The function document_create_from_tabular() has more parameters, for example, to upload the document to a specified notebook or folder (click the function above to learn more).
How to find the values for these parameters? Browse your RSpace folders using folder_tree() and use either the id or the globalID. Folder identifiers start with FL, notebook identifiers start with NB, structured document identifiers start with SD. For example:
## # A tibble: 10 × 7
## id globalId name created lastModified type owner
## <int> <chr> <chr> <dttm> <dttm> <chr> <chr>
## 1 356307 SD356307 Gerhard Burger 2024-01-17 14:56:22 2024-01-17 15:04:39 DOCUMENT Gerhard Burger
## 2 260004 FL260004 LACDR RDM 2023-11-06 10:19:59 2023-11-06 10:19:59 FOLDER Gerhard Burger
## 3 242175 FL242175 GABi001_EMP_regulation 2023-05-30 10:14:51 2023-06-14 12:30:47 FOLDER Gerhard Burger
## 4 242400 FL242400 Ontologies 2023-06-01 07:23:10 2023-06-01 07:23:10 FOLDER Gerhard Burger
## 5 242398 FL242398 Api Inbox 2023-06-01 07:23:08 2023-06-01 07:23:08 FOLDER Gerhard Burger
## 6 242182 FL242182 Publications 2023-05-30 11:07:25 2023-05-30 11:07:25 FOLDER Gerhard Burger
## 7 21961 FL21961 DDS2 Data management 2023-03-16 09:50:33 2023-03-16 09:50:33 FOLDER Gerhard Burger
## 8 7833 FL7833 Templates 2022-12-22 12:32:22 2022-12-22 12:32:22 FOLDER Gerhard Burger
## 9 7819 GF7819 Gallery 2022-12-22 12:32:22 2022-12-22 12:32:22 FOLDER Gerhard Burger
## 10 7814 FL7814 Shared 2022-12-22 12:32:22 2022-12-22 12:32:22 FOLDER Gerhard Burger
folder_tree("FL409926")## # A tibble: 4 × 7
## id globalId name created lastModified type owner
## <int> <chr> <chr> <dttm> <dttm> <chr> <chr>
## 1 409948 SD409948 example title 2025-04-24 10:12:56 2025-04-24 10:13:06 DOCUMENT Hanneke Leegw…
## 2 409942 SD409942 example title 2025-04-24 10:11:01 2025-04-24 10:11:10 DOCUMENT Hanneke Leegw…
## 3 409929 SD409929 a002_normalize_lipidomics 2025-04-24 10:01:59 2025-04-24 10:02:14 DOCUMENT Hanneke Leegw…
## 4 409928 SD409928 a001_preprocess_data 2025-04-24 10:01:34 2025-04-24 10:01:52 DOCUMENT Hanneke Leegw…Of course you can also find these by going to the web interface of your RSpace instance. You can also tag your documents using a tags vector, for example a status like “finished” or “in progress” or “failed”. If you want to upload attachments to a field, use the attachments argument. Files will be added in the number of the field as an attachment. You can optionally replace an existing Document by specifying an existing_file_id. Use this only if a file needs to be replaced instead of created.
In this example we add a Quarto code file and a HTML file Template_example.html as an attachment to the field with number 4. We also place the file in a specific folder, and add the “tutorial” tag.
attachment_file <- system.file("Template_example.html", package = "rspacer")
(matching_code_file <- fs::path_ext_set(attachment_file, ".qmd"))## /Users/gerhard/GitHub/rspacer/inst/Template_example.qmd
document_create_from_tabular(
df = df_to_upload,
template_id = "SD377682",
tags = c("tutorial"),
attachments = tibble(field = c(4, 4), path = c(attachment_file, matching_code_file))
)## File uploaded to <https://leiden.researchspace.com/globalId/GL426708>
## File uploaded to <https://leiden.researchspace.com/globalId/GL426709>
## Document created: <https://leiden.researchspace.com/globalId/SD426710>Uploading directly from file
You can also directly upload tabular data from files using the document_create_from_tabfile() function. A small example, with the example data from before:
file_name <- "Template_example.csv"
df_to_upload |>
write_csv(file_name, col_names = FALSE) # the csv should not contain the column names
# now we upload
document_create_from_tabfile(
path = file_name,
template_id = "SD377682"
)## Document created: <https://leiden.researchspace.com/globalId/SD426712>