Get started with glcdp

glcdp provides a focused route from a Global Light Commons (GLC) package to analysis-ready R data:

This article uses the validated MELIDOS IZTECH package throughout. Its current passing revision uses schema 3.0.2 and exercises the stable 3.0 import contract with real questionnaire, participant, and light-sensor data. Remote examples run when pkgdown builds the package website. They are displayed without execution during ordinary package and CRAN builds, which keeps those checks independent of network availability. Website maintainers can also set GLCDP_SKIP_LIVE=true for an explicitly offline pkgdown build.

Install and load

Install the development version from GitHub and attach the package:

pak::pak("tscnlab/glc-dp-r")
library(glcdp)

glcdp currently understands the following GLC schemas:

library(glcdp)
glc_schema_versions()
#> # A tibble: 5 × 3
#>   version status notes                                                          
#>   <chr>   <chr>  <chr>                                                          
#> 1 1.0.0   legacy Barebones support for recognizable packages without a root ver…
#> 2 2.0.0   legacy Barebones compatibility for the unimplemented legacy schema.   
#> 3 3.0.0   stable Compatible stable predecessor using the typed import contract. 
#> 4 3.0.1   stable Compatible stable predecessor using the typed import contract. 
#> 5 3.0.2   stable Current default schema and primary metadata-driven import impl…

Discover a package

The registry includes both passing and non-passing current revisions. Keeping both visible makes validation status explicit instead of silently hiding packages with problems.

packages <- glc_packages()
packages

glc_search_packages("iztech", packages)

You can also filter on validation status or on whether a package has a recorded passing revision:

glc_search_packages(packages = packages, status = "pass")
glc_search_packages(packages = packages, has_pass = TRUE)

Open a reproducible revision

Registered packages open at their latest passing commit by default. The returned handle records the repository, exact commit, schema version, and whether the revision was verified against the registry.

iztech_repository <- "tscnlab/melidos-iztech-glc-dataset"
iztech_dataset <- "MELIDOS_IZTECH_S001"
iztech_demographics <- "MELIDOS_IZTECH_S001:4"
iztech_chest_light <- "MELIDOS_IZTECH_S001:17"

iztech <- glc_open(iztech_repository)
iztech

The same function opens a local package directory or its datapackage.json file:

local_package <- glc_open("path/to/data-package")

Inspect before reading

A compact summary is a useful first look:

glc_summary(iztech)

The inventories make data selection explicit. List datasets, then narrow the file and variable inventories to the dataset and file groups you intend to read.

glc_datasets(iztech)
glc_files(iztech, dataset_id = "MELIDOS_IZTECH_S001")
glc_variables(
  iztech,
  file_group = "MELIDOS_IZTECH_S001:17",
  primary = TRUE
)

Use glc_metadata() for structured metadata and glc_search_metadata() when you need to locate a value without knowing its resource or field in advance.

metadata <- glc_metadata(
  iztech,
  resources = c("study", "participants")
)
metadata$study
metadata$participants

glc_search_metadata(iztech, "Izmir", resources = "study")
glc_search_metadata(
  iztech,
  "participant_age",
  resources = "participants",
  search_in = "fields"
)

Let the schema define R column types

Schema 3.0.2 declares every source column’s data type and, for factors, its allowed levels in schema-declared order. glc_read() applies those declarations instead of guessing from the first rows of a file. The compact demographics file contains numeric, logical, and factor columns:

demographic_variables <- glc_variables(
  iztech,
  file_group = "MELIDOS_IZTECH_S001:4"
)
demographic_variables[, c("name", "type", "factor_values")]

The imported R classes and factor levels follow that inventory:

demographics <- glc_read(
  iztech,
  dataset_id = "MELIDOS_IZTECH_S001",
  file_group = "MELIDOS_IZTECH_S001:4"
)
demographic_data <- demographics$data[[1]]
demographic_data
levels(demographic_data$sex)

The same metadata-driven import also handles headers, datetime formats, decimal marks, encodings, and time zones. By default, values that cannot be parsed to the declared type or factor level are reported as errors rather than silently changing the column.

Read selected light data

A dataset selection is required so that a large package is not imported accidentally. File-group and variable selectors keep the request precise. This example reads only photopic illuminance from the S001 chest sensor and limits parsing to the first 10,000 records:

light_collection <- glc_read(
  iztech,
  dataset_id = "MELIDOS_IZTECH_S001",
  file_group = "MELIDOS_IZTECH_S001:17",
  variables = "LIGHT",
  n_max = 10000
)
light_collection

In interactive sessions, glc_read() displays progress across the selected files. Set progress = FALSE to suppress the indicator, for example in a script that manages its own progress reporting.

The result has one row per compatible file group and stores each imported table in its data list-column. Inspect or process groups separately when their roles, modalities, or schemas differ.

names(light_collection$data[[1]])

n_max limits rows parsed after the selected remote file is available; it does not turn a source file into a byte-range download.

Collect compatible groups

glc_collect() checks that the selected groups have compatible columns, types, time zones, modalities, roles, data states, and datetime specifications before combining them. Its default output maps the dataset id to Id, the participant id to participant_Id, parses Datetime, and retains a declared source file.name column when present (otherwise deriving it from the package path). Internal .glc_* provenance columns are removed from this analysis-ready result, matching the core conventions described in LightLogR’s import documentation.

light_data <- glc_collect(light_collection)
head(light_data[!is.na(light_data$LIGHT), ])

The result can be passed directly to LightLogR. Continue with its guides to visualizing light logger data or calculating light exposure metrics.

Use standardize = "none" to leave the source columns and .glc_* provenance columns unchanged:

source_data <- glc_collect(
  light_collection,
  standardize = "none"
)
head(source_data)