Skip to contents

Convert documents using bibr

Source: R/import-bibr.R
convert_bibr.Rd

Converts document files (PDF, DOC, DOCX) to structured JSON using the bibr extraction service. Supports three backends: metacheck's API on SURF Research Cloud ("surf"), which converts PDF files and needs no API key; the Scienceverse platform ("scivrs") which uses a job queue with load balancing; and a self-hosted bibr instance ("selfhosted") for direct API access.

Usage

convert_bibr(
  file_path,
  save_path,
  backend = c("auto", "surf", "scivrs", "selfhosted"),
  api_key = NULL,
  api_url = NULL,
  include_figures = FALSE,
  start_page = 1,
  end_page = Inf,
  poll_interval = 2,
  timeout = 600
)

Arguments

file_path

Path to the document file, or a directory of documents

save_path

Path to a directory in which to save the JSON file; there is no default, because CRAN does not allow writing into the working directory unless you ask for it

backend

Which backend to use: "auto" (default) detects from the available API key and URL (see Details), "surf" uses metacheck's API on SURF Research Cloud, "scivrs" uses the Scienceverse platform, "selfhosted" uses a direct bibr API instance.

api_key

API key. For the scivrs backend, a Bearer token starting with sv_, defaulting to the SCIVRS_API_KEY env var. For the selfhosted backend, the server's bearer token if it requires one, defaulting to the BIBR_API_KEY env var (none if unset).

api_url

Base URL of the API. Defaults to the appropriate URL for the selected backend (for surf, the SURF_API_URL env var or https://metacheckserve.metacheck.src.surf-hosted.nl/api; for selfhosted, the BIBR_API_URL env var or http://localhost:8000).

include_figures

Whether to include base64-encoded figure images in the output (default FALSE; not for the surf backend)

start_page

First page of the file to extract (default 1; not for the surf backend)

end_page

Last page of the file to extract (default Inf for all pages; not for the surf backend)

poll_interval

Seconds between status polls, scivrs backend only (default 2)

timeout

Maximum seconds to wait for processing (default 600)

Value

Path(s) to the saved JSON file(s)

Details

When backend = "auto" (the default), the "scivrs" backend is used if api_key is provided or the SCIVRS_API_KEY environment variable is set, and "selfhosted" if api_url is provided or the BIBR_API_URL environment variable is set. Otherwise, "surf" is used.

The "surf" backend sends the PDF to the /convert endpoint of metacheck's API on SURF Research Cloud, whose address can be set with the SURF_API_URL environment variable. It converts only PDF files (at most 50 MB), always whole and without figures, so include_figures, start_page and end_page do not apply. The server deletes the upload once it is converted, and the result an hour later.

A self-hosted bibr server that requires authentication (bibr serve with AUTH_API_KEY set, as on a SURF Research Cloud workspace) gets its bearer token from api_key or the BIBR_API_KEY environment variable; its address can be set with BIBR_API_URL.

Examples

if (FALSE) { # \dontrun{
# Auto-detect backend from environment variables
pdf <- demofile("pdf")
convert_bibr(pdf)

# Explicitly use metacheck's API on SURF Research Cloud
convert_bibr(pdf, backend = "surf")

# Explicitly use Scienceverse platform
convert_bibr(pdf, backend = "scivrs")

# Use self-hosted bibr instance
convert_bibr(pdf, backend = "selfhosted")

# Extract specific pages
convert_bibr(pdf, start_page = 1, end_page = 10)

# Directory of papers
dir <- system.file("demo", package = "metacheck")
convert_bibr(dir, save_path = "results/")
} # }