Pedigree

About pedigrees

A pedigree chart is a standardized diagram used in clinical genetics to trace a single condition — or a small set of related conditions — through a family across multiple generations. Unlike a genogram, which records emotional and social texture, a pedigree is purely structural: who is affected, who is a carrier, who has been tested, and who the index case is. Genetic counselors, clinical geneticists, and referring physicians use it to judge inheritance pattern, recurrence risk, and who else in the family should be offered testing.

Schematex follows the Bennett et al. (2022) NSGC recommendations — the most recent update from the National Society of Genetic Counselors — which supersedes the 1995 and 2008 revisions. For background see Wikipedia: Pedigree chart. This page documents what the parser accepts today.

1. Your first pedigree

The smallest clinically useful pedigree: two parents and their affected child.

Four rules cover 80% of usage:

1. Start with the keyword pedigree, optionally followed by a quoted title.
2. Declare each individual on their own line: id [attributes]. Conventionally IDs are I-1, II-3, etc. — Roman-numeral generation, dash, position within the generation.
3. Connect two individuals with a couple operator — -- (mated), == (consanguineous), -/- (separated), ~ (no offspring). See §4.
4. Indent under the couple line to add their children. Any deeper indent works; two spaces is conventional.

Comments must be on their own line, starting with #, //, or Mermaid-style %%. Inline trailing comments will break the parser.

2. Individuals

An individual line is id [attr1, attr2, …]. Attributes are comma-separated, order-independent, all optional.

ID rules. Must match [a-zA-Z][a-zA-Z0-9_-]*. IDs are case-insensitive internally but preserve their original casing as the display label (override with label:"…").

Attributes accepted by the parser today:

3. Shapes, status, markers

3.1 Shapes (Bennett 2022)

Bennett 2022 formalized that square and circle represent assigned sex at birth, not gender identity. If gender identity differs, record it in the label ([female, label: "Trans man (AFAB)"]) — do not change the shape.

3.2 Genetic status (fill)

3.3 Markers

3.4 Life status

Multiple tokens combine: [female, affected, deceased], [male, sab], [unknown, pregnancy, presymptomatic].

4. Couples and children

4.1 Couple operators

The parser tries these in order. The first match wins — so -/- beats --.

4.2 Inline individual on the right side

If the right-hand individual has not been declared yet, declare them in place:

4.3 Children (indented under a couple)

Indentation under a couple line = "these are the children of this couple." Any indent greater than the couple's indent works; two spaces is conventional.

4.4 Consanguineous unions

Consanguinity is rendered as a double line and must be made visible — it is the single most load-bearing piece of information on many pedigrees.

5. Multi-trait pedigrees

For families that carry more than one heritable condition, use legend: lines to define which quadrant of the shape represents which trait, then tag individuals with affected: trait1+trait2.

pedigree "Cancer Family Syndrome"
  legend: breast = "Breast cancer" (fill: quad-tl)
  legend: ovarian = "Ovarian cancer" (fill: quad-tr)
  legend: prostate = "Prostate cancer" (fill: quad-bl)
  legend: colon = "Colon cancer" (fill: quad-br)

  I-1 [male, affected: prostate, deceased]
  I-2 [female, affected: breast, deceased]
  I-1 -- I-2
    II-1 [female, affected: breast+ovarian]
    II-2 [male, unaffected]

Legend syntax: legend: id = "Human label" (fill: POSITION).

Individuals use the legend trait IDs: [affected: breast], [affected: breast+ovarian]. The + joins traits; quadrants fill cumulatively.

6. Labels & comments

• Title: pedigree "BRCA1 Family" — first line only.
• Individual label override: II-1 [female, affected, label: "Jane Smith (42)"].
• Legend entry: legend: id = "Label" (fill: POSITION) — see §5.
• Mode suffix: pedigree:autosomal-dominant "Family X" is accepted. The suffix is stored as metadata.mode; current renderers ignore it.
• Comments: #, //, or %% at the start of a line (after leading whitespace). Inline trailing comments are not supported.

7. Reserved words & escaping

Reserved at line start: pedigree (header), legend: (legend entry).

Reserved operator tokens inside a line — avoid using these sequences in IDs: --, ==, -/-, ~.

Reserved attribute tokens inside […] — the parser will interpret these regardless of position: sex tokens (male, female, unknown, amab, afab, uaab), genetic statuses (affected, carrier, carrier-x, obligate-carrier, presymptomatic, unaffected), markers (proband, consultand, evaluated), and life statuses (deceased, stillborn, pregnancy, sab, tab, ectopic).

Strings with spaces must be double-quoted. Single quotes and backticks are not recognized.

8. Common mistakes

Real parser errors, what triggers them, and how to fix.

9. Grammar (EBNF)

document       = header (blank | comment | legend | individual | couple-block)*

header         = "pedigree" ( ":" mode )? ( WS quoted-string )? NEWLINE
mode           = [A-Za-z] [A-Za-z0-9_-]*
quoted-string  = '"' any-char-but-quote* '"'

legend         = INDENT "legend:" WS id WS "=" WS quoted-string
                   ( WS "(" "fill:" fill-value ")" )? NEWLINE

individual     = INDENT id ( "[" attrs "]" )? NEWLINE
couple-block   = INDENT id WS coupleOp WS right-side NEWLINE
                   ( deeper-indent child )*
child          = INDENT id ( "[" attrs "]" )? NEWLINE
right-side     = id ( "[" attrs "]" )?

coupleOp       = "-/-" | "==" | "--" | "~"

id             = [a-zA-Z] [a-zA-Z0-9_-]*
attrs          = attr ("," attr)*
attr           = sex
               | genetic-status
               | marker
               | life-status
               | digit digit digit digit                         // birth year
               | "label" ":" quoted-string
               | "affected" ":" trait-id ( "+" trait-id )*
               | key ":" value                                    // custom

sex            = "male" | "female" | "unknown" | "amab" | "afab" | "uaab"
genetic-status = "unaffected" | "affected" | "carrier" | "carrier-x"
               | "obligate-carrier" | "presymptomatic"
marker         = "proband" | "consultand" | "evaluated"
life-status    = "deceased" | "stillborn" | "pregnancy"
               | "sab" | "tab" | "ectopic"
fill-value     = "full" | "half-left" | "half-right" | "half-top" | "half-bottom"
               | "quad-tl" | "quad-tr" | "quad-bl" | "quad-br"

comment        = INDENT ( "#" | "//" | "%%" ) any NEWLINE

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

10. Standard compliance

Schematex pedigrees follow Bennett, R.L. et al. (2022), The evolving pedigree: Updating to reflect modern family structures, sex, and gender for shape semantics, status fills, and the proband/consultand conventions. Earlier revisions (Bennett 1995, 2008) remain a valid reference for the classical subset.

What is implemented today vs. the standard:

• ✅ Core shapes (square / circle / diamond) with Bennett 2022 AMAB/AFAB/UAAB semantics
• ✅ Full genetic-status set (affected / carrier / carrier-x / obligate-carrier / presymptomatic / unaffected)
• ✅ Proband, consultand, evaluated markers
• ✅ Life-status modifiers (deceased, stillborn, pregnancy, SAB, TAB, ectopic)
• ✅ Couple operators: mated / separated / consanguineous / no-offspring
• ✅ Multi-trait quadrant fills with legend: entries
• ⏳ Twin notation (monozygotic / dizygotic / unknown zygosity)
• ⏳ Adopted-in / adopted-out bracket notation
• ⏳ Assisted reproduction (donor egg/sperm/embryo, surrogate, IVF)
• ⏳ No-offspring-by-choice and infertility markers

References:

• Bennett, R.L., French, K.S., Resta, R.G., & Austin, J. (2022). Practice resource-focused revision: Standardized pedigree nomenclature update centered on sex and gender inclusivity. Journal of Genetic Counseling, 31(6), 1238–1249.
• Bennett, R.L., Steinhaus French, K., Resta, R.G., & Doyle, D.L. (2008). Standardized human pedigree nomenclature: Update and assessment. J Genet Couns, 17(5), 424–433.
• Bennett, R.L. et al. (1995). Recommendations for standardized human pedigree nomenclature. Am J Hum Genet, 56(3), 745–752.

11. Related examples

Ready-to-use scenarios from the examples gallery:

12. Roadmap

Planned — not yet parseable. Do not use these in generated DSL today; the parser will reject them or store them as unused custom properties.

• Twin notation — twin-mz (monozygotic), twin-dz (dizygotic), twin-unknown.
• Adoption brackets — adopted-in, adopted-out (bracketed shape, dashed line to biological parents).
• Assisted reproduction — donor-egg, donor-sperm, donor-embryo, surrogate, and an ivf annotation on the couple line.
• No-offspring markers — no-children (by choice) and infertile drop-line annotations.
• Gender-identity annotation — a structured attribute distinct from sex, rather than stuffing it into label:.
• Triplets and higher-order births — triplet-mz, triplet-dz.

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