LGVISIUM-102: common parent class "Sidebar" for LayerIdentifierColumn and DepthColumn

[stijnvermeeren-swisstopo]

A lot of lines changes, but a lot of it is simple renaming, moving code to different files and documentation.

Main renamed classes:

• BoundaryDepthColumn -> AAboveBSidebar
• LayerDepthColumn -> AToBSidebar
• LayerIdentifierColumn -> LayerIdentifierSidebar

These three classes now extend from a common parent class (Sidebar).
Logic for finding these different "sidebars" in borehole profiles is contained in respective SidebarExtractor classes.
Code for all of these is now more cleanly contained in a single sidebar package.

The bounding boxes for depth columns and material descriptions, that are part of the predictions.json output, are now more elegantly represented by a new class BoundaryBoxes, removing the need to implement JSON serialization logic from the actual Sidebar (formerly DepthColumn) classes.

There is a very small / almost negligible effect on the benchmarking scores, caused by the fact that we no longer automatically reject material descriptions to which we cannot associate any depth interval.

This PR also updates the documentation for the predictions.json format, moving it to a separate markdown file, and removing a few redundant entries from the JSON output

[github-actions]

Coverage Report

File	Stmts	Miss	Cover	Missing
src/stratigraphy
__init__.py	8	1	88%	11
extract.py	167	167	0%	3–446
get_files.py	19	19	0%	3–47
main.py	114	114	0%	3–307
src/stratigraphy/benchmark
metrics.py	59	42	29%	22–25, 29–32, 36–39, 46–49, 53–54, 58, 65–74, 78–91, 96–133
src/stratigraphy/data_extractor
data_extractor.py	74	4	95%	33, 46, 123, 168
src/stratigraphy/depthcolumn
depthcolumnentry.py	68	12	82%	21, 25, 37, 71–72, 86, 95, 107–109, 130, 143
src/stratigraphy/depths_materials_column_pairs
bounding_boxes.py	30	10	67%	23, 32, 50, 60, 72–78
material_description_rect_with_sidebar.py	18	8	56%	27–41
src/stratigraphy/evaluation
evaluation_dataclasses.py	49	11	78%	52, 71–74, 90, 104, 125–131, 147
groundwater_evaluator.py	48	1	98%	77
layer_evaluator.py	66	46	30%	29–30, 35–39, 47, 69–95, 105–113, 128–149
metadata_evaluator.py	37	14	62%	46–65, 86–93
utility.py	16	7	56%	43–52
src/stratigraphy/groundwater
groundwater_extraction.py	156	99	37%	52, 94, 127–132, 140, 167–171, 186–206, 217–306, 322–354
utility.py	39	33	15%	10–17, 30–47, 59–73, 88–102
src/stratigraphy/layer
layer.py	37	13	65%	26, 29, 37, 52–72
src/stratigraphy/lines
geometric_line_utilities.py	86	2	98%	81, 131
line.py	51	4	92%	25, 50, 60, 110
linesquadtree.py	46	1	98%	75
src/stratigraphy/metadata
coordinate_extraction.py	106	4	96%	29, 93–94, 106
elevation_extraction.py	90	60	33%	34–39, 47, 55, 63, 79–87, 124–138, 150–153, 165–197, 212–220, 228–232
language_detection.py	18	13	28%	17–23, 37–45
metadata.py	66	24	64%	27, 83, 101–127, 146–155, 195–198, 206
src/stratigraphy/sidebar
a_above_b_sidebar.py	95	40	58%	39, 45, 64–72, 83, 88, 95, 108, 113–120, 135–136, 178–219
a_above_b_sidebar_extractor.py	29	3	90%	45–47
a_above_b_sidebar_validator.py	41	20	51%	48, 58, 61, 81–84, 109–127, 139–148
a_to_b_sidebar.py	47	16	66%	37, 40, 53–54, 71, 99–114
layer_identifier_sidebar.py	51	32	37%	23–24, 27, 59–78, 94–110, 122, 135
layer_identifier_sidebar_extractor.py	42	33	21%	30–40, 54–86
sidebar.py	40	1	98%	84
src/stratigraphy/text
description_block_splitter.py	70	2	97%	24, 139
extract_text.py	29	3	90%	19, 53–54
find_description.py	41	8	80%	26–34, 111–114
textblock.py	90	11	88%	22, 27, 39, 44, 71, 79, 104, 116, 139, 160, 189
src/stratigraphy/util
dataclasses.py	32	3	91%	37–39
interval.py	114	65	43%	28–31, 36–39, 45, 51, 55, 94–140, 157, 163–179, 196–214
predictions.py	72	34	53%	72, 95–115, 143–187
util.py	34	13	62%	41, 69–76, 90–92, 116–117
TOTAL	2377	993	58%

Tests	Skipped	Failures	Errors	Time
99	0 💤	0 ❌	0 🔥	7.891s ⏱️

[lhaibach]

I like the structure and naming -- it's much more intuitive for me now to understand which class does what.
Question regarding parent classes: AAboveBSidebar and AToBSidebar and LayerIdentifierSidebar are child classes of Sidebar, which makes perfect sense to me. For the corresponding extractors AAboveBSidebarExtractor and AtoBSidebarExtractor and LayerIdentifierSidebarExtractor this is not the case. How do you decide when to use parent classes for certain classes?
Regarding the #todo: automatic AAboveBInterval: will it be possible somehow to determine the interval type based on the sidebar type?

[stijnvermeeren-swisstopo]

@lhaibach
Re SidebarExtractor: potentially it would make sense to have these extend from a common parent class. This might also be what the comment TODO: Similar to AToBSidebarExtractor.find_in_words(). Refactoring may be desired. in layer_identifier_sidebar_extractor.py is hinting at. However, I don't immediately see a significant amount of shared logic that we could move into a shared parent class. But feel free to give it a try, if you think there is potential to simplify the code like that.

Generally speaking, main reasons for using a parent class are:

• Shared code between different classes
• Allowing different classes to be passed as a value for the same parameter (with transparent type annotations)

Re the TODO in extract.py: I don't think the problem is determining the interval type (at this point in the code, we already have an interval instance with a specific type). I think the solution should be to allow any interval type (not just AAboveBInterval) in the Layer class, and to deal with any implications that this might have (in particular, concerning JSON serialization and deserialization).

[stijnvermeeren-swisstopo]

I have now created a ticket for that last TODO: https://jira.swisstopo.ch/browse/LGVISIUM-104

[lhaibach]

@stijnvermeeren-swisstopo thanks for explaining :) !