# Get started with glcdp

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

1. discover a registered package;
2. open an immutable revision;
3. inspect its datasets, files, variables, and metadata;
4. read only the data you need; and
5. collect compatible file groups for analysis.

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)

## Where to go next

- Explore and hand off data with the Shiny app follows the same IZTECH package through a guided browser workflow.
- Discover and inspect data packages covers registry, revision, inventory, and metadata workflows.
- Import and download data covers schema-defined column types, precise imports, persistent downloads, and reproducibility manifests.