E-Qual

E-Qual is a local-first desktop application for qualitative research. It combines manual coding, hierarchical codebooks, rich memos, multimedia coding, retrieval, inter-coder reliability, text exploration, local transcription, transparent analysis assistance, visual maps, and publication-oriented exports.

Projects use readable JSON files. Research data stays on the computer running E-Qual unless the researcher explicitly imports a URL, configures a local model endpoint, or exports an exchange package.

See USER_GUIDE.md for the complete feature manual, step-by-step usage instructions, methodological limitations, and guidance for deciding which capabilities should remain in a future simplified version.

Project Status

Version 1.0.2 is a beta research release. Its expanded workflows are functional and tested at the calculation and data-transformation level, but it has not received the years of field testing, accessibility evaluation, performance tuning, and independent methodological validation associated with established commercial CAQDAS products.

• Primary development environment: Windows.
• Source and packaged startup have been validated on Linux.
• GitHub CI is configured for Windows, Linux, and macOS.
• Project files and exports are not encrypted.
• Keep independent, encrypted backups of sensitive projects.

Download

Download E-Qual.exe for Windows or the x86_64 AppImage for Linux from the latest GitHub release. Both packages run without installing Python. Windows SmartScreen may warn about early beta builds because they are not digitally signed; verify the accompanying checksum before opening the file.

On Linux, make the AppImage executable and start it:

chmod +x E-Qual-x86_64.AppImage
./E-Qual-x86_64.AppImage

The beta AppImage targets x86_64 Linux systems with Ubuntu 22.04 or a compatible newer runtime. Native ARM64 packaging is not currently provided.

Release downloads are built automatically from version tags. Source users can follow the installation instructions below.

Major Capabilities

Project safety and governance

• Versioned project schema with automatic migration from legacy projects.
• Atomic project writes to reduce corruption risk.
• Rotating recovery snapshots with a recovery browser.
• Persistent audit log with timestamps, actions, and coder attribution.
• Project and coder identities, owner/coder roles, and active-coder selection.
• Session undo and redo plus persistent recovery history.
• Exchange packages and controlled colleague-project merging.

Sources and multimedia

• Word documents: .docx
• Plain text and transcripts: .txt
• PDF text extraction: .pdf
• Saved web pages: .html, .htm
• Email messages: .eml
• JSON comment collections and social-comment exports: .json
• Web pages imported from a researcher-supplied URL
• Images: PNG, JPEG, BMP, GIF, TIFF, and WebP
• Audio: MP3, WAV, M4A, AAC, FLAC, and OGG
• Video: MP4, MOV, MKV, AVI, WebM, and M4V

PDFs become page-marked text documents. Images support rectangular region coding. Audio and video support millisecond time-range coding and linked playback. Media files are linked by path rather than embedded in project JSON, so archive them with the project.

Coding and organization

• Manual passage coding with overlapping codes.
• Unlimited parent/child code hierarchy.
• Macrothemes and reusable code sets.
• Code definitions, colors, weights, and creator metadata.
• Active-code keyboard coding.
• Coding weights and accepted, suggested, or rejected review status.
• Coding memos and researcher review of automatically created codings.
• Document groups, overlapping document sets, and document variables.
• Interactive thematic maps with persistent layouts.
• Macrotheme–code structure and overlap-based code networks.
• Adaptive macrotheme clusters designed for large codebooks.
• Fast code/macrotheme search, Fit All, simple zoom and pan controls, Small/Normal/Large map sizing, node details, and PNG/SVG/PDF export.
• Whole-cluster dragging for moving a macrotheme and all its codes together.
• Export-only color legend listing every visible code, including when map labels are hidden.

Memos and analytic writing

• Project, document, code, coding, free, and research-journal memos.
• Memo titles, source links, summaries, authors, and timestamps.
• Document-by-code summary matrices.
• Editable analytic summaries and Excel export.
• Source-linked Markdown analysis reports.

Retrieval and qualitative analysis

• Search across documents, codes, coded passages, and memos.
• Filters for codes, macrothemes, documents, variables, and values.
• General statistics and document-by-code matrices.
• Same-document, overlapping-range, and window-based co-occurrence.
• Raw counts, Jaccard, cosine, and overlap-coefficient measures.
• Descriptive thematic-saturation analysis.
• Case comparison by code or macrotheme.
• Inter-coder disagreement review and consensus decisions.

Formal inter-coder reliability

• Automatic code mapping by normalized code name.
• Character-weighted percentage agreement.
• Character-weighted Cohen's kappa by code.
• Shared-document comparison.
• Colleague-only coding acceptance.
• Current-coding rejection with consensus metadata.
• Merge of missing documents, codes, and non-duplicate codings.
• .eqtx teamwork exchange packages.

Reliability values depend on the unitization and code mapping used. Review code mapping, source-text equivalence, and the suitability of kappa for the study before reporting a statistic.

Text Explorer

• Unicode-aware word frequencies.
• Selectable stop-word lists for 17 European languages.
• Editable custom stop-word lists and minimum frequency.
• Keyword-in-context results with source offsets.
• Literal, case-sensitive, and regular-expression search.
• Excel and CSV export.

Local transcription

• faster-whisper transcription on CPU with integer quantization.
• Tiny, base, small, medium, and large-v3 model choices.
• Automatic language detection or an explicit language.
• Incremental audio decoding for long recordings.
• Timestamped segments and synchronized playback.
• Approximate local speaker clustering for a selected speaker count.
• Isolated worker process so native transcription failures do not close E-Qual.

Speaker clustering uses simple acoustic features and k-means. It is approximate diarization—not verified identity recognition—and must be reviewed manually. The selected Whisper model downloads on first use and is cached locally.

Accessibility

• Adjustable interface font size.
• One-click light and dark modes with a consistent application-wide palette.
• Optional high-contrast theme with strong focus outlines.
• Keyboard navigation through native Qt controls.
• Document search, coding, undo, and redo shortcuts.
• Accessible application name and text labels.

Formal screen-reader and WCAG evaluation remains future validation work.

Requirements

• Python 3.10 or newer
• A Qt-capable desktop operating system
• Packages declared in requirements.txt
• Internet access for initial Whisper-model downloads

The primary transcription path uses PyAV wheels containing the necessary FFmpeg libraries on supported systems. A separate system FFmpeg installation is normally unnecessary.

Installation

Clone or download the repository and open a terminal in its directory.

Windows PowerShell

py -m venv .venv
.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -r requirements.txt
python E-Qual.py

If PowerShell prevents activation:

.venv\Scripts\python.exe E-Qual.py

Linux or macOS

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements.txt
python E-Qual.py

Using the Advanced Workspaces

Open the Analysis menu from the bottom toolbar:

Workspace	Purpose
Research Workspace	Code hierarchy, memos, groups, sets, coding review, coders, recovery, summaries
Media Sources	PDF, web, email, image, audio, and video sources
Text Explorer	Multilingual word frequencies and KWIC context search
Teamwork and Inter-coder Reliability	Kappa, consensus, exchange, and project merge
Accessibility Preferences	Light/dark mode, font size, high contrast, and keyboard reference

Existing statistics, saturation, comparison, co-occurrence, retrieval, codebook, cases, maps, and exports remain available.

Keyboard Shortcuts

Shortcut	Action
Ctrl+F	Focus search in the current document
F3 / Shift+F3	Next / previous document-search result
Ctrl+Enter or Ctrl+Return	Apply the active code
Ctrl+Z	Undo the latest project change
Ctrl+Y or Ctrl+Shift+Z	Redo the latest undone change

Data, Privacy, and Backups

E-Qual project JSON can contain source text, codings, memos, variables, bibliographic metadata, audit records, and researcher names. Treat it as sensitive whenever it contains confidential or identifiable material.

• Original source files are not modified.
• Linked media must remain available at its recorded path.
• Removing a project source does not delete its original file.
• Project files and exports are not encrypted.
• Recovery snapshots are stored beside a project in a hidden .<project-name>.backups directory.
• Recently opened paths are stored in ~/.thematic_analysis_recent.json.
• URL import makes an explicit network request.
• Local-model functions send selected text to the configured endpoint.

Use encrypted storage, access control, de-identification, and secure backups as required by the study's ethics, legal, contractual, and institutional rules. Never commit participant data to a public repository.

Methodological Limits

• Coding frequency does not measure conceptual importance.
• Co-occurrence does not demonstrate causality.
• Saturation results depend on document order and codebook development.
• Character-offset coding requires review after substantial text edits.
• Acoustic speaker clustering is approximate.
• Inter-coder metrics require defensible units, mappings, and interpretation.

Testing

Install development requirements and run:

python -m pip install -r requirements-dev.txt
python -m unittest discover -s tests -v
python -m py_compile E-Qual.py equal_*.py

The current suite covers schema migration, atomic persistence, recovery, multilingual word exploration, HTML extraction, active-code behavior, inter-coder agreement, source-linked retrieval, and transcription formatting.

Building a Desktop Executable

The repository includes a PyInstaller specification:

python -m pip install -r requirements-dev.txt
pyinstaller --noconfirm --clean E-Qual.spec

The executable is written to dist/. Build separately on each target operating system; PyInstaller does not cross-compile. Test the resulting build with representative source import, save/reopen, exports, playback, and transcription before distribution.

GitHub Actions runs tests on Windows, Linux, and macOS. Pushing a version tag such as v1.0.2 creates a GitHub release containing E-Qual.exe, the Linux x86_64 AppImage, and their SHA-256 checksums. Release assets use stable names so /releases/latest/download/ links remain valid across future versions.

Repository Structure

.
├── E-Qual.py                            # Application entry point
├── equal_project.py                     # Schema, migration, audit, recovery
├── equal_workspace.py                   # Codes, memos, groups, review, governance
├── equal_media.py                       # PDF/web/email/media import and coding
├── equal_lexical.py                     # Word frequencies and KWIC
├── equal_teamwork.py                    # Reliability, consensus, merge, exchange
├── equal_accessibility.py               # Accessibility preferences
├── equal_transcribe_worker_1_1_2.py     # Isolated transcription worker
├── add_transcript_to_equal_project.py   # Command-line transcript importer
├── tests/                               # Automated test suite
├── E-Qual.spec                          # PyInstaller build specification
├── E-Qual-linux.spec                    # Linux AppImage build specification
├── packaging/linux/                     # AppImage launcher metadata
├── pyproject.toml                       # Project and test-tool metadata
├── requirements.txt                    # Runtime dependencies
├── requirements-dev.txt                # Development/build dependencies
├── LICENSE                              # MIT License
├── CHANGELOG.md                         # User-facing release history
├── RELEASE_CHECKLIST.md                 # Maintainer release procedure
├── SECURITY.md                          # Vulnerability and data-security policy
├── CITATION.cff                         # Machine-readable citation metadata
└── CONTRIBUTING.md                      # Contribution guidelines

Command-Line Transcript Import

python add_transcript_to_equal_project.py \
  --project PROJECT.json \
  --transcript TRANSCRIPT.txt \
  --name interview_01.txt

The helper creates a timestamped backup before modifying the project.

Contributing and Security

Read CONTRIBUTING.md before proposing a change. Report security issues according to SECURITY.md, and never attach confidential research data to a public issue.

Cite E-Qual

If you use E-Qual in research, teaching, or a publication, please cite:

Bonora, M. (2026). E-Qual [Computer software]. Zenodo. https://doi.org/10.5281/zenodo.21999246

Machine-readable citation metadata is available in CITATION.cff.

License

E-Qual is free and open-source software released under the MIT License. You may use, copy, modify, and redistribute it under the terms of that license. The software is provided without warranty.