Skip to content
← Documentation

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.