Virata manual

use

Opens a data file that is already on your computer and puts it in memory.

What we have

  • .dta, .csv and SPSS .sav files, chosen by the file name
  • .json, .jsonl and .ndjson: records found inside a wrapper, nested blocks flattened into columns, repeated groups turned into one row each with a line saying so
  • variable labels and value labels come across from a .dta
  • clear, and a refusal to discard unsaved data without it

Coming later

  • .parquet is read only if you install pyarrow yourself — it is not bundled
  • two repeated groups at once — say which with expand()
  • loading part of a file; the whole file comes into memory
  • fixed-format text (infile, infix) and webuse

How you write it

use "file.dta" [, clear]

Square brackets mean optional. A vertical bar means choose one.

What it does

Virata works on one dataset at a time, held in memory (the data in memory). use is how that dataset gets there. It reads Stata's own .dta files, plain comma-separated text (.csv), SPSS files (.sav), the compressed columnar format .parquet, and .json — and it works out which is which from the file name.

If a dataset is already open, Virata will not quietly throw it away — add clear to say you mean it.

JSON needs a word of its own. Survey platforms and government systems hand out .json files, and Stata cannot read one at all. A JSON file is not a table, so Virata has to make it into one: it finds the records (including when they sit inside a wrapper like {"status": "ok", "data": [...]}), turns a nested block such as address into columns named address_city, and reads files that hold one record per line (.jsonl).

The part to watch is a repeated group — a household carrying a list of its members. Virata turns those into one row each, so 400 households holding 1,800 people become 1,800 rows, and it says so when it does: members expanded: 400 records became 1,800 rows, one per member. Read that line, because after it a row is a person and not a household, and every count, mean and total means something different. If a record carries two repeated groups, Virata stops and asks which one you meant, because expanding both would multiply them together: use "x.json", clear expand(members).

Watch out. Every file name you type is looked for relative to the folder you are currently in (the working directory). pwd tells you where that is and cd moves you. This is the single most common reason a file 'cannot be found' when it is plainly sitting there.

Try it

Every example below was run after sysuse vira.sample02, clear.

. save "kept.dta", replace
file kept.dta saved
The same thing in pandas and in R

pandas

df.to_stata("kept.dta", write_index=False)

R

library(haven)
write_dta(df, "kept.dta")

# This R has NOT been run against a real R yet: read it as documentation.
. use "kept.dta", clear
(6,000 observations read from kept.dta)
The same thing in pandas and in R

pandas

import pandas as pd

df = pd.read_stata("kept.dta")

R

library(haven)
df <- read_dta("kept.dta")

# This R has NOT been run against a real R yet: read it as documentation.

Nearby

save sysuse import export clear browse