Package 'rspacer'

Title: 'RSpace' API Wrapper
Description: Wrapper for the 'RSpace' Electronic Lab Notebook (<https://www.researchspace.com/>) API. This packages provides convenience functions to browse, search, create, and edit your 'RSpace' documents. In addition, it enables filling 'RSpace' templates from R Markdown/Quarto templates or tabular data (e.g., 'Excel' files). This R package is not developed or endorsed by 'Research Space'.
Authors: Gerhard Burger [aut, cre] (ORCID: <https://orcid.org/0000-0003-1062-5576>), Hanneke Leegwater [aut] (ORCID: <https://orcid.org/0000-0001-6003-1544>), Leiden University [cph, fnd] (ROR: <https://ror.org/027bh9e22>)
Maintainer: Gerhard Burger <[email protected]>
License: MIT + file LICENSE
Version: 0.3.1.9000
Built: 2026-05-17 09:15:09 UTC
Source: https://github.com/lacdr/rspacer

Help Index

Function to check availability of the API service

Description

Function to check availability of the API service

Usage

api_status(api_key = get_api_key())

Arguments

api_key

RSpace API key

Value

If the request succeeds, a list with the status message and the RSpace version of the API.

Examples

## Not run: 
api_status()

## End(Not run)

Get the form id used for a document

Description

Get the form id used for a document

Usage

doc_to_form_id(doc_id, verbose = TRUE, api_key = get_api_key())

Arguments

doc_id

Unique identifier of the document
verbose

whether to print the matching document/form
api_key

RSpace API key

Value

A form id.

Add attachments to existing document

Description

Add attachments to existing document

Usage

document_add_attachments(doc_id, attachments, api_key = get_api_key())

Arguments

doc_id

Unique identifier of the document
attachments

attachments to attach to the fields in tibble/data.frame form (one attachment per row), e.g., tibble(field = 7, path = "file.txt")
api_key

RSpace API key

Value

A JSON object, invisibly. The function will raise an error if doc_id is not specified.

Add html content to an existing RSpace document

Description

Append a html document (e.g., generated from quarto) to an RSpace structured document. This function retrieves the current document, and adds text to fields specified by h2 html headers.

Usage

document_append_from_html(
  path,
  existing_document_id,
  tags = NULL,
  attachments = NULL,
  allow_missing_fields = FALSE,
  api_key = get_api_key()
)

Arguments

path

html document to upload
existing_document_id

document identifier of the current RSpace document.
tags

vector of tags to apply to the document (will include "rspacer" by default)
attachments

attachments to attach to the fields in tibble/data.frame form (one attachment per row), e.g., tibble(field = 7, path = "file.txt")
allow_missing_fields

Specify if a mismatch in fields is allowed. If this is FALSE, the html fields cannot be appended to the RSpace document when fields are missing. If it is TRUE, only fields with the same name as in the template will be appended.
api_key

RSpace API key

Value

Invisible JSON response from the API.

Upload a html document to RSpace

Description

This function can upload a html document (e.g., generated from quarto) to an RSpace Basic Document, or to a Structured Document if the template is also provided.

Usage

document_create_from_html(
  path,
  template_id = NULL,
  folder_id = NULL,
  tags = NULL,
  attachments = NULL,
  existing_document_id = NULL,
  api_key = get_api_key()
)

Arguments

path

html document to upload
template_id

document id of the RSpace template used. Will be overwritten by the template of existing_document_id if specified. A basic document is created if no template is specified.
folder_id

folder_id in which the document will be created (can be a notebook)
tags

vector of tags to apply to the document (will include "rspacer" by default)
attachments

attachments to attach to the fields in tibble/data.frame form (one attachment per row), e.g., tibble(field = 7, path = "file.txt")
existing_document_id

document id of a document to be replaced, if NULL (the default) a new document will be created.
api_key

RSpace API key

Value

Invisible JSON response from the API.

Upload a tabular document to RSpace

Description

This function can upload tabular files to RSpace structured documents. The file needs to have exactly two columns, one with the RSpace structured document fields and one with the content.

Usage

document_create_from_tabfile(
  path,
  file_type = NULL,
  document_name = NULL,
  template_id = NULL,
  folder_id = NULL,
  tags = NULL,
  attachments = NULL,
  existing_document_id = NULL,
  api_key = get_api_key()
)

Arguments

path

tabular file to upload. Can be XLSX, CSV or TSV
file_type

an optional character string to specify the file type. Will be guessed from the file name if not specified.
document_name

specify the name of the RSpace entry. If not specified, it will be the value in Title, Name, title, or name if that is one of the fields in the Excel document. If that does not exist, it will be the file name.
template_id

document id of the RSpace template used. Will be overwritten by the template of existing_document_id if specified. A basic document is created if no template is specified.
folder_id

folder_id in which the document will be created (can be a notebook)
tags

vector of tags to apply to the document (will include "rspacer" by default)
attachments

attachments to attach to the fields in tibble/data.frame form (one attachment per row), e.g., tibble(field = 7, path = "file.txt")
existing_document_id

document id of a document to be replaced, if NULL (the default) a new document will be created.
api_key

RSpace API key

Value

Invisible JSON response from the API.

Upload tabular data to RSpace

Description

This function can upload tabular data (data.frame/tibble) to an RSpace structured document. The tabular needs to have exactly two columns, one with the RSpace structured document fields and one with the content.

Usage

document_create_from_tabular(
  df,
  document_name = NULL,
  template_id = NULL,
  folder_id = NULL,
  tags = NULL,
  attachments = NULL,
  existing_document_id = NULL,
  api_key = get_api_key()
)

Arguments

df

tabular data to upload.
document_name

specify the name of the RSpace entry. If not specified, it will be the value in Title, Name, title, or name if that is one of the fields in the Excel document. If that does not exist, it will be the file name.
template_id

document id of the RSpace template used. Will be overwritten by the template of existing_document_id if specified. A basic document is created if no template is specified.
folder_id

folder_id in which the document will be created (can be a notebook)
tags

vector of tags to apply to the document (will include "rspacer" by default)
attachments

attachments to attach to the fields in tibble/data.frame form (one attachment per row), e.g., tibble(field = 7, path = "file.txt")
existing_document_id

document id of a document to be replaced, if NULL (the default) a new document will be created.
api_key

RSpace API key

Value

Invisible JSON response from the API.

Get the fields of a structured document as a tibble

Description

This function retrieves the fields of a structured document and returns them as a tibble, one row per field. As fields can contain HTML, the tibble can be displayed prettier with, for example, the gt package (see the Examples).

Usage

document_get_fields(doc_id, api_key = get_api_key())

Arguments

doc_id

Unique identifier of the document
api_key

RSpace API key

Value

A tibble with the fields as rows.

Examples

## Not run: 
library(gt)
document_get_fields("SD123456") |> gt() |> fmt_markdown(columns = c(content))

## End(Not run)

List attachments of a structured document

Description

This function lists all attachments of a field in a structured document.

Usage

document_list_attachments(doc_id, api_key = get_api_key())

Arguments

doc_id

Unique identifier of the document
api_key

RSpace API key

Value

description A tibble with identifiers and information on attachments, one attachment per row. Returns an empty tibble if no files are attached to the field.

Get document from RSpace based on document ID

Description

Get document from RSpace based on document ID

Usage

document_retrieve(doc_id, api_key = get_api_key())

Arguments

doc_id

Unique identifier of the document
api_key

RSpace API key

Value

An RSpace document as parsed JSON.

Global search for a term

Description

Global search for a term, works identically to the simple "All" search in RSpace Workspace. Query term must be >= 3 characters long.

Usage

document_search(
  query,
  ...,
  max_results = 50,
  simplify = T,
  api_key = get_api_key()
)

Arguments

query

description
...

query parameters as documented in https://community.researchspace.com/public/apiDocs [GET /documents] Can be used to order/filter the results.
max_results

Maximum number of results to return.
simplify

Whether to simplify the returned tibble by converting/removing columns Use Inf to return all results (may take a while).
api_key

RSpace API key

Value

A tibble with search results, one result per row.

Convert fields list to a tibble

Description

Convert fields list to a tibble

Usage

fields_to_data_frame(fields, simplify = T)

Arguments

fields

fields list as retrieved from RSpace API
simplify

Whether to simplify the returned tibble by converting/removing columns

Value

A tibble with the fields as rows.

Download a file from the gallery

Description

Download a file from the gallery

Usage

file_download(file_id, path = ".", api_key = get_api_key())

Arguments

file_id

gallery file to be downloaded
path

download destination
api_key

RSpace API key

Value

The file path of the downloaded file. If the file already exists, the user is asked whether the function should overwrite the pre-existing file. If not, the download is canceled and FALSE is returned invisibly.

Upload a file to the gallery

Description

Upload a file to the gallery

Usage

file_upload(path, api_key = get_api_key())

Arguments

path

file to be uploaded
api_key

RSpace API key

Value

Parsed JSON response from the API.

List contents of a folder, if no folder is specified the contents of the root folder will be listed.

Description

List contents of a folder, if no folder is specified the contents of the root folder will be listed.

Usage

folder_tree(
  folder_id = NULL,
  ...,
  max_results = Inf,
  simplify = T,
  api_key = get_api_key()
)

Arguments

folder_id

Unique identifier of the folder, if NULL will return contents of the Workspace Home folder
...

query parameters as documented in https://community.researchspace.com/public/apiDocs [GET /folders/tree]. Can be used to order/filter the results.
max_results

Maximum number of results to return.
simplify

Whether to simplify the returned tibble by converting/removing columns
api_key

RSpace API key

Value

A tibble with the folder content as rows.

Get the RSpace API key

Description

Gets the RSpace API key from the RSPACE_API_KEY environment variable. See set_api_key() on how to set it.

Usage

get_api_key()

Value

An API key

See Also

set_api_key()

Examples

## Not run: 
get_api_key()

## End(Not run)

Get the RSpace API URL

Description

Gets the RSpace API URL from the RSPACE_API_URL environment variable. See set_api_url() on how to set it.

Usage

get_api_url()

Value

A url.

See Also

set_api_url()

Examples

## Not run: 
get_api_url()

## End(Not run)

Set the RSPACE_API_KEY environment variable

Description

Sets the RSPACE_API_KEY environment variable to the provided RSpace API key. To create an API key go to 'Manage API Key' section of your profile page (MyRSpace -> Profile).

Usage

set_api_key(rspace_api_key)

Arguments

rspace_api_key

Your RSpace API key

Details

This will only set the environment variable for the current session, to set it permanently, add ⁠RSPACE_API_KEY=<your_api_key_here>⁠ to your .Renviron file, for example, using usethis::edit_r_environ().

Value

A logical indicating if setting the API key succeeded

Set the RSPACE_API_URL environment variable

Description

Sets the RSPACE_API_URL environment variable to the provided RSpace API URL. The RSpace API URL is likely the URL of your RSpace instance followed by api/v1.

Usage

set_api_url(rspace_api_url)

Arguments

rspace_api_url

The RSpace API URL

Details

This will only set the environment variable for the current session, to set it permanently, add ⁠RSPACE_API_URL=<your_api_url_here>⁠ to your .Renviron file, for example, using usethis::edit_r_environ().

Value

A logical indicating if setting the API URL succeeded.

Examples

## Not run: 
set_api_url("https://leiden.researchspace.com/api/v1")

## End(Not run)