Merge pull request dimitri-yatsenko#55 from dimitri-yatsenko/claude/reorganize-diagram-sections-YwHn8

Reorganize diagramming and relationships sections

Author: dimitri-yatsenko

book/30-design/030-foreign-keys.md

@@ -539,8 +539,8 @@ CREATE TABLE order_ (
 `````
 
 ```{seealso}
-For detailed coverage of relationship patterns created by different foreign key placements, see [Relationships](050-relationships.ipynb).
-For visual representation of these relationships, see [Diagramming](060-diagrams.ipynb).
+To see how these foreign key placements appear in schema diagrams, see [Diagramming](040-diagrams.ipynb).
+For detailed coverage of relationship patterns, see [Relationships](050-relationships.ipynb).
 ```
 
 # Association Tables: Many-to-Many Relationships
@@ -647,6 +647,6 @@ In DataJoint, they also establish **workflow dependencies** that prescribe the o
 :class: note
 
 Now that you understand foreign keys and their modifiers:
+- **[Diagramming](040-diagrams.ipynb)** — Learn to read and interpret schema diagrams
 - **[Relationships](050-relationships.ipynb)** — Explore relationship patterns: one-to-one, one-to-many, many-to-many
-- **[Diagramming](060-diagrams.ipynb)** — Learn to read and interpret schema diagrams
 ```

book/30-design/060-diagrams.ipynb book/30-design/040-diagrams.ipynbbook/30-design/060-diagrams.ipynb renamed to book/30-design/040-diagrams.ipynb

@@ -4,37 +4,7 @@
    "cell_type": "markdown",
    "id": "cell-0",
    "metadata": {},
-   "source": [
-    "---\n",
-    "title: Diagramming\n",
-    "---\n",
-    "\n",
-    "# Diagramming: Visualizing Schema Structure\n",
-    "\n",
-    "Schema diagrams are essential tools for understanding and designing DataJoint pipelines.\n",
-    "They provide a visual representation of tables and their dependencies, making complex workflows comprehensible at a glance.\n",
-    "\n",
-    "As introduced in [Relational Workflows](../20-concepts/05-workflows.md), DataJoint schemas form **Directed Acyclic Graphs (DAGs)** where:\n",
-    "\n",
-    "- **Nodes** represent tables (workflow steps)\n",
-    "- **Edges** represent foreign key dependencies\n",
-    "- **Direction** flows from parent (referenced) to child (referencing) tables\n",
-    "\n",
-    "This DAG structure embodies a core principle of the Relational Workflow Model: **the schema is an executable specification**.\n",
-    "Tables at the top are independent entities; tables below depend on tables above them.\n",
-    "Reading the diagram top-to-bottom reveals the workflow execution order.\n",
-    "\n",
-    "```{admonition} Learning Objectives\n",
-    ":class: note\n",
-    "\n",
-    "By the end of this chapter, you will:\n",
-    "- Understand the three line styles and their semantic meanings\n",
-    "- Identify relationship types from diagram structure\n",
-    "- Recognize what diagrams show and don't show\n",
-    "- Use diagram operations to explore large schemas\n",
-    "- Compare DataJoint notation with traditional ER diagrams\n",
-    "```"
-   ]
+   "source": "---\ntitle: Diagramming\n---\n\n# Diagramming: Visualizing Schema Structure\n\nSchema diagrams are essential tools for understanding and designing DataJoint pipelines.\nThey provide a visual representation of tables and their dependencies, making complex workflows comprehensible at a glance.\n\nBuilding on the [Foreign Keys](030-foreign-keys.md) chapter—which covered how foreign key placement affects relationship structure—this chapter focuses on how to **read and interpret** the visual representation of these relationships.\n\nAs introduced in [Relational Workflows](../20-concepts/05-workflows.md), DataJoint schemas form **Directed Acyclic Graphs (DAGs)** where:\n\n- **Nodes** represent tables (workflow steps)\n- **Edges** represent foreign key dependencies\n- **Direction** flows from parent (referenced) to child (referencing) tables\n\nThis DAG structure embodies a core principle of the Relational Workflow Model: **the schema is an executable specification**.\nTables at the top are independent entities; tables below depend on tables above them.\nReading the diagram top-to-bottom reveals the workflow execution order.\n\n```{admonition} Learning Objectives\n:class: note\n\nBy the end of this chapter, you will:\n- Understand the three line styles and their semantic meanings\n- Identify relationship types from diagram structure\n- Recognize what diagrams show and don't show\n- Use diagram operations to explore large schemas\n- Compare DataJoint notation with traditional ER diagrams\n```"
   },
   {
    "cell_type": "markdown",
@@ -1339,6 +1309,12 @@
     "```"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "azttpu2mrwk",
+   "source": "```{admonition} Next Steps\n:class: note\n\nNow that you can read and interpret schema diagrams:\n- **[Relationships](050-relationships.ipynb)** — Explore relationship patterns: one-to-one, one-to-many, many-to-many, hierarchies, and more\n- **[Master-Part Tables](053-master-part.ipynb)** — Special pattern for composite entities\n```",
+   "metadata": {}
+  },
   {
    "cell_type": "markdown",
    "id": "cell-27",
@@ -1382,4 +1358,4 @@
  },
  "nbformat": 4,
  "nbformat_minor": 5
-}
+}

book/30-design/050-relationships.ipynb

@@ -4,30 +4,7 @@
    "cell_type": "markdown",
    "id": "cell-0",
    "metadata": {},
-   "source": [
-    "---\n",
-    "title: Relationships\n",
-    "---\n",
-    "\n",
-    "# Relationships: Modeling Entity Connections\n",
-    "\n",
-    "Relational databases model the real world by representing entities and the **relationships** between them.\n",
-    "While the [Foreign Keys](030-foreign-keys.md) chapter covered how foreign keys enforce referential integrity, this chapter focuses on the **patterns** that emerge from different combinations of uniqueness and referential constraints.\n",
-    "\n",
-    "Understanding these patterns is essential for designing schemas that accurately represent business rules, data dependencies, and workflow structures.\n",
-    "\n",
-    "```{admonition} Learning Objectives\n",
-    ":class: note\n",
-    "\n",
-    "By the end of this chapter, you will:\n",
-    "- Understand how foreign key placement determines relationship cardinality\n",
-    "- Design one-to-one, one-to-many, and many-to-many relationships\n",
-    "- Use association tables for complex relationships\n",
-    "- Build hierarchies and sequences using cascading foreign keys\n",
-    "- Apply the parameterization pattern for method/parameter combinations\n",
-    "- Model directed graphs using renamed foreign keys\n",
-    "```"
-   ]
+   "source": "---\ntitle: Relationships\n---\n\n# Relationships: Modeling Entity Connections\n\nRelational databases model the real world by representing entities and the **relationships** between them.\nBuilding on the [Foreign Keys](030-foreign-keys.md) chapter—which covered referential integrity and foreign key modifiers—and the [Diagramming](040-diagrams.ipynb) chapter—which introduced the visual notation—this chapter focuses on the **patterns** that emerge from different combinations of uniqueness and referential constraints.\n\nUnderstanding these patterns is essential for designing schemas that accurately represent business rules, data dependencies, and workflow structures.\nThroughout this chapter, we'll use diagrams to visualize each pattern, reinforcing the connection between table definitions and their visual representation.\n\n```{admonition} Learning Objectives\n:class: note\n\nBy the end of this chapter, you will:\n- Understand how foreign key placement determines relationship cardinality\n- Design one-to-one, one-to-many, and many-to-many relationships\n- Use association tables for complex relationships\n- Build hierarchies and sequences using cascading foreign keys\n- Apply the parameterization pattern for method/parameter combinations\n- Model directed graphs using renamed foreign keys\n```"
   },
   {
    "cell_type": "markdown",
@@ -1967,38 +1944,7 @@
    "cell_type": "markdown",
    "id": "cell-37",
    "metadata": {},
-   "source": [
-    "# Relationship Summary\n",
-    "\n",
-    "| Pattern | Foreign Key Position | Constraint | Cardinality | Diagram Line |\n",
-    "|---------|---------------------|------------|-------------|--------------|\n",
-    "| One-to-many (reference) | Secondary | None | 1:N | Dashed |\n",
-    "| One-to-many (containment) | Part of PK | None | 1:N | Thin solid |\n",
-    "| One-to-one (extension) | Entire PK | Inherent | 1:1 | Thick solid |\n",
-    "| One-to-one (reference) | Secondary | `unique` | 1:1 | Dashed |\n",
-    "| Optional relationship | Secondary | `nullable` | 1:0..N | Dashed |\n",
-    "| Optional one-to-one | Secondary | `nullable, unique` | 1:0..1 | Dashed |\n",
-    "| Many-to-many | Both in PK | None | M:N | Two thin solids |\n",
-    "\n",
-    "```{admonition} Design Guidelines\n",
-    ":class: tip\n",
-    "\n",
-    "1. **Prefer solid lines** when appropriate—they enable direct joins across levels\n",
-    "2. **Use composite primary keys** for hierarchies to cascade identity\n",
-    "3. **Use association tables** for many-to-many relationships\n",
-    "4. **Use thick solid lines** (extension) when child has no independent meaning\n",
-    "5. **Check table definitions** for `nullable` and `unique`—diagrams don't show them\n",
-    "```\n",
-    "\n",
-    "```{admonition} Next Steps\n",
-    ":class: note\n",
-    "\n",
-    "Now that you understand relationship patterns:\n",
-    "- **[Master-Part Tables](053-master-part.ipynb)** — Special pattern for composite entities\n",
-    "- **[Diagramming](060-diagrams.ipynb)** — Visual representation of relationships\n",
-    "- **[Normalization](055-normalization.ipynb)** — Principles for organizing attributes\n",
-    "```"
-   ]
+   "source": "# Relationship Summary\n\n| Pattern | Foreign Key Position | Constraint | Cardinality | Diagram Line |\n|---------|---------------------|------------|-------------|--------------|\n| One-to-many (reference) | Secondary | None | 1:N | Dashed |\n| One-to-many (containment) | Part of PK | None | 1:N | Thin solid |\n| One-to-one (extension) | Entire PK | Inherent | 1:1 | Thick solid |\n| One-to-one (reference) | Secondary | `unique` | 1:1 | Dashed |\n| Optional relationship | Secondary | `nullable` | 1:0..N | Dashed |\n| Optional one-to-one | Secondary | `nullable, unique` | 1:0..1 | Dashed |\n| Many-to-many | Both in PK | None | M:N | Two thin solids |\n\n```{admonition} Design Guidelines\n:class: tip\n\n1. **Prefer solid lines** when appropriate—they enable direct joins across levels\n2. **Use composite primary keys** for hierarchies to cascade identity\n3. **Use association tables** for many-to-many relationships\n4. **Use thick solid lines** (extension) when child has no independent meaning\n5. **Check table definitions** for `nullable` and `unique`—diagrams don't show them\n```\n\n```{admonition} Next Steps\n:class: note\n\nNow that you understand relationship patterns:\n- **[Master-Part Tables](053-master-part.ipynb)** — Special pattern for composite entities\n- **[Normalization](055-normalization.ipynb)** — Principles for organizing attributes\n```"
   },
   {
    "cell_type": "markdown",
@@ -2391,4 +2337,4 @@
  },
  "nbformat": 4,
  "nbformat_minor": 5
-}
+}