docs/representation-family.md
The minimal set of representations
Not "which layout is prettiest" but which representations carry information no other carries. A representation earns its place iff some fact is recoverable from it and from nothing else.
Measured on this repository: 178 subjects, 8 districts, 1263 couplings.
Recovery matrix
What a reader can get back out of each view.
| fact | A control | B treemap | C map | D linear |
|---|---|---|---|---|
| bytes per subject | height, r=0.96 | area, exact | height, r=0.96 | height, r=0.96 |
| directory (at drawn depth) | ring + accent | nesting, exact | block, exact | colour |
| coupling order, global | exact | — | 85.4% pairwise | exact |
| coupling distance | see below | — | — | — |
| edge existence | — | — | — | top 120 = 9.5% of edges, 29.7% of flow |
| activity | emissive | — | — | — |
Two structural results
1 · A is strictly dominated by D. A's positions lie on a line: its axis correlates with its own rank order at r = 0.9937, so it carries an ordering and not a plane. The only thing A could add over a plain ordering is spacing — and spacing recovers coupling distance no better than uniform rank spacing (r = −0.416 vs −0.406, and both figures are dominated by the unreachable stand-in, so neither is evidence of anything). A therefore carries {order, bytes, directory, activity}; D carries all of those plus edge existence. A has no unique information. It should be retired, not tuned.
2 · C is contained in B ∪ D. C claims directory (which B states exactly) and coupling order (which D states exactly and globally). There is no fact recoverable from C that is not recoverable from B and D together. C earns its place on comprehension, not on information — which is a legitimate reason, and must be stated as that rather than dressed as a truth claim.
So the minimal information-bearing set is {B, D}. C is a comprehension-optimised recombination of what they already carry.
The correction that nearly became a finding
Raw correlation said coupling distance rises with positional separation —
i.e. the layout places coupled files apart. That would have been a severe
finding and it was false. symmetrise substitutes a finite stand-in (186.0)
for unreachable pairs, and that value dominated the near buckets: 58–71% of
adjacent and near pairs are unreachable stand-ins against 12.4% of far pairs.
On genuinely-connected pairs only, the ordering is monotonic:
| separation | % at stand-in | mean coupling distance |
|---|---|---|
| adjacent | 58.2% | 19.49 |
| near | 70.5% | 22.57 |
| mid | 71.2% | 29.90 |
| far | 12.4% | 35.89 |
The coupling ordering is coherent. Near really is more coupled. C's central claim survives; the control's spacing claim does not.
What each hypothesis says the repository IS
| the repository is… | first-class | secondary | likely false inference | |
|---|---|---|---|---|
| A | a place with distances | none | everything | "these two are near, so they are related" — the spacing does not support it |
| B | a hierarchy of sizes | bytes, containment | everything relational | "adjacent cells are related" — adjacency in a treemap is packing, not meaning |
| C | neighbourhoods in an order | containment, local order | magnitude (width is member count, not bytes) | "block width is size" — it is population |
| D | one ordering with jumps | order, strong edges | magnitude, containment | "the 120 arcs are the couplings" — they are 9.5% of them |
The gap none of them fills
Every candidate renders one revision. The ChangeSet is the system's
temporal model and no view exposes it beyond a two-revision comparison —
the review walk visits changes one at a time and shows no history. That is
information the system already computes and no representation carries, which is
the only unmet claim to uniqueness on this page.
A fifth view — evolution over many revisions — is the one addition that would earn its place on information rather than on legibility. It is not built.
Standing
Retire A as the default. It has no unique information and one measurably false claim.
This is a claim about A, not about cities. What is established is that this geometric encoding — MDS over co-change, drawn as a plane — is information-dominated by other encodings of the same facts. Nothing here tests whether a spatial encoding built from other measured primitives (containment depth, temporal evolution, agent activity) could earn its place. That question is open and this file does not answer it.
B and D are the information-bearing pair.
C is worth building for comprehension, labelled as such.
Timeline is the only genuinely missing view.
None of this has been read by a human. Every legibility judgement here is my reading of my own output, which condition 3 says cannot be self-certified.