Sociogram

About sociograms

A sociogram maps the web of choices, rejections, and alliances within a group — who likes whom, who is isolated, where cliques form. Jacob Moreno introduced the method in 1934 as a clinical tool for group therapy; it has since been adopted by classroom teachers (who use it to detect exclusion and bullying), HR teams (informal influence mapping), and organizational researchers. Unlike an ecomap, which centers on one person's external environment, a sociogram treats every member of the group symmetrically.

Schematex follows the Moreno (1934) sociometry conventions for node roles and edge types, extended with modern social network analysis notations for valence, direction, and weight. This page documents what the parser accepts today.

1. Your first sociogram

The smallest useful sociogram: four people, three different relationship types.

Four rules cover 80% of usage:

1. Start with the keyword sociogram, optionally followed by a quoted title.
2. Each person is a node — declared explicitly with id [label: "…"] or auto-created the first time they appear in an edge.
3. Connect two nodes with an edge operator — <-> (mutual), -> (one-way), -x> (rejection), -.- (neutral). See §3.
4. Optionally declare groups and config lines to control layout and coloring.

Comments must start with # on their own line.

2. Nodes

A node line is id [attr: value, …]. Nodes are also created implicitly when first referenced in an edge — but explicit declaration lets you set labels, groups, and roles.

ID rules. Must match [a-zA-Z][a-zA-Z0-9_-]*. The ID is used internally; the label: attribute sets the display name.

Node attributes:

3. Edges

An edge line is leftId OP rightId optionally followed by [label: "…", weight: N]. Both IDs are auto-registered as nodes if not yet declared.

3.1 Direction and valence

3.2 Weight / strength

Higher weight = thicker line. Use the shorthand operators or override explicitly with [weight: N].

3.3 Edge labels

A -> B [label: "best friend"] — the label appears on the connecting line.

4. Groups

A group block collects nodes into a named subgroup for coloring and layout clustering.

Group syntax:

• group id [label: "…", color: "#hex"] — the group header line.
• Member lines follow, each indented at least 4 spaces, one node per line.
• A non-indented line (or the next group) closes the current group.
• Members can carry their own props: anna [label: "Anna K.", size: large].

Nodes can also be assigned inline: alice [group: girls].

5. Configuration

config: lines tune layout and visual encoding. Each is its own line.

Layout notes:

• circular — nodes evenly spaced on a ring. Best for small groups (≤15).
• force-directed — spring model; clusters emerge automatically. Best for medium-sized groups with distinct subgroups.
• concentric — inner rings hold high-in-degree nodes. Best for showing core-periphery structure.

Circular — uniform ring placement; every node equally visible. Best for small, tightly-knit groups.

Force-directed — spring physics pulls connected nodes together and pushes disconnected ones apart. Subgroups cluster organically.

Concentric — nodes sorted by in-degree; high-centrality nodes appear on inner rings, peripheral nodes on outer rings.

6. Sociometric roles

The parser stores role annotations on nodes. The renderer uses them to apply visual badges — a star marker for star, a dashed border for isolate, and so on.

7. Labels & comments

• Title: sociogram "Study group" — first line only.
• Node label: alice [label: "Alice K."].
• Group label: group boys [label: "Boys"].
• Edge label: alice -> bob [label: "lab partners"].
• Comments: # at the start of a line (after leading whitespace).

8. Reserved words & escaping

Reserved at line start: sociogram (header), group, config:.

Reserved operator tokens — avoid these sequences inside IDs: ->, <-, <->, --, ===, ==>, <==, <===>, -x>, <x-, -x-, <x->, -.>, <.->, -.-.

Strings with spaces must be double-quoted in label: and color: values.

9. Common mistakes

10. Grammar (EBNF)

document       = header (blank | comment | config | group-block | edge | node)*

header         = "sociogram" ( WS quoted-string )? NEWLINE
quoted-string  = '"' any-char-but-quote* '"'

config         = "config:" WS key WS "=" WS value NEWLINE
key            = "layout" | "sizing" | "coloring" | "highlight"

group-block    = "group" WS id ( "[" group-attrs "]" )? NEWLINE
                   ( INDENT≥4 member-line )*
member-line    = id ( "[" node-attrs "]" )? NEWLINE
group-attrs    = group-attr ("," group-attr)*
group-attr     = "label:" quoted-string | "color:" quoted-string

node           = id ( "[" node-attrs "]" )? NEWLINE
node-attrs     = node-attr ("," node-attr)*
node-attr      = "label:" quoted-string
               | "group:" id
               | "role:" role
               | "size:" ("small" | "medium" | "large")

edge           = id WS op WS id ( "[" edge-attrs "]" )? NEWLINE
edge-attrs     = edge-attr ("," edge-attr)*
edge-attr      = "label:" quoted-string | "weight:" number

op             = // positive
                 "<===>" | "===>" | "<==="
               | "<==>"|"==>"|"<=="
               | "===" | "<->" | "->" | "<-" | "--"
               // negative
               | "<x->" | "-x>" | "<x-" | "-x-"
               // neutral
               | "<.->" | "-\.>" | "-.-"

role           = "star" | "isolate" | "bridge" | "neglectee" | "rejected"
id             = [a-zA-Z] [a-zA-Z0-9_-]*
comment        = "#" any NEWLINE

Authoritative source: src/diagrams/sociogram/parser.ts. If this diverges from the parser, the parser wins — please open an issue.

11. Standard compliance

Schematex sociograms follow Moreno (1934) sociometry conventions for node roles (star, isolate, neglectee) and directed-choice semantics. The edge operator set is extended with valence (positive / negative / neutral) and weight levels following modern social network analysis practice (Hanneman & Riddle, 2005).

What is implemented today:

• ✅ Directed, mutual, and undirected edges
• ✅ Positive, negative, and neutral valence operators
• ✅ Four weight levels (1–4) with shorthand operators and [weight: N]
• ✅ Groups with color
• ✅ Node role declarations (star, isolate, bridge, neglectee, rejected)
• ✅ Three layouts: circular, force-directed, concentric
• ✅ Three sizing modes: uniform, in-degree, betweenness
• ⏳ Auto-detected clique highlighting — shaded convex hull (see §13)
• ⏳ Social atom view (ego-centered layout)

References:

• Moreno, J.L. (1934). Who Shall Survive? Foundations of Sociometry, Group Psychotherapy and Sociodrama. Beacon House.
• Hanneman, R.A. & Riddle, M. (2005). Introduction to Social Network Methods. UC Riverside.

12. Related examples

13. Roadmap

Planned — not yet parseable. Do not use these in generated DSL today; the parser will reject or ignore them.

• Auto-detected clique highlighting — shaded convex hull drawn around mutual-choice subgroups of ≥3.
• Bridge auto-detection — role: bridge inferred from betweenness centrality without explicit declaration.
• Social atom view — ego-centered layout where one nominated node sits at the center.
• Reciprocity matrix export — structured table output alongside the diagram.

Track in the GitHub issues if you need any of these sooner.