Getting started with dqcheckrGUI

First-run setup

On first launch, if no dqcheckr.yml global config file exists in the working directory, the app opens directly to Global Config and prompts you to set two paths before doing anything else:

• Snapshot database — where run summaries are stored (e.g. data/snapshots.sqlite)
• Report output directory — where HTML reports are written (e.g. reports/)

Click Save global config once these are set, then proceed to configure your first dataset.

Example configuration files

Example YAML configuration files using the Star Wars dataset are included with the package. Copy them to get started quickly:

file.copy(
  system.file("extdata/example_config", package = "dqcheckrGUI"),
  "config",
  recursive = TRUE
)

Status badges

Status badges appear in the sidebar, dataset panel, and history table:

Step 1 — Dataset identity

Enter a short machine-readable name for the dataset. Names must start with a letter and contain only letters, numbers, and underscores (e.g. customer_accounts). This name is used as the config filename and passed directly to dqcheckr::run_dq_check().

An optional free-text description can also be added.

Step 2 — File location

Choose how files are identified for each run:

Folder scan (recommended) — point to a folder; the app picks the two most recently modified files automatically on each run. Use this for delivery processes that drop files into a fixed directory.

A Preview most recent file button shows the names and sizes of the two most recent files in the selected folder: “Current: 20260530.csv (2.4 MB) | Previous: 20260523.csv (2.3 MB)”.

Explicit file paths — list a current file and optionally a previous file by path. Useful when files are versioned by name. If no previous file is given, comparison checks (CP series) are skipped.

Step 3 — Format and structure

This step identifies the file’s format and column layout. The top of the screen shows a raw text preview of the first 50 lines of the file — the full file is never loaded.

Auto-detection: when a file is loaded, the app uses readr to detect the delimiter, encoding, quote character, and whether the first row is a header. Results are shown as an editable confirmation panel — you always make the final call, nothing is silently committed.

Step 4 — Column classification

Review every detected column. For each column you can:

• Set a type override — force a column to be treated as character even if it looks numeric. Use this for postcodes, phone numbers, account codes, BSB numbers, or any identifier that happens to contain only digits. Click the inferred type to open the override dropdown.
• Mark as key column — that column will be checked for uniqueness (QC-12).
• Mark as expected — columns not present in a delivery will raise a schema warning (SC-01). All columns are expected by default; use Select none to clear all and tick only the columns that must always be present.

Step 5 — Column rules

Each column is shown as a collapsible card. Expand a column to add optional per-column validation rules.

Standard rules (always visible):

Advanced rules (click Advanced ▼ to reveal):

A regex syntax error disables Next; a pattern that fails against sample values shows a warning but does not block you from proceeding.

Step 6 — Rule overrides

Override the global default thresholds for this dataset only. Each field is pre-filled with the current global default. Only fields whose value differs from the global default are written to the dataset config; fields left at their default are omitted so that a later change to the global config is automatically inherited.

Schema change flags control whether warnings are raised when columns are added, dropped, change type, or change order between deliveries.

Step 7 — Custom checks (optional)

Point to a plain R file that defines a custom_checks(df) function. The app validates the file immediately: it checks that the file exists, parses without syntax errors, and defines the expected function. A green badge confirms a valid file; a red badge shows the specific problem.

Leave this field blank to skip custom checks. See vignette("dqcheckr", package = "dqcheckr") for the custom checks function signature and return value.

Step 8 — Review and save

A summary of all settings is shown alongside a YAML preview of the configuration that will be written. Click Save config ✓ to write the file. A success notification confirms the path. The app then navigates to the dataset panel for the saved dataset.

For analysts who hand-edit YAML: the app preserves any keys you have added to the YAML file outside the wizard. On the next edit, those keys appear in the Step 8 preview under # preserved from original file and are written back unchanged. The wizard never silently drops hand-added config keys.

Team use via a shared network drive

Multiple users can share the same configuration and run history by pointing their config_dir and snapshot database paths at a shared network folder. Each user runs the app locally; the shared drive holds the YAML configs and the SQLite snapshot database. Set these paths in Global Config on each user’s machine. SQLite handles concurrent reads safely; two simultaneous writes (unlikely in practice) are serialised by file locking.