Pyreadstat: Read/Write SAS, SPSS, Stata Files

Warnings

• breaking Older versions of pyreadstat (prior to 1.3.3) may not be compatible with pandas 3.0 due to API changes in pandas. This can lead to errors when reading or writing dataframes.
  Fix: Upgrade pyreadstat to version 1.3.3 or newer to ensure compatibility with pandas 3.0. If you cannot upgrade pyreadstat, consider pinning your pandas version to `<3.0`.
• gotcha Handling character encodings in statistical files (SAS, SPSS, Stata) can be complex. If you encounter encoding errors or corrupted text, explicitly specify the correct encoding when reading files.
  Fix: Use the `encoding` parameter in `read_sas7bdat()`, `read_sav()`, or `read_dta()`. Common encodings include 'latin-1', 'cp1252', 'utf-8'. Example: `pyreadstat.read_sas7bdat('file.sas7bdat', encoding='latin-1')`.
• gotcha Reading very large statistical files can consume significant memory, potentially leading to `MemoryError` as `pyreadstat` loads the entire file into memory. This is particularly relevant for files with millions of rows or numerous columns.
  Fix: Ensure your system has sufficient RAM to accommodate the file size. For extremely large files, consider preprocessing them with other tools (e.g., SAS/SPSS/Stata itself) to extract subsets, or convert them to more memory-efficient formats (like Parquet or Feather) before processing with Python if only specific columns/rows are needed.
• gotcha SAS time variables are often stored as numeric values representing seconds or days since a reference date. pyreadstat attempts to convert these, but specific formats might require custom handling or the `sas_time_is_datetime_format` parameter.
  Fix: If SAS date/time variables are not parsed correctly, inspect the metadata (`meta.variable_formats`) and consider passing `sas_time_is_datetime_format=True` to `read_sas7bdat` if the SAS file explicitly stores datetime types. Otherwise, manual conversion might be necessary post-read.

Install

• pip install pyreadstat Standard installation
• pip install "pyreadstat[polars]" With Polars support (optional)

Imports

• pyreadstat

  import pyreadstat

Quickstart

This quickstart demonstrates how to import pyreadstat, write a simple pandas DataFrame to a SAS .sas7bdat file, and then read it back, illustrating basic data and metadata retrieval. The same `read_*` and `write_*` patterns apply to SPSS and Stata files.

import pyreadstat
import pandas as pd
import os

# Example: Create a dummy SAS file for reading and writing
data = {'col1': [1, 2, 3], 'col2': ['A', 'B', 'C']}
df_to_write = pd.DataFrame(data)
output_file = 'test_sas_file.sas7bdat'

# Write a dummy SAS file
try:
    pyreadstat.write_sas7bdat(df_to_write, output_file)
    print(f"Dummy SAS file '{output_file}' created successfully.")

    # Read the SAS file
    df_read, meta = pyreadstat.read_sas7bdat(output_file)

    print("\nDataFrame read from file:")
    print(df_read)
    print("\nMetadata read from file:")
    print(f"Column Names: {meta.column_names}")
    print(f"Column Labels: {meta.column_labels}")
    print(f"Table Name: {meta.table_name}")

except Exception as e:
    print(f"An error occurred: {e}")
finally:
    if os.path.exists(output_file):
        os.remove(output_file)
        print(f"Cleaned up '{output_file}'.")