archival-structures 0.1.0__tar.gz

archival_structures-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Marijn Koolen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

archival_structures-0.1.0/PKG-INFO

@@ -0,0 +1,154 @@
+Metadata-Version: 2.4
+Name: archival-structures
+Version: 0.1.0
+Summary: A Python package for analysing and restructuring the output of Automatic Text Recognition (ATR) pipelines.
+License: MIT
+License-File: LICENSE
+Keywords: archives,pagexml,atr,ocr,digital-humanities,document-analysis
+Author: Marijn Koolen
+Author-email: marijn.koolen@gmail.com
+Requires-Python: >=3.11,<3.15
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Image Recognition
+Classifier: Topic :: Text Processing :: Linguistic
+Requires-Dist: fuzzy-search (>=2.5.0,<4.0.0)
+Requires-Dist: hdbscan (>=0.8.44)
+Requires-Dist: ipycanvas (>=0.13.0)
+Requires-Dist: ipywidgets (>=8.1.0)
+Requires-Dist: lxml (>=5.3.0,<7.0.0)
+Requires-Dist: numpy (>=2.3.5,<3.0.0)
+Requires-Dist: opencv-python (>=4.13.0.92)
+Requires-Dist: orjson (>=3.11.7)
+Requires-Dist: pagexml-tools (>=0.8.0,<1.0.0)
+Requires-Dist: pandas (>=2.3.3,<3.0.0)
+Requires-Dist: scikit-image (>=0.26.0)
+Requires-Dist: scikit-learn (>=1.9.0)
+Requires-Dist: torch (>=2.12.0)
+Requires-Dist: transformers (>=5.11.0)
+Requires-Dist: umap-learn (>=0.5.12)
+Project-URL: Homepage, https://github.com/Data-Scopes/archival-structures
+Project-URL: Issues, https://github.com/Data-Scopes/archival-structures/issues
+Project-URL: Repository, https://github.com/Data-Scopes/archival-structures
+Description-Content-Type: text/markdown
+
+# archival-structures
+
+Tools for analysing PageXML/ATR transcriptions and scan images of archival documents:
+detecting and splitting two-page book openings, clustering text lines and page layouts,
+mining cross-page document-element sequences, ink-colour and missing-transcription detection,
+and parsing EAD/METS archival finding-aid metadata.
+
+Full documentation (including the per-module API reference) lives in [`docs/`](docs/) and is
+built with Sphinx; see [Documentation](#documentation) below.
+
+## Techniques and tasks
+
+Archival images and transcriptions are organised as
+`<institute_id>/<archive_id>/<inventory_num_id>/<scan>`. The core idea behind this package is
+that one inventory number's worth of scans is a structured, ordered corpus, not a set of
+independent images -- so the analysis is built up in layers:
+
+1. **Opening detection and splitting** (`archival_structures.analysis.opening_detection`) --
+   decide whether a scan is a two-page spread, split it into independent verso/recto pages, and
+   classify a whole inventory number as a *book of openings* versus a *mixed* folder/booklet.
+2. **Page-layout clustering** (`archival_structures.analysis.page_layout_clustering`) -- cluster
+   whole pages by the spatial arrangement of their text lines, via a grid-pattern TF-IDF
+   fingerprint.
+3. **Line clustering** (`archival_structures.analysis.line_clustering`) -- cluster individual
+   text lines by indentation/width/height into a vocabulary of recurring line types (body text,
+   closing lines, marginalia, ...).
+4. **Sequence-pattern mining** (`archival_structures.analysis.sequence_patterns`) -- order lines
+   into a corpus-wide reading sequence and segment it into document elements, including elements
+   that span a page break.
+
+Tasks 2 and 3 both depend on splitting first (task 1) -- clustering whole two-page scans
+conflates the left and right page's geometry into one coordinate frame.
+
+Alongside the text-analysis pipeline:
+
+- **Ink colour, multi-colour text, and missing transcriptions**
+  (`archival_structures.clustering.colour_clustering`) -- robust ink/paper separation via
+  multiotsu + connected-component shape (resistant to small artefacts like a sticker or stain),
+  screening pages for more than one ink colour via LAB chroma spread, and flagging untranscribed
+  page regions whose pixels look like genuine ink rather than blank paper.
+- **Coordinate-space bridging** (`archival_structures.model.image`,
+  `archival_structures.image`) -- converting between a scan's native pixel coordinates, a
+  thumbnail's, and a canvas rendering of a selection, via an affine `Transform`; converting
+  between PageXML `Coords` and this package's own `Box` type; ipywidgets-based interactive
+  region drawing/tagging.
+- **Ground-truth annotation** (`archival_structures.datasets.annotations`) -- a JSON schema for
+  labelling scans/lines/cross-page elements, plus an ipywidgets notebook app for producing it.
+- **EAD/METS parsing** (`archival_structures.parsers`) -- a separate concern from the
+  PageXML/image pipeline: parsing the archival finding-aid metadata (series/subseries/file
+  structure, page manifests) that describes an archive's holdings.
+
+See [`docs/findings.md`](docs/findings.md) for the concrete, validated-against-real-data lessons
+learned while building this -- several of the choices above (e.g. splitting before clustering,
+chroma spread over luminosity-class counting for multi-colour detection) turned out to matter a
+lot more than they first appeared to.
+
+## Demo notebooks
+
+All in [`notebooks/demo/`](notebooks/demo/):
+
+- [`annotate-scans.ipynb`](notebooks/demo/annotate-scans.ipynb) -- ipywidgets ground-truth
+  annotation app.
+- [`inventory-structure-demo.ipynb`](notebooks/demo/inventory-structure-demo.ipynb) --
+  classifying a whole inventory number as a book of openings vs a mixed folder.
+- [`opening-detection-demo.ipynb`](notebooks/demo/opening-detection-demo.ipynb) -- per-scan
+  opening detection and splitting.
+- [`line-clustering-demo.ipynb`](notebooks/demo/line-clustering-demo.ipynb) and
+  [`line-clustering-table-vs-deeds-demo.ipynb`](notebooks/demo/line-clustering-table-vs-deeds-demo.ipynb)
+  -- clustering text lines by indentation/width, and comparing that across a table-like register
+  versus notary deeds.
+- [`page-layout-clustering-demo.ipynb`](notebooks/demo/page-layout-clustering-demo.ipynb) and
+  [`page-layout-clustering-table-vs-deeds-demo.ipynb`](notebooks/demo/page-layout-clustering-table-vs-deeds-demo.ipynb)
+  -- clustering pages by text-line layout, and the same table-vs-deeds comparison.
+- [`pagexml-image-region-linking.ipynb`](notebooks/demo/pagexml-image-region-linking.ipynb) --
+  drawing PageXML regions on a thumbnail, and converting a manually-drawn selection back into a
+  new PageXML region.
+- [`pagexml-image-multicolour-explorer.ipynb`](notebooks/demo/pagexml-image-multicolour-explorer.ipynb)
+  -- screening a sample of scans for multi-colour text and missing-transcription candidates.
+- [`sequence-patterns-demo.ipynb`](notebooks/demo/sequence-patterns-demo.ipynb) -- mining
+  recurring n-gram patterns and cross-page document elements, comparing the table register
+  against the notary deeds.
+
+### Demo data
+
+The notebooks above need real PageXML/thumbnail data (~341MB across 7 inventory numbers) that
+isn't committed to this repo -- only the package code is. Download `demo-data.zip` from the
+[latest release](https://github.com/Data-Scopes/archival-structures/releases) and extract it at
+the repository root:
+
+```bash
+unzip demo-data.zip -d .
+```
+
+This recreates `data/PageXML/`, `data/thumbs/`, and `data/annotations/` with exactly the
+inventory numbers the demo notebooks reference, so they run unchanged once extracted.
+
+## Installation
+
+```bash
+poetry install
+```
+
+Requires Python >=3.11,<3.15 -- `torch`'s `triton` dependency caps out at Python <3.15, so the
+project's declared Python range matches that rather than the more typical `<4.0`.
+
+## Documentation
+
+Built with Sphinx; requires the optional `docs` dependency group:
+
+```bash
+poetry install --with docs
+cd docs
+make html
+```
+

archival_structures-0.1.0/README.md

@@ -0,0 +1,114 @@
+# archival-structures
+
+Tools for analysing PageXML/ATR transcriptions and scan images of archival documents:
+detecting and splitting two-page book openings, clustering text lines and page layouts,
+mining cross-page document-element sequences, ink-colour and missing-transcription detection,
+and parsing EAD/METS archival finding-aid metadata.
+
+Full documentation (including the per-module API reference) lives in [`docs/`](docs/) and is
+built with Sphinx; see [Documentation](#documentation) below.
+
+## Techniques and tasks
+
+Archival images and transcriptions are organised as
+`<institute_id>/<archive_id>/<inventory_num_id>/<scan>`. The core idea behind this package is
+that one inventory number's worth of scans is a structured, ordered corpus, not a set of
+independent images -- so the analysis is built up in layers:
+
+1. **Opening detection and splitting** (`archival_structures.analysis.opening_detection`) --
+   decide whether a scan is a two-page spread, split it into independent verso/recto pages, and
+   classify a whole inventory number as a *book of openings* versus a *mixed* folder/booklet.
+2. **Page-layout clustering** (`archival_structures.analysis.page_layout_clustering`) -- cluster
+   whole pages by the spatial arrangement of their text lines, via a grid-pattern TF-IDF
+   fingerprint.
+3. **Line clustering** (`archival_structures.analysis.line_clustering`) -- cluster individual
+   text lines by indentation/width/height into a vocabulary of recurring line types (body text,
+   closing lines, marginalia, ...).
+4. **Sequence-pattern mining** (`archival_structures.analysis.sequence_patterns`) -- order lines
+   into a corpus-wide reading sequence and segment it into document elements, including elements
+   that span a page break.
+
+Tasks 2 and 3 both depend on splitting first (task 1) -- clustering whole two-page scans
+conflates the left and right page's geometry into one coordinate frame.
+
+Alongside the text-analysis pipeline:
+
+- **Ink colour, multi-colour text, and missing transcriptions**
+  (`archival_structures.clustering.colour_clustering`) -- robust ink/paper separation via
+  multiotsu + connected-component shape (resistant to small artefacts like a sticker or stain),
+  screening pages for more than one ink colour via LAB chroma spread, and flagging untranscribed
+  page regions whose pixels look like genuine ink rather than blank paper.
+- **Coordinate-space bridging** (`archival_structures.model.image`,
+  `archival_structures.image`) -- converting between a scan's native pixel coordinates, a
+  thumbnail's, and a canvas rendering of a selection, via an affine `Transform`; converting
+  between PageXML `Coords` and this package's own `Box` type; ipywidgets-based interactive
+  region drawing/tagging.
+- **Ground-truth annotation** (`archival_structures.datasets.annotations`) -- a JSON schema for
+  labelling scans/lines/cross-page elements, plus an ipywidgets notebook app for producing it.
+- **EAD/METS parsing** (`archival_structures.parsers`) -- a separate concern from the
+  PageXML/image pipeline: parsing the archival finding-aid metadata (series/subseries/file
+  structure, page manifests) that describes an archive's holdings.
+
+See [`docs/findings.md`](docs/findings.md) for the concrete, validated-against-real-data lessons
+learned while building this -- several of the choices above (e.g. splitting before clustering,
+chroma spread over luminosity-class counting for multi-colour detection) turned out to matter a
+lot more than they first appeared to.
+
+## Demo notebooks
+
+All in [`notebooks/demo/`](notebooks/demo/):
+
+- [`annotate-scans.ipynb`](notebooks/demo/annotate-scans.ipynb) -- ipywidgets ground-truth
+  annotation app.
+- [`inventory-structure-demo.ipynb`](notebooks/demo/inventory-structure-demo.ipynb) --
+  classifying a whole inventory number as a book of openings vs a mixed folder.
+- [`opening-detection-demo.ipynb`](notebooks/demo/opening-detection-demo.ipynb) -- per-scan
+  opening detection and splitting.
+- [`line-clustering-demo.ipynb`](notebooks/demo/line-clustering-demo.ipynb) and
+  [`line-clustering-table-vs-deeds-demo.ipynb`](notebooks/demo/line-clustering-table-vs-deeds-demo.ipynb)
+  -- clustering text lines by indentation/width, and comparing that across a table-like register
+  versus notary deeds.
+- [`page-layout-clustering-demo.ipynb`](notebooks/demo/page-layout-clustering-demo.ipynb) and
+  [`page-layout-clustering-table-vs-deeds-demo.ipynb`](notebooks/demo/page-layout-clustering-table-vs-deeds-demo.ipynb)
+  -- clustering pages by text-line layout, and the same table-vs-deeds comparison.
+- [`pagexml-image-region-linking.ipynb`](notebooks/demo/pagexml-image-region-linking.ipynb) --
+  drawing PageXML regions on a thumbnail, and converting a manually-drawn selection back into a
+  new PageXML region.
+- [`pagexml-image-multicolour-explorer.ipynb`](notebooks/demo/pagexml-image-multicolour-explorer.ipynb)
+  -- screening a sample of scans for multi-colour text and missing-transcription candidates.
+- [`sequence-patterns-demo.ipynb`](notebooks/demo/sequence-patterns-demo.ipynb) -- mining
+  recurring n-gram patterns and cross-page document elements, comparing the table register
+  against the notary deeds.
+
+### Demo data
+
+The notebooks above need real PageXML/thumbnail data (~341MB across 7 inventory numbers) that
+isn't committed to this repo -- only the package code is. Download `demo-data.zip` from the
+[latest release](https://github.com/Data-Scopes/archival-structures/releases) and extract it at
+the repository root:
+
+```bash
+unzip demo-data.zip -d .
+```
+
+This recreates `data/PageXML/`, `data/thumbs/`, and `data/annotations/` with exactly the
+inventory numbers the demo notebooks reference, so they run unchanged once extracted.
+
+## Installation
+
+```bash
+poetry install
+```
+
+Requires Python >=3.11,<3.15 -- `torch`'s `triton` dependency caps out at Python <3.15, so the
+project's declared Python range matches that rather than the more typical `<4.0`.
+
+## Documentation
+
+Built with Sphinx; requires the optional `docs` dependency group:
+
+```bash
+poetry install --with docs
+cd docs
+make html
+```

archival_structures-0.1.0/archival_structures/__init__.py

@@ -0,0 +1,5 @@
+"""Tools for analysing PageXML/ATR transcriptions and scan images of archival documents:
+detecting and splitting two-page book openings, clustering text lines and page layouts,
+mining cross-page document-element sequences, ink-colour and missing-transcription detection,
+and parsing EAD/METS archival finding-aid metadata.
+"""

archival_structures-0.1.0/archival_structures/analysis/allen_interval.py

@@ -0,0 +1,362 @@
+"""Allen Interval Algebra relations between PageXML regions (lines/regions treated as 1D
+horizontal intervals).
+
+`get_allen_interval` classifies a pair of regions into one of the 13 base Allen relations
+(e.g. ``before``, ``meets``, ``overlaps``, ``equal``). `get_extended_allen_interval` further
+splits the asymmetric ``overlaps``/``contains``/``starts``/``finishes`` relations by how much
+of each region is covered (``m`` = most, ``l`` = least), giving the finer-grained
+`EXTENDED_ALLEN_INTERVALS` vocabulary -- useful for distinguishing e.g. a small marginal
+annotation overlapping a body-text line from two lines of comparable width overlapping evenly.
+"""
+
+from collections import Counter
+
+import pagexml.model.physical_document_model as pdm
+from pagexml.helper.pagexml_helper import horizontal_group_lines
+
+
+ALLEN_INTERVALS = {
+    'after', 'meets', 'o',
+    'fi', 'di', 's', 'equal', 'si', 'd', 'f',
+    'oi', 'met by', 'before'
+}
+
+EXTENDED_ALLEN_INTERVALS = {
+    'after', 'meets',
+    'mom', 'mol', 'lom', 'lol',
+    'm', 'mfi', 'lfi',
+    'ldi', 'cdi', 'rdi',
+    'ms', 'ls', 'equal', 'lsi', 'msi',
+    'ld', 'cd', 'rd', 'lf', 'mf',
+    'momi', 'moli', 'lomi', 'loli',
+    'met by', 'before'
+}
+
+
+def get_doc_allen_interval_profile(doc: pdm.PageXMLRegion, use_extended: bool = True):
+    """Frequency count of Allen interval relations between consecutive horizontally-grouped
+    lines of `doc` (each line compared against the previous and next group), giving a profile
+    of how `doc`'s lines relate to their immediate neighbours. Uses
+    `get_extended_allen_interval` if `use_extended`, else the base `get_allen_interval`."""
+    interval_func = get_extended_allen_interval if use_extended else get_allen_interval
+    hor_group_lines = horizontal_group_lines(doc.get_lines())
+    prev_group = None
+    ai_freq = Counter()
+    for ci, curr_group in enumerate(hor_group_lines):
+        if prev_group is not None:
+            ai_freq.update([interval_func(pl, cl) for cl in curr_group for pl in prev_group])
+        if ci < len(hor_group_lines) - 1:
+            next_group = hor_group_lines[ci+1]
+            ai_freq.update([interval_func(cl, nl) for cl in curr_group for nl in next_group])
+        prev_group = curr_group
+    return ai_freq
+
+
+def get_normalised_diff(x: int, y: int, max_diff: int = 0) -> int:
+    """`x - y`, snapped to 0 if the difference is within `max_diff` (treats near-identical
+    boundaries as exactly aligned)."""
+    diff = x - y
+    return 0 if abs(diff) <= max_diff else diff
+
+
+def determine_overlap_relation(region1: pdm.PageXMLDoc, region2: pdm.PageXMLDoc) -> tuple[str | None, str | None]:
+    """For each region, whether the horizontal overlap with the other covers at least half
+    of its own width (``'m'``, most) or less (``'l'``, least). Returns `(None, None)` if the
+    regions don't overlap horizontally at all."""
+    overlap = pdm.get_horizontal_overlap(region1, region2)
+    if overlap == 0:
+        return None, None
+    relation1 = 'm' if overlap / region1.coords.width >= 0.5 else 'l'
+    relation2 = 'm' if overlap / region2.coords.width >= 0.5 else 'l'
+    return relation1, relation2
+
+
+def get_normalised_region_diffs(region1: pdm.PageXMLDoc, region2: pdm.PageXMLDoc) -> tuple[int, int, int, int]:
+    """Left/right boundary differences between `region1` and `region2` (left-vs-left,
+    left-vs-right, right-vs-left, right-vs-right), using baselines if both regions have one,
+    else bounding boxes. These four values are what `get_allen_interval`/
+    `get_extended_allen_interval` branch on to determine the interval relation."""
+    if pdm.has_baseline(region1) and pdm.has_baseline(region2):
+        # only use baseline when both have them, otherwise, use bounding boxes
+        coords1 = region1.baseline
+        coords2 = region2.baseline
+    else:
+        coords1, coords2 = region1.coords, region2.coords
+    l1l2 = get_normalised_diff(coords1.left, coords2.left)
+    l1r2 = get_normalised_diff(coords1.left, coords2.right)
+    r1l2 = get_normalised_diff(coords1.right, coords2.left)
+    r1r2 = get_normalised_diff(coords1.right, coords2.right)
+    return l1l2, l1r2, r1l2, r1r2
+
+
+def get_allen_interval(region1: pdm.PageXMLDoc, region2: pdm.PageXMLDoc,
+                       debug: int = 0):
+    """Determine the (Extended) Allen Interval.
+
+    Use `max_diff` to work with thick boundaries.
+
+    :param region1: a PageXML document with spatial coordinates
+    :param region2: a PageXML document with spatial coordinates
+    :param debug: print debugging info
+    """
+    l1l2, l1r2, r1l2, r1r2 = get_normalised_region_diffs(region1, region2)
+    overlap1, overlap2 = determine_overlap_relation(region1, region2)
+    if debug > 0:
+        print(f"allen_interval.get_extended_allen_interval\n\tl1: left: {pdm.coords_as_span(region1.coords)}")
+        print(f"allen_interval.get_extended_allen_interval\n\tl2: left: {pdm.coords_as_span(region2.coords)}")
+        print(f"allen_interval.get_extended_allen_interval\n\tl1l2: {l1l2}  r1r2: {r1r2}  "
+              f"r1l2: {r1l2}\n\toverlap1: {overlap1}  overlap2: {overlap2}")
+    if l1l2 < 0:
+        if r1r2 < 0:
+            if r1l2 < 0:
+                # --
+                #     --
+                return 'after'
+            elif r1l2 == 0:
+                # ---
+                #    ---
+                return 'meets'
+            else:
+                # ---
+                #  -----
+                return 'o'
+        elif r1r2 == 0:
+            # ------
+            #   ----
+            return "fi"
+        else:
+            # ------
+            #  --
+            return 'di'
+    elif l1l2 == 0:
+        if r1r2 < 0:
+            # ----
+            # ------
+            return 's'
+        elif r1r2 == 0:
+            # no shift, complete overlap (equal)
+            # ------
+            # ------
+            return 'equal'
+        else:
+            # r1r2 > 0
+            # ------
+            # ----
+            return 'si'
+    else:
+        # l1l2 > 0
+        if r1r2 < 0:
+            #  --
+            # ------
+            return 'd'
+        elif r1r2 == 0:
+            #   ----
+            # ------
+            return 'f'
+        else:
+            # r1r2 > 0
+            if l1r2 < 0:
+                #  -----
+                # ---
+                return 'oi'
+            elif l1r2 == 0:
+                #    ---
+                # ---
+                return 'met by'
+            else:
+                #     --
+                # --
+                return 'before'
+
+
+def get_extended_allen_interval(region1: pdm.PageXMLDoc, region2: pdm.PageXMLDoc,
+                                debug: int = 0):
+    """Determine the (Extended) Allen Interval.
+
+    Use `max_diff` to work with thick boundaries.
+
+    :param region1: a PageXML document with spatial coordinates
+    :param region2: a PageXML document with spatial coordinates
+    :param debug: print debugging info
+    """
+    l1l2, l1r2, r1l2, r1r2 = get_normalised_region_diffs(region1, region2)
+    overlap1, overlap2 = determine_overlap_relation(region1, region2)
+    if debug > 0:
+        print(f"allen_interval.get_extended_allen_interval\n\tl1: left: {pdm.coords_as_span(region1.coords)}")
+        print(f"allen_interval.get_extended_allen_interval\n\tl2: left: {pdm.coords_as_span(region2.coords)}")
+        print(f"allen_interval.get_extended_allen_interval\n\tl1l2: {l1l2}  r1r2: {r1r2}  "
+              f"r1l2: {r1l2}\n\toverlap1: {overlap1}  overlap2: {overlap2}")
+    if l1l2 < 0:
+        if r1r2 < 0:
+            if r1l2 < 0:
+                # --
+                #    --
+                return 'after'
+            elif r1l2 == 0:
+                # ---
+                #    ---
+                return 'meets'
+            else:
+                if overlap1 == 'l' and overlap2 == 'm':
+                    # right-shift, shrink, most part 2 overlapped by least part 1 (lom)
+                    # -----
+                    #    ---
+                    return 'lom'
+                elif overlap1 == 'm' and overlap2 == 'l':
+                    # right-shift, stretch, most part 1 overlaps least part 2 (mol)
+                    # ---
+                    #  -----
+                    return 'mol'
+                elif overlap1 == 'm' and overlap2 == 'm':
+                    # right-shift, most part overlaps most part (mom)
+                    # -----
+                    #  -----
+                    return 'mom'
+                elif overlap1 == 'l' and overlap2 == 'l':
+                    # right-shift, least part overlaps least part (lol)
+                    # ----
+                    #    ---
+                    return 'lol'
+                else:
+                    raise ValueError(f"unexpected situation - l1l2: {l1l2}  r1r2: {r1r2}  "
+                                     f"r1l2: {r1l2}  overlap1: {overlap1}  overlap2: {overlap2}")
+        elif r1r2 == 0:
+            if overlap1 == 'm':
+                # right-shift, finished by, most part overlap (mfi)
+                # ------
+                #   ----
+                return 'mfi'
+            elif overlap1 == 'l':
+                # right-shift, finished by, least part overlap (lfi)
+                # ------
+                #     --
+                return "lfi"
+            else:
+                raise ValueError(f"unexpected situation - l1l2: {l1l2}  r1r2: {r1r2}  "
+                                 f"r1l2: {r1l2}  l1r2: {l1r2}  "
+                                 f"overlap1: {overlap1}  overlap2: {overlap2}")
+        else:
+            diff = get_normalised_diff(abs(l1l2), abs(r1r2))
+            if diff < 0:
+                # right-shift, contained by, right-aligned
+                # ------
+                #  --
+                return 'ldi'
+            elif diff == 0:
+                # no shift, contained by, center-aligned
+                # ------
+                #  ----
+                return 'cdi'
+            else:
+                # left-shift, contained by, left-aligned
+                # ------
+                #    --
+                return 'rdi'
+    elif l1l2 == 0:
+        if r1r2 < 0:
+            if overlap2 == 'm':
+                # right-shift, starts, overlaps with most part (ms)
+                # ----
+                # ------
+                return 'ms'
+            elif overlap2 == 'l':
+                # right-shift, starts, overlaps with least part (ls)
+                # --
+                # ------
+                return 'ls'
+            else:
+                raise ValueError(f"unexpected situation - l1l2: {l1l2}  r1r2: {r1r2}  "
+                                 f"r1l2: {r1l2}  l1r2: {l1r2}  "
+                                 f"overlap1: {overlap1}  overlap2: {overlap2}")
+        elif r1r2 == 0:
+            # no shift, complete overlap (equal)
+            # ------
+            # ------
+            return 'equal'
+        else:
+            # r1r2 > 0
+            if overlap1 == 'm':
+                # left-shift, starts, most part overlaps
+                # ------
+                # ----
+                return 'msi'
+            elif overlap1 == 'l':
+                # left-shift, starts, least part overlaps
+                # ------
+                # --
+                return 'lsi'
+            else:
+                raise ValueError(f"unexpected situation - l1l2: {l1l2}  r1r2: {r1r2}  "
+                                 f"r1l2: {r1l2}  l1r2: {l1r2}  "
+                                 f"overlap1: {overlap1}  overlap2: {overlap2}")
+    else:
+        # l1l2 > 0
+        if r1r2 < 0:
+            diff = get_normalised_diff(abs(l1l2), abs(r1r2))
+            if diff < 0:
+                # right-shift, contains, left-aligned
+                #  --
+                # ------
+                return 'ld'
+            elif diff == 0:
+                # no shift, contains, center-aligned
+                #  ----
+                # ------
+                return 'cd'
+            else:
+                # left-shift, contains, right-aligned
+                #    --
+                # ------
+                return 'rd'
+        elif r1r2 == 0:
+            if overlap2 == 'm':
+                # left-shift, finishes, most part overlap (mfi)
+                #   ----
+                # ------
+                return 'mf'
+            elif overlap2 == 'l':
+                # left-shift, finishes, least part overlap (lfi)
+                #     --
+                # ------
+                return 'lf'
+            else:
+                raise ValueError(f"unexpected situation - l1l2: {l1l2}  r1r2: {r1r2}  "
+                                 f"r1l2: {r1l2}  l1r2: {l1r2}  "
+                                 f"overlap1: {overlap1}  overlap2: {overlap2}")
+        else:
+            # r1r2 > 0
+            if l1r2 < 0:
+                if overlap1 == 'l' and overlap2 == 'm':
+                    # left-shift, shrink, least part 2 overlapped by most part 1 (lomi)
+                    #  -----
+                    # ---
+                    return 'lomi'
+                elif overlap1 == 'm' and overlap2 == 'l':
+                    # left-shift, stretch, least part 2 overlaps most part 1 (moli)
+                    #    ---
+                    # -----
+                    return 'moli'
+                elif overlap1 == 'm' and overlap2 == 'm':
+                    # left-shift, most part overlaps most part (momi)
+                    #  -----
+                    # -----
+                    return 'momi'
+                elif overlap1 == 'l' and overlap2 == 'l':
+                    # left-shift, least part overlaps least part (loli)
+                    #    ---
+                    # ----
+                    return 'loli'
+                else:
+                    print(f"region 1: {region1.id} {region1.coords.box_string}")
+                    print(f"region 2: {region2.id} {region2.coords.box_string}")
+                    raise ValueError(f"unexpected situation - l1l2: {l1l2}  r1r2: {r1r2}  "
+                                     f"r1l2: {r1l2}  l1r2: {l1r2}  "
+                                     f"overlap1: {overlap1}  overlap2: {overlap2}")
+            elif l1r2 == 0:
+                #    ---
+                # ---
+                return 'met by'
+            else:
+                #     --
+                # --
+                return 'before'