https://github.com/WizardMac/ReadStat
Command-line tool (+ C library) for converting SAS, Stata, and SPSS files 💾
https://github.com/WizardMac/ReadStat
readstat sas sas7bdat spss stata
Last synced: about 2 months ago
JSON representation
Command-line tool (+ C library) for converting SAS, Stata, and SPSS files 💾
- Host: GitHub
- URL: https://github.com/WizardMac/ReadStat
- Owner: WizardMac
- License: mit
- Created: 2012-07-20T21:17:40.000Z (over 13 years ago)
- Default Branch: dev
- Last Pushed: 2026-01-07T13:32:25.000Z (2 months ago)
- Last Synced: 2026-01-13T02:41:32.843Z (2 months ago)
- Topics: readstat, sas, sas7bdat, spss, stata
- Language: C
- Homepage:
- Size: 2.2 MB
- Stars: 301
- Watchers: 18
- Forks: 78
- Open Issues: 48
-
Metadata Files:
- Readme: README.md
- Changelog: NEWS
- License: LICENSE
Awesome Lists containing this project
- awesome-send - ReadStat_command_Line
README
[](https://github.com/WizardMac/ReadStat/actions)
[](https://ci.appveyor.com/project/evanmiller/readstat/branch/master)
[](https://codecov.io/gh/WizardMac/ReadStat)
[](https://bugs.chromium.org/p/oss-fuzz/issues/list?sort=-opened&can=1&q=proj:readstat)
ReadStat: Read (and write) data sets from SAS, Stata, and SPSS
==
Originally developed for [Wizard](https://www.wizardmac.com/), ReadStat is a
command-line tool and MIT-licensed C library for reading files from popular
stats packages. Supported data formats include:
* SAS: SAS7BDAT (binary file) and XPORT (transport file)
* Stata: DTA (binary file) versions 104-119
* SPSS: POR (portable file), SAV (binary file), and ZSAV (compressed binary)
Supported metadata formats include:
* SAS: SAS7BCAT (catalog file) and .sas (command file)
* Stata: .dct (dictionary file)
* SPSS: .sps (command file)
There is also write support for all the data formats, but not the metadata
formats. *The produced SAS7BDAT files still cannot be read by SAS*, but feel
free to contribute your binary-format expertise here.
For reading in R data files, please see the related
[librdata](https://github.com/WizardMac/librdata) project.
Installation on Unix / macOS
--
Grab the latest [release](https://github.com/WizardMac/ReadStat/releases) and
then proceed as usual:
./configure
make
sudo make install
If you're cloning the repository, first make sure you have autotools installed,
and then run `./autogen.sh` to generate the configure file.
If you're on Mac and see errors about `AM_ICONV` when you run `./autogen.sh`,
you'll need to install [gettext](https://www.gnu.org/software/gettext/).
Installation on Windows
--
ReadStat now includes a Microsoft Visual Studio project file that includes
build targets for the library and tests. See the [VS17](./VS17) folder in
the downloaded release for a "one-click" Windows build.
Alternatively, you can build ReadStat on the command line using an
[msys2](https://msys2.github.io/) environment. After installing msys2,
download some other packages:
pacman -S autoconf automake libtool make mingw-w64-x86_64-toolchain mingw-w64-x86_64-cmake mingw-w64-x86_64-libiconv
Then start a MINGW command line (not the msys2 prompt!) and follow the UNIX
install instructions above for this package.
Language Bindings
--
* Julia: [ReadStat.jl](https://github.com/queryverse/ReadStat.jl)
* Perl 6: [ReadStat.pm6](https://github.com/WizardMac/ReadStat.pm6)
* Python: [pyreadstat](https://github.com/Roche/pyreadstat)
* R: [haven](https://github.com/tidyverse/haven)
* DuckDB: [`read_stat`]()
Docker
--
A dockerized version is available [here](https://github.com/jbn/readstat)
Command-line Usage
--
Standard usage:
readstat [-f]
Where:
* `` ends with `.dta`, `.por`, `.sav`, `.sas7bdat`, or `.xpt`and
* `` ends with `.dta`, `.por`, `.sav`, `.sas7bdat`, `.xpt` or `.csv`
If [libxlsxwriter](http://libxlsxwriter.github.io) is found at compile-time, an
XLSX file (ending in `.xlsx`) can be written instead.
If zlib is found at compile-time, compressed SPSS files (`.zsav`) can be read
and written as well.
Use the `-f` option to overwrite an existing output file.
If you have a plain-text file described by a Stata dictionary file, a SAS
command file, or an SPSS command file, a second invocation style is supported:
readstat
Where:
* `` can be anything
* `` ends with `.dct`, `.sas`, or `.sps`
* `` ends with `.dta`, `.por`, `.sav`, `.xpt`, or `.csv`
If you have a SAS catalog file containing the data set's value labels, you
can use the same invocation:
readstat
Except where:
* `` ends with `.sas7bdat`
* `` ends with `.sas7bcat`
* `` ends with `.dta`, `.por`, `.sav`, `.xpt`, or `.csv`
If the file conversion succeeds, ReadStat will report the number of rows and
variables converted, e.g.
Converted 111 variables and 160851 rows in 12.36 seconds
At the moment value labels are supported, but the finer nuances of converting
format strings (e.g. `%8.2g`) are not.
Command-line Usage with CSV input
--
A prerequisite for CSV input is that the [libcsv](https://github.com/rgamble/libcsv)
library is found at compile time.
CSV input is supported together with a metadata file describing the data:
readstat
The `` should end with `.dta`, `.sav`, or `.csv`.
The `` is a regular CSV file.
The `` is a JSON file describing column types, value
labels and missing values. The easiest way to create such a metadata file is to
use the provided `extract_metadata` program on an existing file:
$ extract_metadata
The schema of this JSON file is fully described in
[variablemetadata_schema.json](variablemetadata_schema.json) using [JSON
Schema](http://json-schema.org/).
The following is an example of a valid metadata file:
{
"type": "SPSS",
"variables": [
{
"type": "NUMERIC",
"name": "citizenship",
"label": "Citizenship of respondent",
"categories": [
{
"code": 1,
"label": "Afghanistan"
},
{
"code": 2,
"label": "Albania"
},
{
"code": 98,
"label": "No answer"
},
{
"code": 99,
"label": "Not applicable"
}
],
"missing": {
"type": "DISCRETE",
"values": [
98,
99
]
}
}
]
}
Here the column `citizenship` is a numeric column with four possible values `1`, `2`, `98`, and `99`.
`1` has the label `Afghanistan`, `2` has `Albania`, `98` has `No answer` and `99` has `Not applicable`.
`98` and `99` are defined as missing values.
Other column types are `STRING` and `DATE`.
All values in `DATE` columns are expected to conform to [ISO 8601 date](https://en.wikipedia.org/wiki/ISO_8601).
Here is an example of `DATE` metadata:
{
"type": "SPSS",
"variables": [
{
"type": "DATE",
"name": "startdate",
"label": "Start date",
"categories": [
{
"code": "6666-01-01",
"label": "no date available"
}
],
"missing": {
"type": "DISCRETE",
"values": [
"6666-01-01",
"9999-01-01"
]
}
}
]
}
Value labels are supported for `DATE`.
The last column type is `STRING`:
{
"type": "SPSS",
"variables": [
{
"type": "STRING",
"name": "somestring",
"label": "Label of column",
"missing": {
"type": "DISCRETE",
"values": [
"NA",
"N/A"
]
}
}
]
}
Value labels are not supported for `STRING`.
Library Usage: Reading Files
--
The ReadStat API is callback-based. It uses very little memory, and is suitable
for programs with progress bars. ReadStat uses
[iconv](https://en.wikipedia.org/wiki/Iconv) to automatically transcode
text data into UTF-8, so you don't have to worry about character encodings.
See src/readstat.h for the complete API. In general you'll provide a filename
and a set of optional callback functions for handling various information and
data found in the file. It's up to the user to store this information in an
appropriate data structure. If a context pointer is passed to the parse_* functions,
it will be made available to the various callback functions.
Callback functions should return `READSTAT_HANDLER_OK` (zero) on success.
Returning `READSTAT_HANDLER_ABORT` will abort the parsing process.
Example: Return the number of records in a DTA file.
```c
#include "readstat.h"
int handle_metadata(readstat_metadata_t *metadata, void *ctx) {
int *my_count = (int *)ctx;
*my_count = readstat_get_row_count(metadata);
return READSTAT_HANDLER_OK;
}
int main(int argc, char *argv[]) {
if (argc != 2) {
printf("Usage: %s \n", argv[0]);
return 1;
}
int my_count = 0;
readstat_error_t error = READSTAT_OK;
readstat_parser_t *parser = readstat_parser_init();
readstat_set_metadata_handler(parser, &handle_metadata);
error = readstat_parse_dta(parser, argv[1], &my_count);
readstat_parser_free(parser);
if (error != READSTAT_OK) {
printf("Error processing %s: %d\n", argv[1], error);
return 1;
}
printf("Found %d records\n", my_count);
return 0;
}
```
Example: Convert a DTA to a tab-separated file.
```c
#include "readstat.h"
int handle_metadata(readstat_metadata_t *metadata, void *ctx) {
int *my_var_count = (int *)ctx;
*my_var_count = readstat_get_var_count(metadata);
return READSTAT_HANDLER_OK;
}
int handle_variable(int index, readstat_variable_t *variable,
const char *val_labels, void *ctx) {
int *my_var_count = (int *)ctx;
printf("%s", readstat_variable_get_name(variable));
if (index == *my_var_count - 1) {
printf("\n");
} else {
printf("\t");
}
return READSTAT_HANDLER_OK;
}
int handle_value(int obs_index, readstat_variable_t *variable, readstat_value_t value, void *ctx) {
int *my_var_count = (int *)ctx;
int var_index = readstat_variable_get_index(variable);
readstat_type_t type = readstat_value_type(value);
if (!readstat_value_is_system_missing(value)) {
if (type == READSTAT_TYPE_STRING) {
printf("%s", readstat_string_value(value));
} else if (type == READSTAT_TYPE_INT8) {
printf("%hhd", readstat_int8_value(value));
} else if (type == READSTAT_TYPE_INT16) {
printf("%hd", readstat_int16_value(value));
} else if (type == READSTAT_TYPE_INT32) {
printf("%d", readstat_int32_value(value));
} else if (type == READSTAT_TYPE_FLOAT) {
printf("%f", readstat_float_value(value));
} else if (type == READSTAT_TYPE_DOUBLE) {
printf("%lf", readstat_double_value(value));
}
}
if (var_index == *my_var_count - 1) {
printf("\n");
} else {
printf("\t");
}
return READSTAT_HANDLER_OK;
}
int main(int argc, char *argv[]) {
if (argc != 2) {
printf("Usage: %s \n", argv[0]);
return 1;
}
int my_var_count = 0;
readstat_error_t error = READSTAT_OK;
readstat_parser_t *parser = readstat_parser_init();
readstat_set_metadata_handler(parser, &handle_metadata);
readstat_set_variable_handler(parser, &handle_variable);
readstat_set_value_handler(parser, &handle_value);
error = readstat_parse_dta(parser, argv[1], &my_var_count);
readstat_parser_free(parser);
if (error != READSTAT_OK) {
printf("Error processing %s: %d\n", argv[1], error);
return 1;
}
return 0;
}
```
Library Usage: Writing Files
--
ReadStat can write data sets to a number of file formats, and uses largely the
same API for each of them. Files are written incrementally, with the header
written first, followed by individual rows of data, and ending with some kind
of trailer. (So the full data file never resides in memory.) Unlike like the
callback-based API for reading files, the writer API consists of function that
the developer must call in a particular order. The complete API can be found in
[readstat.h](./src/readstat.h).
Basic usage:
```c
#include "readstat.h"
/* A callback for writing bytes to your file descriptor of choice */
/* The ctx argument comes from the readstat_begin_writing_xxx function */
static ssize_t write_bytes(const void *data, size_t len, void *ctx) {
int fd = *(int *)ctx;
return write(fd, data, len);
}
int main(int argc, char *argv[]) {
readstat_writer_t *writer = readstat_writer_init();
readstat_set_data_writer(writer, &write_bytes);
readstat_writer_set_file_label(writer, "My data set");
int row_count = 1;
readstat_variable_t *variable = readstat_add_variable(writer, "Var1", READSTAT_TYPE_DOUBLE, 0);
readstat_variable_set_label(variable, "First variable");
/* Call one of:
* readstat_begin_writing_dta
* readstat_begin_writing_por
* readstat_begin_writing_sas7bdat
* readstat_begin_writing_sav
* readstat_begin_writing_xport
*/
int fd = open("something.dta", O_CREAT | O_WRONLY);
readstat_begin_writing_dta(writer, &fd, row_count);
int i;
for (i=0; i