CMAP QDPX Converter

Convert QDPX files from qualitative data analysis (QDA) software into CMAP schema CSV, ready for the CMAP Visualization Toolkit. This is pilot research software, not a production product.

QDPX is the REFI-QDA standard exchange format supported by ATLAS.ti, NVivo, MAXQDA, and other QDA applications.

Quick Start

1. Export a REFI-QDA project from your QDA software:
   • ATLAS.ti: Project > Export > REFI-QDA Project (.qdpx)
   • NVivo: File > Export > Export Project > REFI-QDA format
   • MAXQDA: Project > Export > REFI-QDA Project
2. Clone this repository and enter it:

   git clone https://github.com/Computational-Ethnography-Lab/cmap_qdpx_converter.git
   cd cmap_qdpx_converter

3. Run the converter with a real project name (no install needed — Python 3.8+; developed and tested on 3.11–3.13):

   python3 qda_converter.py /path/to/your_file.qdpx -p my_study

   Windows: use python (or py) instead of python3.

The output your_file_converted.csv is written beside the input. Keep data local: for non-public transcripts, run on your own machine rather than uploading to a shared or cloud environment.

Worked example (bundled synthetic file, safe to share):

python3 qda_converter.py "synth_data_joy&age.qdpx" -p synth_demo

This yields 288 coded segments across 32 sources, with data_group populated from the file's document sets.

Next step: load the resulting CSV directly into the CMAP Visualization Toolkit — no transformation needed (see Output Format).

Configuration

Edit the constants at the top of qda_converter.py:

Setting	Purpose
DEFAULT_PROJECT_NAME	Placeholder name; passing it (or omitting -p) prints a warning.
EXCLUDE_SETS	Document sets to omit from data_group (default: none). Add admin/catch-all sets, e.g. ["z_all"]. Names match exactly and case-sensitively.
CSV_ENCODING_BOM	Write a UTF-8 BOM for Excel. Default False — a BOM breaks the toolkit. Also available as --excel-friendly.

Command-line flags: -p/--project, -o/--output, --keep-temp (retain the extracted folder), --excel-friendly, --version.

Planned (future release): a fuller CLI exposing --exclude-set (repeatable) and related knobs layered over these constants.

Output Format

The CSV has 13 columns:

Column	Description
project	Project identifier (from -p).
number	Sequential segment number (float string).
reference	1-based segment reference.
text	Extracted coded text segment.
document	Source document name.
old_codes	Reserved ([]; no prior-codes concept in QDPX).
start_position	Start character position in the source.
end_position	End character position in the source.
data_group	Document groups for the source (string-formatted list).
text_length	Character count of text.
word_count	Word count of text.
doc_id	project-prefixed segment id.
codes	Applied codes (string-formatted list).

codes and data_group are Python-literal lists (e.g. ['DATA:: Interviews', 'DEMOG:: Older Adults']), matching the toolkit's expected format.

These 13 columns are the canonical CMAP schema. The output passes strict CMapsSchema validation (when the schema is available) and loads directly into the CMAP Visualization Toolkit and other CMAP programs with no transformation — a bare pd.read_csv (no BOM), groupby('project'), and literal-eval faceting all work as-is.

Document Groups (data_group)

data_group is built from REFI-QDA document sets — <Set> elements whose members are sources. Code-sets (sets of codes) are ignored. A source in several sets gets a multi-value list.

• ATLAS.ti (verified): document groups export as sets directly.
• NVivo (inferred): user-created Sets and Case Classifications export; folders do not export to REFI-QDA at all, so a folder-only grouping will not appear — create a Set first.
• MAXQDA (inferred): document groups export as sets; document variables map through the attribute path.

The toolkit's facet filter matches data_group values exactly and case-sensitively against the literal set name (for example DATA:: Interviews), so keep set names stable in your QDA project.

Opening the CSV in Excel or Numbers

The file is clean UTF-8. If curly quotes appear as ’ or similar, the spreadsheet opened it as a legacy encoding — this is a display artifact, not corruption. Import as UTF-8 instead: in Excel, Data > From Text/CSV > choose 65001: Unicode (UTF-8). If you only ever double-click into Excel, run with --excel-friendly (writes a BOM; do not feed that file to the toolkit).

Troubleshooting

• 0 segments / conversion stops: the file may not be a REFI-QDA export (the root namespace must be urn:QDA-XML:project:1.0), or it has no coded quotations. The converter fails loudly rather than writing an empty file.
• Empty data_group: the project has no document sets, or all sets are code-sets. In ATLAS.ti, create document groups and re-export.
• Wrong file type: pass a .qdpx archive, not a bare .qde or .docx.

Requirements

• Python 3.8+ (standard library only — no pip install, no third-party packages). Developed and tested on Python 3.11–3.13. On Windows, use python (or py) in place of python3.

The converter is dependency-free. The optional strict-schema validation step uses the CMAP Visualization Toolkit's own environment when you run it there, but the converter itself never requires pandas or any external package.

The converter runs entirely on your machine and makes no network calls — safe for sensitive or non-public transcripts. QDPX archives are extracted with path-traversal protection. Report security concerns to the Computational Ethnography Lab via the repository issue tracker.

Citation

If you use this software, please cite:

This software:

Abramson, C. M. (2026). CMAP QDPX Converter (Version 1.2.4) [Computer software]. Computational Ethnography Lab. https://github.com/Computational-Ethnography-Lab/cmap_qdpx_converter

Underlying schema methodology:

Abramson, Corey M., Tara Prendergast, Zhuofan Li, and Daniel Dohan. 2026. "Qualitative Research in an Era of Artificial Intelligence: A Pragmatic Approach to Data Analysis, Workflow, and Computation." Annual Review of Sociology. https://doi.org/10.1146/annurev-soc-011824-104836

CMAP Visualization Toolkit:

Abramson, C. M., & Nian, Y. (2025). CMAP Visualization Toolkit. https://doi.org/10.5281/zenodo.17162829

License

Creative Commons Attribution-NonCommercial 4.0 International (CC BY-NC 4.0). Free for academic and non-commercial use with attribution; commercial use requires prior written permission from the copyright holder. See LICENSE.

Format Specification

QDPX follows the REFI-QDA standard: https://www.qdasoftware.org/refi-qda-codebook/