---
title: "Get started with harbouR"
output: rmarkdown::html_vignette
vignette: >
%\VignetteIndexEntry{Get started with harbouR}
%\VignetteEngine{knitr::rmarkdown}
%\VignetteEncoding{UTF-8}
resource_files:
- figures/logo.svg
- figures/logo-dark.svg
---
```{r setup, include = FALSE}
knitr::opts_chunk$set(collapse = TRUE, comment = "#>")
```
You have a SeaTable base of patient samples and you want to pull it into
R for analysis, push your results back, and attach the resulting PDF
reports - all without leaving R. `harbouR` is an unofficial R client
that lets you do exactly that, against a **self-hosted SeaTable server**
or against an exported **`.dtable` file** with no server at all.
> SeaTable is a trademark of SeaTable GmbH; harbouR is not affiliated
> with or endorsed by SeaTable GmbH.
## Connect
```{r connect, eval = FALSE}
library(harbouR)
client <- hb_client(
server = Sys.getenv("SEATABLE_SERVER"),
api_token = Sys.getenv("SEATABLE_API_TOKEN")
)
```
SeaTable uses a three-token model. You hand harbouR either an
API-token (long-lived, per-base, generated in the SeaTable UI) or a
username+password pair. harbouR exchanges these for a short-lived
**base-token** the first time it needs to, caches it, and refreshes
transparently when it expires - you never see it.
## Inspect the base
The remaining chunks here all run **offline**, against the bundled
example data, so you can knit the vignette without a server.
```{r inspect}
library(harbouR)
meta <- hb_example_metadata()
meta
tibble::as_tibble(meta)
```
## Read a table
Against a live server this is a single call:
```{r read-live, eval = FALSE}
samples <- hb_read_table(client, "Samples")
```
The offline equivalent returns a tibble of the same shape, including
list-columns for multi-select / collaborator / file values:
```{r read-offline}
samples <- hb_example_rows("Samples")
samples
```
## Analyse
`samples` is a regular tibble. Everything you already know about
dplyr / ggplot2 / etc. just works:
```{r analyse, message = FALSE, warning = FALSE}
samples[samples$Status == "ready", c("Name", "Concentration", "Collected")]
```
## Write back
Appending and updating accept any tibble whose columns match the schema:
```{r write-live, eval = FALSE}
new_rows <- tibble::tibble(
Name = "S-004",
Concentration = 17.2,
Status = "draft"
)
hb_append_rows(client, "Samples", new_rows)
hb_update_rows(
client, "Samples",
tibble::tibble(`_id` = "r0001", Concentration = 99.9)
)
```
## Attach a file
```{r attach, eval = FALSE}
hb_attach_file(client, "Samples", "r0001", "Reports", "report.pdf")
```
## Next steps
* The `column-types` vignette explains the coercion layer in detail.
* The `explorer-app` vignette walks through `hb_run_explorer()`.
## Citation
If harbouR contributes to work you publish, please cite it:
```{r citation}
citation("harbouR")
```
The text and the BibTeX entry are both generated from the package
metadata, so they always match the version you have installed.
## Authors
harbouR is by Raban Heller, Paul Elsinghorst, Wiebke Derz, Matthias Ring,
Gerhard Achatz and Vinzent Forstmeier. It grew out of their needs, field
testing and data.
## Trademarks and affiliation
harbouR is an independent, third-party client. It is **not** affiliated
with, endorsed by, sponsored by, or officially connected to SeaTable GmbH,
and support requests about harbouR should go to its own issue tracker
rather than to SeaTable GmbH.
SeaTable is a trademark of SeaTable GmbH, 117er Ehrenhof 5, 55118 Mainz,
Germany (Amtsgericht Mainz, HRB 49723). harbouR uses the name only to
identify the service it communicates with and claims no right in the mark.
harbouR contains no SeaTable server code; it speaks to a SeaTable server
through the public REST API documented at .
Your use of SeaTable itself is governed by your agreement with SeaTable
GmbH, not by this package's licence.
The full notice is at
.
## Acknowledgements
harbouR is a client, and it rests on work SeaTable GmbH and Seafile Ltd.
did first โ in particular on their decisions about how open that work
would be.
They publish the OpenAPI 3.0 specification for the REST API as a public
repository, kept on one branch per server version, so the contract a
release promised remains available afterwards. The full reference reads
without an account or payment. The admin and developer manuals are
public repositories that accept pull requests. The official Python and
PHP clients are Apache-2.0.
They also write down what they break. The public API changelog recorded
that `/dtable-server` and `/dtable-db` were deprecated in 5.2 and removed
in 5.3. harbouR was aimed at exactly those endpoints; without that entry
this package would still be talking to an API that no longer exists.
For accuracy: SeaTable Server is not open source โ `dtable-server`, the
component holding the tables, is proprietary. The official clients and
SDKs are Apache-2.0. The API specification and reference are published
publicly but carry no open licence, and harbouR relies on none: it
reproduces no documentation prose, and it relies on the exclusion of the
ideas and principles underlying a program's interfaces from copyright
protection (Art. 1(2), Directive 2009/24/EC; ยง 69a(2) UrhG; CJEU
C-406/10). SeaTable's own dtable-server EULA points the same way โ
applications using the API are "third-party software", and "[t]he
provisions of the EULA do not apply to any such third-party software".
This is reasoning, not legal advice; the full notice linked above sets
out its limits.
SeaTable is developed by Seafile Ltd. (Beijing); SeaTable GmbH (Mainz)
is the German company behind it. Thanks are owed to both.