README.md

metadata

title: DiscourseGeometry
emoji: 🧭
colorFrom: green
colorTo: blue
sdk: gradio
sdk_version: 5.49.1
app_file: app.py
pinned: false
license: apache-2.0
short_description: Compare text collections on semantic axes

DiscourseGeometry

Reference implementation of the spatial-geometric framework for discourse comparison (Vallego, 2026, SSRN). Part of the H4rmony Project.

Two collections of texts are placed in the semantic space of a sentence encoder and compared on a primary axis and up to five secondary axes. Each axis is defined by two sets of exemplar texts (pole A, pole B); secondary axes are orthogonalised with Gram-Schmidt in the order given. The default preset reproduces the paper's study (TinyLlama-1.1B-Chat vs its H4rmony fine-tuned version on 60 prompts, four ecosophical axes). An extended preset adds two secondary axes proposed in the paper's §9.2, Non-human Agency and Intergenerational Responsibility (exemplars in extra_axes.py), appended after the paper's three so their results are unchanged.

3D view. Two modes. Semantic map (default, as in SpatialSemanticAnalysis): x = position on a chosen axis (0–100%), y and z = the two main directions in which all texts differ once that axis is removed; the pole exemplars are shown with the collections. Chosen axes: any three axes (primary or secondary), as raw projections or orthogonalised in the chosen order, with each collection's centroid and first principal component.

Documentation. DiscourseGeometry_Documentation.docx explains every input, measure and output.

The six layers

Layer	Question	Reported
Axis validation	Are the axes well defined?	pole separation, separation ÷ mean SD, d′, leave-one-out check, angles between axes, primary–secondary overlap
1 · Primary axis	Where does each collection sit, and did it move?	mean score and position, shift, t-test, Cohen's d, permutation p, optional neutral baseline
2 · Secondary axes	Which dimensions moved?	Gram-Schmidt-projected shifts with Bonferroni correction
3 · Order check	Do the results depend on the Gram-Schmidt order?	GS vs raw shifts and their ratio
4 · Secondary Frobenius	How is the shift spread across the named dimensions?	column norms and shares
5 · Full-space Frobenius	How large is the total difference, and how much do the named axes capture?	‖ΔE‖_F, per-unit shift and consistency, coverage of the primary, secondary and combined subspaces vs random directions, residual
6 · Eigenanalysis	Did the shape and orientation change?	eigenvalues, isotropy, effective dimensionality, PC1 loadings, PC1 angle to the primary axis, principal-axis rotation with permutation test and bootstrap intervals; also in the full space

Designs. Paired: two sets of responses to the same prompts in the same order (paired t-test, Cohen's d_z, sign-flip permutation, per-unit Frobenius as in the paper). Independent: two corpora (Welch t-test, Cohen's d, label permutation, Frobenius as centroid separation with its share along the axes, plus shape difference).

Robustness. The encoder can be switched (all-mpnet-base-v2, bge-base-en-v1.5, e5-base-v2, a multilingual mpnet) to check that findings do not depend on one model.

Scales. Score = dot product with the axis (positive = toward pole A), as in the paper. Position = 0% at the pole B centre, 100% at the pole A centre. Eigenvector signs are arbitrary, so only angles between directions (0–90°) are interpreted.

Generation (optional). The two collections can be generated in the app from a list of prompts with any two Hugging Face causal language models (greedy decoding).

Cite

Vallego, J. (2026). A spatial-geometric framework for discourse comparison: Centroid projection, Frobenius norm, and eigenanalysis in a constructed semantic measurement space. SSRN. https://papers.ssrn.com/sol3/papers.cfm?abstract_id=6387958

Vallego, J. (2026). DiscourseGeometry [Software]. Hugging Face Spaces. https://huggingface.co/spaces/neovalle/DiscourseGeometry