Skip to content
Framework for Stata
R Python Stata CLI

Data

fw_use

Load a named dataset and check its integrity

fw_use loads a dataset by name. A name is resolved in this order:

  1. A file path, such as inputs/raw/survey.csv. A relative path is tried from the current folder, then from the project root.
  2. An entry in the project's data catalog, such as inputs.raw.survey.
  3. Dot notation: the longest leading part that names a project folder picks the folder, and the rest names the file. inputs.final.analysis is $fw_inputs_final/analysis.dta.

The extension picks the reader: .dta uses use, .csv and .tsv use import delimited, and .xlsx and .xls use import excel, firstrow.

Usage

fw_use name [, clear check(strict|warn|off|accept) options(string)]

Options

Name Default Description
name required

A file path, a catalog name, or a dot name.
clear

Replaces the data in memory.
check(strict|warn|off|accept) strict

Sets the integrity check. warn loads a changed locked dataset with a warning and keeps the old record. off skips the check and the record. accept loads the dataset and records it as it is now, with the new SHA-256, data signature, and time. The lock stays as it was. The file is not rewritten. With the integrity ledger on, it sends the new checksum, as fw_save does. It needs a catalog or dot name.
options(string)

Options passed to use, import delimited, or import excel.

Value

  • r(name): the dataset name
  • r(path): the file
  • r(type): dta, csv, tsv, xlsx, or xls
  • r(sha256): the file checksum, when available
  • r(datasignature): the data signature
  • r(locked): 1 when the dataset is locked
  • r(accepted): 1 when check(accept) recorded the dataset again

Details

Before loading, fw_use computes the file's SHA-256 checksum and compares it with the record from the last fw_save or fw_use. After loading, it compares Stata's datasignature. A dataset that changed stops with error 459 when it is locked, and loads with a warning when it is unlocked. To accept a change to a locked dataset, load it with check(accept). It records the new checksum and data signature and keeps the lock. The file is not rewritten.

The checksum covers the whole file, as in R and Python. A .dta file holds the time it was saved, so saving the same data again with plain save changes the checksum, and a locked dataset then stops with error 459. Save with fw_save, which records the new file, or accept the change with check(accept).

The first read of a name records it. Reads of unlocked datasets update the record, as in R and Python. Records live in .framework/stata-integrity.tsv. Plain file paths are not recorded.

SHA-256 comes from sha256sum or shasum on Linux and macOS and from PowerShell on Windows. Without one, only datasignature is checked. It covers values and variable names. It does not cover labels or notes.

Examples

Not run 

fw_use inputs.raw.survey, clear

A CSV file by path Not run 

fw_use "inputs/raw/visits.csv", clear options(varnames(1))

Accept a change to a locked dataset Not run 

fw_use inputs.raw.survey, clear check(accept)

Related reference