Diagram¶

Schema visualization

Diagram for DataJoint schemas.

This module provides the Diagram class for constructing derived views of the dependency graph. Diagram supports set operators (+, -, *) for selecting subsets of tables, restriction propagation (cascade, restrict) for selecting subsets of data, and inspection (counts, prune) for viewing those selections.

Mutation operations (delete, drop) live in Table, which uses Diagram internally for graph computation.

Visualization methods (draw, make_dot, make_svg, etc.) require matplotlib and pygraphviz. All other methods are always available.

Diagram ¶

Bases: DiGraph

Schema diagram as a directed acyclic graph (DAG).

Visualizes tables and foreign key relationships derived from connection.dependencies.

Parameters:

Name	Type	Description	Default
`source`	`Table, Schema, or module`	A table object, table class, schema, or module with a schema.	required
`context`	`dict`	Namespace for resolving table class names. If None, uses caller's frame globals/locals.	`None`

Examples:

>>> diag = dj.Diagram(schema.MyTable)
>>> diag.draw()

Operators:

diag1 + diag2 - union of diagrams
diag1 - diag2 - difference of diagrams
diag1 * diag2 - intersection of diagrams
diag + n - expand n levels of successors (children)
diag - n - expand n levels of predecessors (parents)

>>> dj.Diagram(schema.Table) + 1 - 1  # immediate ancestors and descendants

Notes

diagram + 1 - 1 may differ from diagram - 1 + 1. Only tables in activated schemas are displayed. To include tables in downstream schemas that depend on the current schema but haven't been explicitly activated::

conn.dependencies.load_all_downstream()
dj.Diagram(schema)  # now includes all downstream schemas

Diagram.cascade() calls load_all_downstream() automatically.

Layout direction is controlled via dj.config.display.diagram_direction (default "TB"). Use dj.config.override() to change temporarily::

with dj.config.override(display_diagram_direction="LR"):
    dj.Diagram(schema).draw()

from_sequence `classmethod` ¶

from_sequence(sequence)

Create combined Diagram from a sequence of sources.

Parameters:

Name	Type	Description	Default
`sequence`	`iterable`	Sequence of table objects, classes, or schemas.	required

Returns:

Type	Description
`Diagram`	Union of diagrams: `Diagram(arg1) + ... + Diagram(argn)`.

add_parts ¶

add_parts()

Add part tables of all masters already in the diagram.

Returns:

Type	Description
`Diagram`	New diagram with part tables included.

collapse ¶

collapse()

Mark all nodes in this diagram as collapsed.

Collapsed nodes are shown as a single node per schema. When combined with other diagrams using +, expanded nodes win: if a node is expanded in either operand, it remains expanded in the result.

Returns:

Type	Description
`Diagram`	A copy of this diagram with all nodes collapsed.

Examples:

>>> # Show schema1 expanded, schema2 collapsed into single nodes
>>> dj.Diagram(schema1) + dj.Diagram(schema2).collapse()

>>> # Collapse all three schemas together
>>> (dj.Diagram(schema1) + dj.Diagram(schema2) + dj.Diagram(schema3)).collapse()

>>> # Expand one table from collapsed schema
>>> dj.Diagram(schema).collapse() + dj.Diagram(SingleTable)

cascade `classmethod` ¶

cascade(table_expr, part_integrity='enforce')

Create a cascade diagram for a table expression.

Builds a Diagram from the table's dependency graph, includes all descendants (across all loaded schemas), and propagates the restriction downstream using OR convergence — a child row is affected if any restricted ancestor taints it.

Parameters:

Name	Type	Description	Default
`table_expr`	`QueryExpression`	A (possibly restricted) table expression (e.g., `Session & 'subject_id=1'`).	required
`part_integrity`	`str`	`"enforce"` (default), `"ignore"`, or `"cascade"`.	`'enforce'`

Returns:

Type	Description
`Diagram`	New Diagram with cascade restrictions applied, trimmed to the seed table and its affected descendants.

Examples:

>>> # Preview cascade impact across all downstream schemas
>>> dj.Diagram.cascade(Session & 'subject_id=1').counts()

>>> # Inspect the cascade subgraph
>>> dj.Diagram.cascade(Session & 'subject_id=1')

restrict ¶

restrict(table_expr)

Apply restrict condition and propagate downstream.

AND at convergence — a child row is included only if it satisfies all restricted ancestors. Used for export. Can be chained.

Cannot be called on a Diagram produced by Diagram.cascade().

Parameters:

Name	Type	Description	Default
`table_expr`	`QueryExpression`	A restricted table expression.	required

Returns:

Type	Description
`Diagram`	New Diagram with restrict conditions applied.

counts ¶

counts()

Return affected row counts per table without modifying data.

Returns:

Type	Description
`dict[str, int]`	Mapping of full table name to affected row count.

prune ¶

prune()

Remove tables with zero matching rows from the diagram.

Without prior restrictions, removes physically empty tables. After restrict(), removes tables where the restricted query yields zero rows. Cannot be used on a cascade Diagram (cascade is for delete, where zero-count tables must remain in the graph to handle concurrent inserts safely).

Returns:

Type	Description
`Diagram`	New Diagram with empty tables removed.

make_dot ¶

make_dot()

Generate a pydot graph object.

Returns:

Type	Description
`Dot`	The graph object ready for rendering.

Raises:

Type	Description
`DataJointError`	If pygraphviz/pydot is not installed.

Notes

Layout direction is controlled via dj.config.display.diagram_direction. Tables are grouped by schema, with the Python module name shown as the group label when available.

make_mermaid ¶

make_mermaid()

Generate Mermaid diagram syntax.

Produces a flowchart in Mermaid syntax that can be rendered in Markdown documentation, GitHub, or https://mermaid.live.

Returns:

Type	Description
`str`	Mermaid flowchart syntax.

Notes

Layout direction is controlled via dj.config.display.diagram_direction. Tables are grouped by schema using Mermaid subgraphs, with the Python module name shown as the group label when available.

Examples:

>>> print(dj.Diagram(schema).make_mermaid())
flowchart TB
    subgraph my_pipeline
        Mouse[Mouse]:::manual
        Session[Session]:::manual
        Neuron([Neuron]):::computed
    end
    Mouse --> Session
    Session --> Neuron

save ¶

save(filename, format=None)

Save diagram to file.

Parameters:

Name	Type	Description	Default
`filename`	`str`	Output filename.	required
`format`	`str`	File format (`'png'`, `'svg'`, or `'mermaid'`). Inferred from extension if None.	`None`

Raises:

Type	Description
`DataJointError`	If format is unsupported.

Notes

Layout direction is controlled via dj.config.display.diagram_direction. Tables are grouped by schema, with the Python module name shown as the group label when available.

Diagram¶

Diagram ¶

from_sequence classmethod ¶

add_parts ¶

collapse ¶

cascade classmethod ¶

restrict ¶

counts ¶

prune ¶

make_dot ¶

make_mermaid ¶

save ¶

from_sequence `classmethod` ¶

cascade `classmethod` ¶