survy 0.1.3

Process, transform and analyze survey-format data with clean and simple API.

survy

Process, transform, and analyze survey-format data with a clean and simple API.

---

📦 Overview

survy is a lightweight Python library built for working efficiently with survey data. It simplifies the full workflow—from raw data ingestion to transformation and analysis—while preserving survey-specific structures like multiselect questions.

---

✨ Features

• 🔹 Multiselect as a first-class concept
• 🔹 Read & write multiple formats: CSV, Excel, JSON, SPSS, etc.
• 🔹 Clean, minimal, and expressive API
• 🔹 Built-in tools for validation, tracking, and analysis

---

🚀 Installation

pip install survy

---

⚡ Quick Demo

Sample data

data.csv

id,Q1,Q2_1,Q2_2,Q2_3
1,a,a,b,
2,b,a,,c
3,a,,b,c

data_compact.csv

id,Q1,Q2
1,a,a;b
2,b,a
3,a,b;c

---

Load and analyze

import survy

# Load dataset with compact multiselect column
survey = survy.read_csv("data.csv")
#or
survey = survy.read_csv(
    "data_compact.csv",
    compact_ids=["Q2"],
    compact_separator=";"
)

# Inspect variable
q1 = survey["Q1"]
print(q1.frequencies)

# Crosstab analysis
crosstab = survy.crosstab(survey["Q1"], survey["Q2"])
print(crosstab)

---

📥 Usage

Load data

survey = survy.read_csv("data.csv")

With compact multiselect:

survey = survy.read_csv(
    "data.csv",
    compact_ids=["Q2"],
    compact_separator=";"
)

---

Get DataFrame

survey.get_df(select_dtype="text", multiselect_dtype="compact")

---

Work with variables

q1 = survey["Q1"]

print(q1.vtype)
print(q1.value_indices)
print(q1.base)
print(q1.frequencies)

---

Update variables

q1.label = "Question 1"
q1.value_indices = {"b": 1, "a": 2}

Batch update:

survey.update([
    {
        "id": "Q1",
        "label": "Question 1",
        "value_indices": {"b": 1, "a": 2}
    }
])

---

Export

survey.to_csv(name="output")
survey.to_spss(name="output")

---

Analyze

crosstab = survy.crosstab(survey["Q1"], survey["Q2"])
print(crosstab)

---

🧠 Design Philosophy

• Keep survey logic explicit (variables, labels, value mappings)
• Treat multiselect questions as a core data type
• Provide a clean abstraction over high-performance data processing

---

🤝 Contributing

Contributions are welcome! Feel free to open issues or submit pull requests.

---

📄 License

MIT License

---

🔗 References

• Powered by Polars for fast data processing

---