← QE npm index — QE Package Index

@qe-libs/refi-qda

v0.1.3 · dev 0.1.3-dev.9006 — REFI-QDA projects (.qdpx from NVivo, ATLAS.ti, MAXQDA, QualCoder) as utterance × code tables, in the browser and Node

Depends on: fflate

Install
# Add to .npmrc once:
    @qe-libs:registry=https://gitlab.com/api/v4/projects/22522458/packages/npm/

    # Then install:
    npm install @qe-libs/refi-qda
npm install @qe-libs/refi-qda@dev   # latest dev build
Browse on GitLab Package Registry →

@qe-libs/refi-qda

Reads REFI-QDA projects (.qdpx, exported by NVivo, ATLAS.ti, MAXQDA, QualCoder and others) into the table ENA works on: one row per utterance, a 0/1 column per code. Runs in the browser and in Node; about 6 KB gzipped (the unzip library, fflate, is bundled).

REFI-QDA is the open exchange standard from the Rotterdam Exchange Format Initiative. A .qdpx is a zip of project.qde (XML: codebook, coders, sources, coded spans) and the source texts.

Use

import { toCSV } from '@qe-libs/refi-qda';

const { csv, report, coders, textColumn } = toCSV(bytes, { coder: 'any' });
more than one person (see codersOf):

| coder | Rows | A line is 1 for a code when… | |---|---|---| | 'any' (default) | one per utterance | any coder coded it | | 'all' | one per utterance | every coder coded it | | 'each' | one per utterance per coder, with a Coder column | that row's coder coded it | | 'columns' | one per utterance; each code once per coder, Code [Coder A] | that column's coder coded it | | a coder's name or GUID | one per utterance | that coder coded it |

'each' and 'columns' keep every coder's coding: 'each' so coders can be compared or combined in the model (Coder as a unit or a group), 'columns' so each coder's version of a code can be chosen or compared as codes.

The browser's own DOMParser is used otherwise.

In a page without a bundler, dist/refi-qda.umd.js defines window.RefiQda. CommonJS code gets the same build through require('@qe-libs/refi-qda') (dist/refi-qda.umd.cjs).

FunctionReturns
`codersOf(project)``[{ guid, name, spans }]`: the coders who coded something, with their number of coded spans
`readProject(bytes, { DOMParser })`The project: `codes` (`{ guid, name, parent, parentGuid, codable, description }`, in codebook order), `users`, `sources` (text, variables, coded spans), `skipped`
`toTable(project, { coder, unit, lines, minOverlap })``{ fields, rows, report }`; `report.codebook` is the hierarchy, as `[{ name, parent }]` per code column
`toCSV(bytes, { coder, unit, lines, minOverlap, DOMParser })``{ csv, fields, rows, report, coders, textColumn }`
`writeCSV(fields, rows)`CSV text
Errors are QdaErrors with a code: not-zip, no-project, bad-xml, no-coder, misaligned, no-sources, bad-option. Their messages are written for the person importing.

The table

Columns: Source, Line, UserName (the speaker), Coder (with coder: 'each'), the sources' variables, Text, then one column per codable code in codebook order (a repeated name gets its parent's: Design talk / Cost).

Rows are the transcript lines that look like Speaker: text; a transcript without such lines gives one row per non-empty line. A line is 1 for a code when a span coded with it (by the chosen coder) overlaps the line.

Three options change what a row is:

Speaker: text lines, not only those: a title, or a paragraph that continues the previous speaker, becomes a row with the previous speaker (none before the first). report.notes says how many lines were kept. column after Line (Line stays the line number). A sentence ends at . ? ! …, optional closing quotes or brackets, and a space, except before a lowercase word or after an abbreviation or an initial (Dr., Mme., cf., e.g., J.). The first sentence of a line starts where the line does, so a span over the speaker prefix counts for it. The same overlap rule applies, so a span across two sentences codes both. For notes written as paragraphs, Source and Line together make a good ENA conversation, with a moving window of a few sentences. unit can also be a function (text, start) => [{ start, end, text }] that splits a line's text (after Speaker: ) your own way: start is the text's position in the source, in code points, and each piece's positions are absolute too. The splitter above is the same, character for character, in the Python port. more than n characters, or covers the whole span when the span is that short. Some exports place spans a character or two off, which would code the neighbouring line as well; minOverlap: 2 ignores that without dropping short spans. The default, 0, is any overlap.

Positions

Coded spans are character positions in each source's text, and exporters count them differently: code points, UTF-16 units, or with CRLF line ends as two characters. Each source's spans are checked against the span text the project records, the reading that matches is used, and report.notes says when it isn't plain code points. When fewer than 90% match, the import stops (misaligned) rather than placing codes on the wrong lines.

report also gives counts, the coders, skipped sources (audio, PDF, images) and how many spans were checked.

The codebook's hierarchy

report.codebook keeps the codebook's tree, so a tool can suggest nested codes: one { name, parent } per code column, in column order. name is the column name exactly as in fields (Design talk / Cost, Text (code), Cost [Ann]); parent is the column name of the nearest ancestor that is codable and has a column, or null. A category that can't be coded is skipped and its own parent considered, so `Process > Admin (not codable) > Cost gives Admin / Cost the parent Process. With coder: 'columns'` the parent is the same coder's column (Battery [Ann] → Cost [Ann]). Parents are resolved by the tree, not by name, so two codes called Cost in different branches keep their own parents.

Python

The same importer is available for Python as qe-refi-qda on qe-libs.org: read_project, coders_of, to_table, to_csv, write_csv, with the same output byte for byte. Pure Python, no dependencies, with Table.to_pandas() for a DataFrame.

pip install qe-refi-qda --extra-index-url https://qe-libs.org/py/simple/

from refi_qda import to_csv
r = to_csv("project.qdpx", coder="any")

It releases on python/vX.Y.Z tags; a bare vX.Y.Z releases the npm package only (see python/README.md).

Develop

npm install
npm test        # builds dist/, then runs tests/ (node --test)

tests/fixtures/ holds a small invented project and the CSV expected for each coder; make_sample.py regenerates them. The Python tests in python/tests/ use the same fixtures (cd python && pip install -e '.[test]' && pytest).

Powered by GitLab CI — Package registry — QE Package Index