From 244a4821c89183dd6a953c790d4a953a66a8e4dd Mon Sep 17 00:00:00 2001
From: Arun Isaac
Date: Fri, 9 Oct 2026 00:26:00 +0100
Subject: Document database schema in the manual.
---
.guix/domagi-website.scm | 34 ++++++++++++++++++--
doc/domagi.dbk | 39 +++++++++++++++++++++++
doc/er.pic | 80 ++++++++++++++++++++++++++++++++++++++++++++++++
doc/schema.pic | 45 +++++++++++++++++++++++++++
4 files changed, 196 insertions(+), 2 deletions(-)
create mode 100644 doc/er.pic
create mode 100644 doc/schema.pic
diff --git a/.guix/domagi-website.scm b/.guix/domagi-website.scm
index 83c785d..c924cab 100644
--- a/.guix/domagi-website.scm
+++ b/.guix/domagi-website.scm
@@ -17,6 +17,7 @@
;;; domagi. If not, see .
(define-module (domagi-website)
+ #:use-module ((gnu packages diagram) #:select (pikchr))
#:use-module ((gnu packages docbook) #:select (docbook-xsltng))
#:use-module ((gnu packages fonts) #:select (font-charter font-fira-code))
#:use-module ((gnu packages haskell-xyz) #:select (pandoc))
@@ -48,7 +49,30 @@
(define domagi-web-manual-en-gexp
(with-imported-modules '((guix build utils))
#~(begin
- (use-modules (guix build utils))
+ (use-modules (guix build utils)
+ (ice-9 popen)
+ (srfi srfi-26)
+ (rnrs io ports))
+
+ (define (call-with-input-pipe command proc)
+ (let ((port #f))
+ (dynamic-wind
+ (lambda ()
+ (set! port (apply open-pipe* OPEN_READ command)))
+ (cut proc port)
+ (lambda ()
+ (unless (zero? (close-pipe port))
+ (error "Command invocation failed" command))))))
+
+ (define (pikchr source svg)
+ (mkdir-p (dirname svg))
+ (call-with-output-file svg
+ (cut display
+ (call-with-input-pipe (list #$(file-append pikchr "/bin/pikchr")
+ "--svg-only"
+ source)
+ get-string-all)
+ <>)))
(setenv "HOME" "/tmp")
(set-path-environment-variable
@@ -65,11 +89,17 @@
(string-append (getcwd) "/doc"))
(invoke #$(file-append python "/bin/python3")
(string-append #$(package-source domagi) "/extractdoc.py"))
+ (chdir "doc")
+ (pikchr "er.pic"
+ (string-append #$output "/media/er.svg"))
+ (pikchr "schema.pic"
+ (string-append #$output "/media/schema.svg"))
(invoke #$(file-append docbook-xsltng "/bin/docbook")
(string-append "--resources:" #$output)
"-xi:on"
"resource-base-uri=/domagi/manual/"
- "-s:doc/domagi.dbk"
+ "mediaobject-output-base-uri=/domagi/manual/media/"
+ "-s:domagi.dbk"
(string-append "-o:" #$output "/dev/en/index.html")))))
(define-public domagi-website
diff --git a/doc/domagi.dbk b/doc/domagi.dbk
index 0888ac1..f2ef70d 100644
--- a/doc/domagi.dbk
+++ b/doc/domagi.dbk
@@ -5,6 +5,45 @@
domagi manual
2026Arun Isaac
+
+ Database Schema
+ domagi uses a SQL schema with the following four tables to represent a pangenome.
+
+
+ segment
+ entity representing pangenome segments
+
+
+ link
+ many-to-many relation between segments representing pangenome links
+
+
+ path
+ entity representing pangenome paths
+
+
+ path_segment
+ many-to-many relation mapping paths to segments associating them with the path at a certain coordinate
+
+
+ The schema and the entity relationship diagram are visualized in and respectively.
+
+ domagi database schema
+
+
+
+
+
+
+
+ domagi entity relationship diagram in Chen's notation
+
+
+
+
+
+
+
Reference
diff --git a/doc/er.pic b/doc/er.pic
new file mode 100644
index 0000000..211126a
--- /dev/null
+++ b/doc/er.pic
@@ -0,0 +1,80 @@
+### domagi --- DuckDB-powered pangenome Swiss Army knife
+### Copyright © 2026 Arun Isaac
+###
+### This file is part of domagi.
+###
+### domagi is free software: you can redistribute it and/or modify it under the
+### terms of the GNU General Public License as published by the Free Software
+### Foundation, either version 3 of the License, or (at your option) any later
+### version.
+###
+### domagi is distributed in the hope that it will be useful, but WITHOUT ANY
+### WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+### FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
+### details.
+###
+### You should have received a copy of the GNU General Public License along with
+### domagi. If not, see .
+
+down
+SegmentId: ellipse "id" italic fill lightgrey
+move 0.5cm
+SegmentName: ellipse "name" fill lightgrey
+move 0.5cm
+SegmentSequence: ellipse "sequence" fill lightgrey
+
+line from SegmentId.e \
+ right 1cm \
+ then down until even with SegmentSequence \
+ then to SegmentSequence.e
+line from SegmentName.e right 2cm
+
+Segment: box "segment" fill mediumslateblue
+line "n" above
+IsIn: diamond "is in" fill coral
+line "n" above thick
+Path: box "path" fill mediumslateblue
+down
+
+line; line right 1cm
+ellipse "id" italic fill lightgrey
+down
+move 0.5cm
+PathName: ellipse "name" fill lightgrey
+line from Path.s \
+ down until even with PathName \
+ then to PathName.w
+
+line from IsIn.s \
+ down \
+ then left
+ellipse "orientation" fill lightgrey width 125%
+down
+move 0.5cm
+IsInStart: ellipse "start" fill lightgrey
+move 0.5cm
+IsInEnd: ellipse "end" fill lightgrey
+line from IsIn.s \
+down until even with IsInStart \
+then to IsInStart.e
+line from IsIn.s \
+down until even with IsInEnd \
+then to IsInEnd.e
+
+move from Segment.n up
+Links: diamond "links" fill coral
+right
+move; move
+ToOrientation: ellipse "to-orientation" fill lightgrey width 175%
+up
+move 0.5cm
+FromOrientation: ellipse "from-orientation" fill lightgrey width 175%
+line from Links.e to ToOrientation.w
+line from FromOrientation.w \
+left 1cm \
+then down until even with ToOrientation
+
+# The space in "n " and " n" is a slight trick to nudge the labels a
+# little.
+line from Links.sw down until even with Segment.n "n " rjust
+line from Links.se down until even with Segment.n " n" ljust
\ No newline at end of file
diff --git a/doc/schema.pic b/doc/schema.pic
new file mode 100644
index 0000000..cdf816c
--- /dev/null
+++ b/doc/schema.pic
@@ -0,0 +1,45 @@
+### domagi --- DuckDB-powered pangenome Swiss Army knife
+### Copyright © 2026 Arun Isaac
+###
+### This file is part of domagi.
+###
+### domagi is free software: you can redistribute it and/or modify it under the
+### terms of the GNU General Public License as published by the Free Software
+### Foundation, either version 3 of the License, or (at your option) any later
+### version.
+###
+### domagi is distributed in the hope that it will be useful, but WITHOUT ANY
+### WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+### FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
+### details.
+###
+### You should have received a copy of the GNU General Public License along with
+### domagi. If not, see .
+
+down
+Segment: box "segment" fill lightgrey
+SegmentId: box "id"
+box "name"
+box "sequence"
+
+Link: box "link" at 8cm right of Segment width 175% fill lightgrey
+LinkFromSegment: box "from_segment" width 175%
+box "from_orientation" width 175%
+LinkToSegment: box "to_segment" width 175%
+box "to_orientation" width 175%
+
+Path: box "path" at 8cm below Segment fill lightgrey
+PathId: box "id"
+box "name"
+
+box "path_segment" at 8cm right of Path width 200% fill lightgrey
+PathSegmentPathId: box "path_id" width 200%
+PathSegmentSegmentId: box "segment_id" width 200%
+box "segment_orientation" width 200%
+box "start" width 200%
+box "end" width 200%
+
+arrow from SegmentId.e to LinkFromSegment.w
+arrow from SegmentId.e to LinkToSegment.w
+arrow from SegmentId.e to PathSegmentSegmentId.w
+arrow from PathId.e to PathSegmentPathId.w
\ No newline at end of file
--
cgit 1.4.1