Set Intersection¶

The "setIntersection" transform groups distinct elements by their exact set memberships. It emits a flattened profile-by-set table suitable for co-occurrence matrices, concordance summaries, and set-intersection charts.

Parameters¶

description: Type: string
A description of the transform step. Can be used for documentation and agent context.
element Required: Type: string (field name) | string (field name)[]
Field identifying an element. Multiple fields form a compound identifier.
membership: Type: string (field name)
Optional field containing a Boolean membership value. The values 0 and 1 are also accepted. When omitted, every input row denotes membership.
set Required: Type: string (field name)
Field identifying a set.

Input forms¶

Element and set fields must contain scalar strings, Booleans, or finite numbers.

Sparse input contains one row for each active element–set membership. An absent pair means non-membership:

sample	gene
S1	TP53
S1	KRAS
S2	TP53
S3	PIK3CA

{
  "type": "setIntersection",
  "element": "sample",
  "set": "gene"
}

Dense input may include an explicit membership field. Its values must be true, false, 1, or 0. This form can represent elements that belong to no set:

{
  "type": "setIntersection",
  "element": "sample",
  "set": "gene",
  "membership": "present"
}

Multiple element fields form a compound identity. Repeated rows with the same identity, set, and membership are coalesced. Conflicting memberships for the same element and set are invalid.

Wide binary data can be normalized using "regexFold":

[
  {
    "type": "regexFold",
    "columnRegex": "^(TP53|KRAS|PIK3CA)$",
    "asKey": "gene",
    "asValue": "present"
  },
  {
    "type": "setIntersection",
    "element": "sample",
    "set": "gene",
    "membership": "present"
  }
]

Output¶

The transform emits one row for every observed profile and observed set:

Field	Description
`profileKey`	Bit string encoding the profile in first-observed set order
`profileSize`	Number of distinct elements with exactly this profile
`profileDegree`	Number of active sets in the profile
`set`	Set identifier from the input
`setIndex`	Zero-based index in first-observed set order
`member`	Whether the profile is a member of this set

Only observed profiles are emitted; the transform does not enumerate the power set. Set and profile presentation order can be derived downstream. For example, window can rank profiles by size, while an inclusive set size can be calculated using member ? profileSize : 0 followed by aggregate.

Genomic co-mutation example¶

This example treats samples as elements and mutated genes as sets. Each output row maps directly to one matrix cell: exact profiles are rows, genes are columns, and dark cells indicate membership. The aligned sample count shows how many input samples were collapsed into each exact profile. Hover a cell to inspect the profile size and degree.

{
  "description": "Exact co-mutation profiles across samples.",

  "data": {
    "values": [
      { "sample": "S1", "gene": "TP53" },
      { "sample": "S1", "gene": "KRAS" },
      { "sample": "S2", "gene": "TP53" },
      { "sample": "S3", "gene": "PIK3CA" },
      { "sample": "S3", "gene": "PTEN" },
      { "sample": "S4", "gene": "TP53" },
      { "sample": "S4", "gene": "PIK3CA" },
      { "sample": "S5", "gene": "KRAS" },
      { "sample": "S6", "gene": "TP53" },
      { "sample": "S6", "gene": "KRAS" },
      { "sample": "S7", "gene": "PTEN" },
      { "sample": "S8", "gene": "TP53" },
      { "sample": "S8", "gene": "PIK3CA" }
    ]
  },

  "transform": [
    { "type": "setIntersection", "element": "sample", "set": "gene" }
  ],

  "spacing": 12,
  "resolve": { "scale": { "y": "shared" } },

  "hconcat": [
    {
      "width": { "step": 70 },
      "height": { "step": 32 },
      "title": "Mutated genes",
      "mark": { "type": "rect", "stroke": "white", "strokeWidth": 2 },
      "encoding": {
        "x": {
          "field": "set",
          "type": "nominal",
          "axis": { "title": "Gene", "labelAngle": 0 }
        },
        "y": {
          "field": "profileKey",
          "type": "nominal",
          "axis": { "title": "Exact profile" }
        },
        "color": {
          "field": "member",
          "type": "nominal",
          "scale": {
            "type": "ordinal",
            "domain": [false, true],
            "range": ["#eeeeee", "#333333"]
          },
          "legend": null
        },
        "tooltip": [
          { "field": "profileKey", "title": "Profile" },
          { "field": "profileSize", "title": "Samples" },
          { "field": "profileDegree", "title": "Mutated genes" },
          { "field": "set", "title": "Gene" },
          { "field": "member", "title": "Member" }
        ]
      },
      "name": "profile-memberships"
    },

    {
      "width": 40,
      "height": { "step": 32 },
      "title": "Samples",
      "transform": [{ "type": "filter", "expr": "datum.setIndex == 0" }],
      "mark": { "type": "text", "fontWeight": "bold", "color": "#555" },
      "encoding": {
        "x": { "value": 0.5 },
        "y": { "field": "profileKey", "type": "nominal", "axis": null },
        "text": { "field": "profileSize", "type": "quantitative" }
      },
      "name": "profile-counts"
    }
  ],

  "config": {
    "axis": {
      "labelColor": "#555",
      "titleColor": "#333",
      "titleFontWeight": "normal"
    }
  }
}