← QE npm index — QE Package Index
# 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 →
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.
import { toCSV } from '@qe-libs/refi-qda';
const { csv, report, coders, textColumn } = toCSV(bytes, { coder: 'any' });
bytes: an ArrayBuffer, Uint8Array or Buffer.coder: whose coding becomes the code columns, for projects coded bycodersOf):
| 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.
toCSV(bytes, { DOMParser: require('@xmldom/xmldom').DOMParser }).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).
| Function | Returns |
|---|---|
| `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 |
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.
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:
lines: 'all' keeps every non-empty line of a transcript that hasSpeaker: 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.
unit: 'sentence' makes each sentence of a line a row, with a SentenceLine (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.
minOverlap: n counts a span for a row only when it overlaps the row byn 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.
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.
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.
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).
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