Getting Started with rcdf

What is RCDF?

Think of an RCDF file as a locked cabinet for your data. You can store multiple datasets inside it, and the cabinet can only be opened with the right key. When you share the file with a colleague, they cannot see the contents unless you also give them a copy of the key.

Under the hood, an RCDF file is a single portable archive (.rcdf) that holds your datasets as compressed, encrypted files along with a small metadata record. The encryption happens automatically — you never have to configure it yourself.

Setup

library(rcdf)

The package ships with a sample RCDF file and matching keys so you can try everything without creating your own files first:

sample_dir  <- system.file("extdata", package = "rcdf")
sample_rcdf <- file.path(sample_dir, "mtcars.rcdf")
sample_key  <- file.path(sample_dir, "sample-private-key.pem")

Step 1 — Create your encryption keys

Before saving data, you need a key pair — two files that work together:

Generate a new pair with one function call:

pub_key <- generate_rsa_keys(
  path     = "~/my-keys",         # folder where both files are saved
  password = "a-strong-password"  # optional, but protects the private key
)
# pub_key holds the path to the public key — you will pass it to write_rcdf()

Important: Your private key is the only way to open your files later. Back it up and store it securely. A password manager or encrypted drive is a good choice.

Step 2 — Save your data

Organise your datasets into a named list, then call write_rcdf():

# Create a container for your tables
my_data <- rcdf_list()

# Add any data frames you want to store together
my_data$households <- data.frame(id = 1:100, region = sample(c("North", "South"), 100, TRUE))
my_data$survey     <- data.frame(id = 1:100, score  = rnorm(100))

# Save everything as a single encrypted file
write_rcdf(
  data    = my_data,
  path    = "~/data/survey-2024.rcdf",
  pub_key = pub_key              # path returned by generate_rsa_keys()
)

This creates survey-2024.rcdf — a single, portable file containing all your tables, fully encrypted and ready to share.

Step 3 — Read the data back

To open an RCDF file, provide the matching private key:

survey_data <- read_rcdf(
  path           = "~/data/survey-2024.rcdf",
  decryption_key = "~/my-keys/private-key.pem",
  password       = "a-strong-password"   # only needed if you set one
)

# Each table comes back as a data frame inside the list
head(survey_data$households)
head(survey_data$survey)

Try it right now using the bundled sample data:

sample_data <- read_rcdf(
  path           = sample_rcdf,
  decryption_key = file.path(sample_dir, "sample-private-key-pw.pem"),
  password       = "1234"
)

head(sample_data$mtcars)

all_data <- read_rcdf(
  path           = "~/data/monthly-exports/",
  decryption_key = "~/my-keys/private-key.pem",
  password       = "a-strong-password",
  recursive      = FALSE   # set TRUE to also search sub-folders
)

Step 4 — Export to other formats

Once you have the data in R, export it to whatever format your team needs:

write_rcdf_as(
  data    = survey_data,
  path    = "~/exports/survey-2024",
  formats = c("csv", "xlsx")   # create both at once
)
# Result:
#   ~/exports/survey-2024/CSV/households.csv
#   ~/exports/survey-2024/CSV/survey.csv
#   ~/exports/survey-2024/Excel/households.xlsx
#   ~/exports/survey-2024/Excel/survey.xlsx

All supported formats:

You can also call the individual functions directly (e.g. write_rcdf_csv(), write_rcdf_xlsx()) if you need more control. Run ?write_rcdf_as to see all options.

Checking a file without decrypting it

You can inspect when an RCDF file was created, which package version wrote it, and integrity checksums — all without the private key:

meta <- get_attrs(sample_rcdf)
meta$created_at   # when the file was created
meta$version      # package version used to create it
meta$checksum     # per-table checksums for integrity verification

Next steps

• Working with multiple files — see vignette("merging-rcdf") for loading or combining RCDF files from different sources.
• Full function reference — run ?write_rcdf, ?read_rcdf, or ?write_rcdf_as in the R console for all available options.