---
title: "*rspacer*: an RSpace API wrapper"
subtitle: "Integrating the RSpace ELN into computational workflows"
date: 2025-08-03
authors:
  - name: Hanneke Leegwater
    orcid: 0000-0001-6003-1544
    affiliation:
      - id: lu
        name: Leiden University
        department: Leiden Academic Centre for Drug Research
        city: Leiden
        country: NL
        url: https://www.universiteitleiden.nl/en
        ror: https://ror.org/027bh9e22
        isni: 0000000123121970
  - name: Sylvia Le Dévédec
    orcid: 0000-0002-0615-9616
    affiliation:
      -ref: lu
  - name: Gerhard Burger
    orcid: 0000-0003-1062-5576
    email: g.a.burger@lacdr.leidenuniv.nl
    corresponding: true
    affiliation:
      -ref: lu
bibliography: 
 - references.bib
 - grateful-refs.bib
abstract: |
  With research becoming more data-intensive and increased requirements for FAIR and open data, there is a great need for robust data management strategies. 
  Increasingly, Electronic lab notebooks (ELNs) play a key role in such strategies, but adaption by researchers can lag behind if the ELN cannot be properly integrated into daily research workflows. 
  In this work, we present *rspacer*, an R package that facilitates uploading data, metadata, and notes directly from R using the RSpace API. 
  We demonstrate applications for reusing metadata stored in the RSpace ELN, uploading Quarto reports as lab journal entries, and converting tabular file formats into RSpace documents. 
  *rspacer* streamlines computational workflows leading to more convenient and reliable data entry, which should improve ELN adoption.
keywords:
 - Electronic Lab Notebook (ELN)
 - reproducible research
 - computational workflows
 - Research Data Management (RDM)
 - FAIR
license: "All rights reserved"
fig-cap-location: top
---

## Introduction

Research Data Management (RDM) is in constant development; more and
larger datasets are being generated and analyzed, research is more
collaborative [@2859], and funders require increasingly FAIR
[@Kbjiwfet/582m1iNq] and open data [@2861] in an effort to increase data
quality, integrity, reproducibility, and reusability. In response, many
scientific communities have agreed on, or are working towards reporting
standards and frameworks for research output. These standards include
guidelines for metadata on sample collection, storage conditions, and
measurement details
[@Kbjiwfet/uN9W7T8b; @Kbjiwfet/Blt53i0n; @Kbjiwfet/rfyFooBR; @Kbjiwfet/eqgDZAyy; @Kbjiwfet/2sNhaJ8r; @Kbjiwfet/FIizNHeM; @Kbjiwfet/zEKU8YEx]
supported by domain-specific repositories. For less defined data types,
flexible alternatives such as Zenodo and BioStudies allow sharing with
fewer requirements [@2850; @Kbjiwfet/gT3XgAG0]. Omics metadata often
follows an Investigation-Study-Assay structure [@Kbjiwfet/gt8fS2Fr],
with technology-specific extensions such as metabolite evidence tables
[@Kbjiwfet/zEKU8YEx] or hybridization probe sequences
[@Kbjiwfet/uN9W7T8b]. During data upload, repositories may incorporate
metadata validation protocols [@Kbjiwfet/FIizNHeM; @Kbjiwfet/zEKU8YEx],
or require separate formats for metadata [@Kbjiwfet/WyQgwwAi], often
relying on controlled vocabularies and ontologies.

Meeting these requirements requires meticulous data annotation before,
during, and after data collection. A major challenge is that data
collection often occurs months or even years before publication, risking
omission of important details that cannot be recovered later. A
significant advance in this area has been the introduction of electronic
lab notebooks (ELNs) to replace handwritten notes with digital versions.
ELNs range from basic online notebooks that track changes, such as
OneNote or Evernote, to advanced platforms with additional
functionalities, such as structured folder hierarchies, interlinked
assays, templates, controlled vocabularies or integration with a
laboratory information management system (LIMS) for sample storage
location or compound safety information
[@Kbjiwfet/LNcisbHH; @Kbjiwfet/94CwkKGK; @Kbjiwfet/wOq7cOsP].
Integration of ELNs into data acquisition workflows also facilitate
automated collection of essential metadata, such as microscope or
sequencer settings [@Kbjiwfet/8bZBfR2d], data storage location, software
versions, and data processing steps. These integrations increase
researcher efficiency [@Kbjiwfet/siOdZI48; @2853] and lead to more
reproducible and FAIR research [@Kbjiwfet/f2ngKxrs].

A particular challenge to ELN adoption is integrating it into the
researchers' daily workflow, as established practices can be slow to
change [@2855]. A common workflow used in our institute is computational
analysis and modeling in R using R Markdown and its successor Quarto
(<https://quarto.org/>). Using Quarto, one can generate reproducible
reports using code (e.g., R and Python) and text side-by-side. However,
incorporating these reports into our ELN, RSpace
(<https://www.researchspace.com/>, open-source since 2024) is not
straightforward, as they can only be added as attachments. Moreover,
reusing (meta)data from RSpace in R is inconvenient as it requires
manually downloading files from RSpace.

Here, we present *rspacer*, a wrapper for the RSpace ELN Application
Programming Interface (API). The *rspacer*
package offers a user-friendly set of functions that can automate
uploading documents to RSpace, convert Quarto reports to RSpace
documents, and facilitate the reuse of metadata from RSpace in R. This
integration of the RSpace ELN into the researcher's workflow streamlines
data entry, thereby decreasing the time and energy investment, and at
the same time increases (meta)data quality, leading to better
reproducibility and ELN adoption.

## Implementation

*rspacer* is an R [@Kbjiwfet/LqlhCVIm] package and uses the *httr2*
package [@Kbjiwfet/lX7U9jLx] to wrap a subset of the RSpace API
documented at <https://community.researchspace.com/public/apiDocs>.
Its main functionality is divided into three categories, roughly
corresponding to different API endpoints: browsing/searching the RSpace
file and folder structure, interacting with RSpace documents, and
interacting with [RSpace Gallery](https://web.archive.org/web/20250701084519/https://documentation.researchspace.com/article/sl6mo1i9do-the-gallery) files,
used, for example, to add attachments to RSpace documents ([@fig-rspacer]A).

The R package is available on GitHub (<https://github.com/LACDR/rspacer>)
under an OSI-approved license (MIT), and published to CRAN [@2840].

:::{.column-page-inset}
![Functionality of the *rspacer* package. (A) Functions in the
rspacer package include interactions with folders, documents and files
through the RSpace API. (B) A user can retrieve information on folder
structures using the *rspacer* browse and find functionality. (C) An
example workflow where *rspacer* can be used to retrieve metadata from
the RSpace ELN into R. (D) Screenshots of an example workflow where
*rspacer* uses Quarto HTML reports or tabular assay data (CSV/TSV/XLSX)
as input to create new assays in RSpace.](figures/rspacer_functionality_v5.svg){#fig-rspacer width=100%}
:::

Below, we briefly illustrate how *rspacer* can streamline common data
management and analysis tasks by interacting with the RSpace ELN using
easy-to-use functions. A more detailed overview of the package and its
functionality can be found on the *rspacer* website
(<https://lacdr.github.io/rspacer>) and in the package vignettes.

### Interact with the API and RSpace folder structure

After installing the *rspacer* package (see
<https://lacdr.github.io/rspacer>), users must configure API access to
their institute's RSpace instance. This is done by providing the
instance API URL, typically the instance URL followed by `api/v1`
(e.g., `https://leiden.researchspace.com/api/v1`), and a personal API
key, which can be obtained from MyRSpace \> My Profile. *rspacer*
provides two ways to configure these variables: the API URL and key can
be saved as the environment variables `RSPACE_API_KEY` and `RSPACE_API_URL`
(recommended, see
<https://lacdr.github.io/rspacer/articles/rspacer.html#setting-up-rspacer>
for details). Alternatively, these environment variables can be set for
the current session using the `set_api_key()` and `set_api_url()`
convenience functions. Finally, `api_status()` checks if a connection to
the API can be established using the provided URL and API key. If
successful, users can then navigate RSpace's folder structure using the
`folder_tree()` and `document_search()` functions ([@fig-rspacer]B).


### Documents & Files

Most *rspacer* functions interact with documents, as these are the main
way to store information in the ELN. An RSpace document can be retrieved
by its identifier and is returned as a deeply-nested JSON object
converted into an R list object (`document_retrieve()`). This object
includes document metadata, field contents, metadata, and download links
for files belonging to this document. However, as field contents are
returned as raw HTML, this is not the most user-friendly way to interact
with existing documents. Instead, the main added value of *rspacer* is
in creating and updating documents. New documents can be created from
HTML files (`document_create_from_html()`) or tabular file formats such as
XLSX, CSV, or TSV (`document_create_from_tabfile()`); more details are
provided in the Applications section below. To create structured
documents from HTML, *rspacer* splits HTML by `<h2>` headers, placing each
section into a field of an RSpace template, which can be specified using
a template or form identifier. For tabular file formats, each cell
should correspond to the content of a field in an RSpace template, and
no further processing is performed. Users can completely revise
documents by using the `existing_document_id` argument to these
functions or add additional information to existing fields by using the
`document_append_from_html()` function, resulting in new document
versions. Finally, *rspacer* provides functions to upload and download
Gallery files (`file_upload()` and `file_download()`), which facilitate
working with document attachments (`document_list_attachments()` and
`document_add_attachments()`). Altogether, this functionality enables a
variety of applications, of which we will highlight three examples in
the next section.

## Applications

### Application 1: Reuse of (meta)data uploaded to RSpace

In RSpace, (meta)data, such as a plate layout or a workflow config, can
be attached to an RSpace document as files, which are stored in the
RSpace Gallery. One can list all attachments linked in a document
(`document_list_attachments()`) and then download these metadata files
using their unique identifiers (`file_download()`, [@fig-rspacer]C). This
allows RSpace to serve as a single source of truth, where multiple users
can obtain the same verified (meta)data to perform an analysis. For
example, our research group often performs random cell migration assays
to study how cancer cells alter their migration in response to drugs or
other stimuli [@Kbjiwfet/6NZuEeQJ; @Kbjiwfet/FtFYpjWd]. Metadata is
stored using standardized templates [@Kbjiwfet/QxJiECvY], imaging data
is stored internally in OMERO [@Kbjiwfet/evy2Mqu1] and are used to
calculate tracks in CellProfiler [@351]. The output metrics from
CellProfiler, including the mean speed per well, are then processed in R
[@Kbjiwfet/cXgcxWMZ]. *rspacer* can be integrated into this workflow by
downloading the plate layout from RSpace to link the computed migration
characteristics to the experimental conditions. After completing the
analysis, result files can be uploaded to RSpace
(`document_add_attachments()`), or, even better, the entire analysis
workflow can be uploaded to RSpace, as we will discuss in the next
application.

### Application 2: Uploading LACDR-ISA Quarto reports as lab journal entries

The second application of *rspacer* is to upload Quarto reports to
RSpace. This functionality is especially powerful when a standardized
workflow is used for data analysis or for computational modeling. Since
in our institute we use an ISA (Investigation-Study-Assay
[@Kbjiwfet/gt8fS2Fr])-inspired ELN organization, we developed
Investigation, Study, and Assay Quarto templates (available as a
separate R package at <https://github.com/LACDR/LACDR.ISA>), with
matching templates in RSpace (i.e. the headers in the Quarto files
correspond to fields in the RSpace templates).

Using these templates, users can follow their usual computational
workflow in any language that Quarto supports (most notably R, Python,
Julia, and Observable JavaScript) and have the freedom to include any
sub-headers, code, or figures within each section ([@fig-rspacer]D). When
rendered, Quarto (via Pandoc, <https://pandoc.org/>) produces a Quarto
report in HMTL ([@fig-rspacer]D) or any other Pandoc-supported format
(e.g., PDF, MS Word, Revealjs, etc.).

Using the *rspacer* function `document_create_from_html()`, one converts
this HTML report into an RSpace document with the same title and all
report sections as separate fields ([@fig-rspacer]D). The Quarto code (QMD
file) and additional metadata files can be added to this document as
attachment, a good reproducibility practice. An example Quarto and HTML
file are provided within the package, and detailed instructions on how
to use these are provided in the package vignettes and website.

### Application 3: Uploading tabular files as lab journal entries or as metadata 

As described above, tabular files can be uploaded to the Gallery and
attached to RSpace documents. However, they can also serve as input for
an RSpace document using the `document_create_from_tabfile()` function.
Whereas Application 2 focused on computational outputs, this
functionality is more useful in a wet lab context, where experimental
conditions are typically reported in tabular files (e.g., Excel). At
present, *rspacer* only supports tabular files with two columns: one for
the template field names and one for the field content ([@fig-rspacer]D).
Protected Excel files for Investigations, Studies, and Assays matching
our LACDR-ISA standard are included in the supplementary files and
online, where only specific cells are editable (**Supplementary Files 1,
2 and 3**). Instructions on how to use these are provided in the package
vignettes and website. This protection in Excel improves template
reusability for experimentalists and helps ensure that deviations from
the template are minimized.

### Potential applications: Automated workflows and uploading experimental metadata

In addition to the applications described above, *rspacer* allows
bioinformatics workflows to integrate more tightly with the RSpace ELN.
For instance, *rspacer* can be used in an R script to upload result
files with just a single line of code. Integration into a Shiny app for
standardized data analysis could provide a convenient "Upload to RSpace"
button, or even uploading all analysis metadata automatically on each
run. By storing, for example, file paths, information on the number of
files processed, who analyzed the data, the analysis date, and the
software versions used, *rspacer* could facilitate data analysis
becoming much more reproducible.

## Conclusion

In this article, we introduced a newly developed R package, *rspacer*,
to facilitate interaction with the RSpace lab journal API. This tool
enables integrating automated workflows in R with the RSpace ELN.
Applications include uploading computational lab journals in HTML
format, automating metadata reuse, and uploading data and metadata.
These functionalities are particularly beneficial for experiments
involving large datasets, complex computational workflows, or
combinations thereof. As life sciences datasets grow more intricate,
especially in fields using omics technologies, microscopy, and
artificial intelligence, data-driven research will keep expanding. This
growth will make strong data management strategies even more essential.
Implementing an ELN like RSpace is crucial for such strategies, as it
ensures data integrity and provenance while serving as a central hub for
making data FAIR. This leads to increased reproducibility and
reusability of research data. By integrating RSpace into daily
workflows, the *rspacer* package simplifies and streamlines data entry,
improving ELN adoption and further reinforcing these benefits.

## Acknowledgments {.appendix}

We are grateful for the great R package ecosystem, and in particular for the tremendously helpful "R Packages" book [@wickham2023r], Quarto [@quarto], and our package dependencies:

|Package   |Version |Citation                                       |
|:---------|:-------|:----------------------------------------------|
|base      |4.5.1   |@base                                          |
|cli       |3.6.5   |@cli                                           |
|curl      |6.2.2   |@curl                                          |
|dplyr     |1.1.4   |@dplyr                                         |
|fs        |1.6.6   |@fs                                            |
|glue      |1.8.0   |@glue                                          |
|httr2     |1.1.2   |@httr2                                         |
|purrr     |1.0.4   |@purrr                                         |
|readr     |2.1.5   |@readr                                         |
|readxl    |1.4.5   |@readxl                                        |
|rlang     |1.1.6   |@rlang                                         |
|rvest     |1.0.4   |@rvest                                         |
|stringr   |1.5.1   |@stringr                                       |
|tibble    |3.3.0   |@tibble                                        |
|tidyr     |1.3.1   |@tidyr                                         |
|xml2      |1.3.8   |@xml2                                          |
|knitr     |1.50    |@knitr2014; @knitr2015; @knitr2025             |
|pkgdown   |2.1.2   |@pkgdown                                       |
|rmarkdown |2.29    |@rmarkdown2018; @rmarkdown2020; @rmarkdown2024 |
|spelling  |2.3.1   |@spelling                                      |
|testthat  |3.2.3   |@testthat                                      |
|usethis   |3.1.0   |@usethis                                      |

And finally for *grateful* [@grateful] for making it easy to be  grateful.

## References {.appendix}

::: {#refs}
:::
