---
title: 'QRMine: Python CLI for Grounded Theory Research'
url: https://www.emergentmind.com/topics/qrmine-python-cli-module
type: topic
---

# QRMine: Python CLI for Grounded Theory Research

QRMine is an open-source Python package providing command-line and module-based utilities for computational triangulation and the systematic coding of qualitative and quantitative data in Grounded Theory (GT) research. It integrates natural language processing (NLP) and machine learning (ML) techniques to automate and accelerate core GT stages such as open coding, axial coding, selective coding, and triangulation, facilitating the corroboration of qualitative concepts with quantitative evidence. QRMine is available through the Python Package Index (PyPI) and supports extensible pipelines via both a Click-based CLI and a Python API, leveraging libraries such as spaCy, gensim, scikit-learn, and TensorFlow for text and numeric data analysis [2003.13519].

## 1. Installation, Setup, and System Requirements

QRMine is designed for Python 3.6+ environments and is distributed via PyPI. Installation is initiated in a clean virtual environment, created via `venv` or `conda`, followed by `pip install qrmine`. The package requires spaCy and its English “small” language model (`en_core_web_sm`) for linguistic analysis. To enable GPU-accelerated and high-performance numeric computation, optional dependencies include TensorFlow (either CPU or GPU builds) and Keras. The CLI script becomes available on the path after installation, and module APIs can be imported into Python or Jupyter workflows.

**Sample setup instructions:**
```bash
python3 -m venv qrv-env
source qrv-env/bin/activate
pip install qrmine
python -m spacy download en_core_web_sm
```
Optional: `pip install tensorflow keras` for accelerated neural network tasks.

## 2. Command-Line and Module Interfaces

All QRMine operations are invoked via the `qrmine` base command, supplemented with subcommands and flags for distinct GT and ML workflows. Inputs can be plain text (transcripts), CSV (numeric data, identifiers, dependent variables), or combinations thereof. Filtering by topic, sentiment, or specific transcript sections is supported. The CLI supports output to both STDOUT and user-defined files, and most commands accept configurable limits (e.g., top-N categories or number of topics).

The Python module exposes three principal classes:
- `ReadData`: for ingesting and parsing text and CSV data.
- `Qrmine`: encapsulating NLP-based coding and topic modeling.
- `MLQRMine`: providing wrappers for numeric machine learning algorithms (see Section 4).

Typical method signatures include:
```python
from qrmine import ReadData, Qrmine, MLQRMine

texts = ReadData.load_text(['transcript.txt'])
qm = Qrmine(texts)
cat_list = qm.get_categories(n=10)
codedict = qm.build_codedict(n=10)
lda_model, dic, corp = qm.topic_model(num_topics=3)
topic_assignments = qm.assign_topics(lda_model, corp)

df, ids = ReadData.load_csv('data.csv')
ml = MLQRMine(df, id_col='ID')
nn_history = ml.train_nn(epochs=20)
svm_results = ml.train_svm()
clusters = ml.run_kmeans(k=4)
```

Major CLI flags and commands are summarized below:

| Flag / Command          | Functionality                    | Default/Example Value     |
|------------------------|----------------------------------|--------------------------|
| `-i`, `--input`        | Input transcript(s) (txt/CSV)    | `"transcript.txt"`       |
| `--csv`                | Input numeric (CSV) data         | `"data.csv"`             |
| `--cat`                | Top N repeating verbs (open)     | `-n 10` (overrideable)   |
| `--codedict`           | Axial coding dictionary          | `-n 10` (overrideable)   |
| `--topics`             | LDA topic modeling               | `-n 3` (overrideable)    |
| `--assign`             | Assign docs to topics            |                          |
| `--sentiment`          | VADER sentiment analysis         | `--sentence` (optional)  |
| `--nnet`, `--svm`,     | Numeric ML tasks (see Section 4) |                          |
| `--kmeans`, `--knn`,   |                                  |                          |
| `--pca`                |                                  |                          |

## 3. Methodological and Algorithmic Foundations

QRMine operationalizes standard and contemporary ML and NLP methodologies for GT:

- **Textual Coding**: Open coding extracts the most frequent verbs ($V = \{v_1, ..., v_N\}$) via spaCy lemmatization; axial coding generates dictionaries linking verbs to adjacent adjectives/adverbs based on syntactic dependency parse outputs.
- **Topic Modeling**: Implements Latent Dirichlet Allocation (LDA) using a term–document matrix $X \in \mathbb{R}^{D\times T}$ (TF-IDF weighted). LDA is optimized via collapsed Gibbs sampling or variational EM to derive topic–word ($\varphi_k$) and document–topic ($\theta_d$) distributions. Topic assignment assigns each document $d$ to topic $\operatorname{argmax}_k \theta_{d,k}$.
- **Numeric ML**:
  - Neural network classifier fits cross-entropy loss: $L(\theta) = -\sum_{i=1}^N y^{(i)} \log f(x^{(i)};\theta)$.
  - SVM solves: $\min_{w,b} \frac{1}{2}\|w\|^2 + C\sum \xi_i$ subject to $y_i(w{\cdot}x_i + b) \ge 1 - \xi_i, \xi_i \ge 0$.
  - K-means: $\min_C \sum_i \|x_i - \mu_{c_i}\|^2$ for clusters $C$.
  - PCA: Eigen-decompose covariance $\Sigma = E[(x-\mu)(x-\mu)^\top]$, retain principal components.
  - k-NN: Retrieve $k$ nearest neighbours by Euclidean/cosine distance.

- **Computational Triangulation**: After generating topic assignments ($\theta_d$) and numeric structures ($x_d$), similarity is measured, e.g., via cosine similarity: $\cos(\theta_d, x_d) = \frac{\theta_d \cdot x_d}{\|\theta_d\|\|x_d\|}$, thus corroborating qualitative themes with quantitative clusters.

## 4. Principal Features, Data Flows, and GT Stage Mapping

QRMine supports the full GT pipeline:
- **Open Coding**: (`--cat`, `get_categories`) yields frequent verb/concept lists.
- **Axial Coding**: (`--codedict`, `build_codedict`) maps concepts to descriptors.
- **Selective Coding**: (`--topics`, `topic_model`) uncovers latent themes and core categories.
- **Triangulation**: Integration of topic vectors and numeric cluster memberships for corroborative analysis.

Data formats are standardized: plain text (optionally tagged with `<break>TITLE</break>` per section/interview) for transcripts, and CSV for numeric/categorical data (first column: identifier, last: dependent variable, intermediates: features). Outputs are plain-text tables, JSON dictionaries, or structured Python objects, facilitating downstream quantitative-qualitative integration.

A prototypical GT workflow involves:
1. Automatic category extraction and codebook generation.
2. Topic modeling and assignment.
3. Numeric feature reduction (e.g., PCA) or cluster discovery.
4. Quantitative–qualitative alignment via vector similarity or clustering.

## 5. Technical Architecture, Dependencies, and Extensibility

QRMine exhibits a modular, layered architecture with three core modules: `ReadData` for I/O, `Qrmine` for NLP, and `MLQRMine` for numeric ML. The package directory structure is as follows:
- `read_data.py`: Data parsing routines.
- `qrmine.py`: NLP logic and algorithmic wrappers.
- `ml_qrmine.py`: ML abstractions.
- `cli.py`: Command registration (Click decorators).

Major dependencies:

| Functionality                | Libraries                                        |
|------------------------------|-------------------------------------------------|
| NLP preprocessing            | spaCy, textacy                                  |
| Sentiment analysis           | VaderSentiment                                  |
| Topic modeling               | gensim, scikit-learn                            |
| Numeric ML                   | scikit-learn, Keras, TensorFlow, imbalanced-learn, mlxtend |
| CLI                          | Click                                            |

Design patterns such as facade/wrapper abstractions allow QRMine to multiplex over multiple libraries, and modular separation ensures clarity and maintainability. Extensibility is achieved by subclassing Qrmine (to swap NLP/ML methods) or by introducing new CLI commands via Click.

## 6. Integration, Best Practices, and Contribution Guidelines

The recommended integration route for GT researchers is iterative: begin with open coding in QRMine to establish a core concept list; then perform manual review and refinement in external qualitative software as needed. Selective coding via topic modeling assists with theoretical sampling and prioritization of additional data collection. Numeric ML pipelines serve as a computational triangulation stage, allowing GT researchers to cross-validate emergent concepts with quantitative clusters or principal components.

Version control and collaboration are facilitated via the official repository at https://github.com/dermatologist/nlp-qrmine. Contributions proceed by forking, branching, adhering to dev requirements (pytest, black, mypy), testing, and submitting pull requests. Extensibility points in the API and CLI facilitate adaptation to evolving ML and NLP standards.

A plausible implication is that QRMine operationalizes and accelerates the iterative, data-driven nature of GT, aligning the method with the analytical challenges and opportunities posed by contemporary big data research environments [2003.13519].

Source: https://www.emergentmind.com/topics/qrmine-python-cli-module