modules.mergers

Classes

class modules.mergers.MergeMaterialTable

Merge the two material tables to a single material table.

Inherits from:: PipeModule

Methods:

__init__(mname: str = 'MergeMaterialTable', auto_run: bool = True, material_table1: PortTypeHint.MaterialTable | None = None, material_table2: PortTypeHint.MaterialTable | None = None, merge_by: Literal[GProps.MaterialID, GProps.LayerNumber, GProps.MaterialName] = GProps.MaterialID) → None

Initialize a MergeMaterialTable object.

Parameters

material_table1PortTypeHint.MaterialTable | None, default: None: The main material table.
material_table2PortTypeHint.MaterialTable | None, default: None: The another material table. merge_by: Literal[GProps.MaterialID, GProps.LayerNumber, GProps.MaterialName], default: GProps.MaterialID The column name to merge the material tables by.

Notes

The matearial_table2 will be merged into the material_table1 which means the output material_table will have
the same rows as the material_table1.

set_cal_params(reset: bool = True) → None

execute() → PortTypeHint.MaterialTable | None

Properties:

InputMaterialTable1

InputMaterialTable2

OutputMaterialTable

class modules.mergers.MergeBoresWithMaterialTable

Merge Bores (MultiProfile1D) with MaterialTable to a TableCollection.

Inherits from:: PipeModule

Methods:

__init__(mname: str = 'MergeBoresWithMaterialTable', auto_run: bool = True, bores: PortTypeHint.MultiProfile1D | None = None, material_table: PortTypeHint.MaterialTable | None = None, additional_fields: list[Literal[GRes.LayerBottomElevation, GRes.LayerTopElevation, GRes.LayerThickness]] | None = None) → None

Initialize a MergeBoresWithMaterialTable object.

Parameters

boresPortTypeHint.MultiProfile1D | None, default: None: The bores to merge.
material_tablePortTypeHint.MaterialTable | None, default: None: The material table to merge. additional_fields: list[Literal[GRes.LayerBottomElevation, GRes.LayerTopElevation, GRes.LayerThickness]], default: None The additional fields to put into the output material table.

Notes

Each bore in the MultiProfile1D will merge with the material table.
A MaterialTableCollection will be returned and the keys are bore numbers.

set_cal_params(reset: bool = True) → None

execute() → PortTypeHint.TableCollection | None

Properties:

InputBores

InputMaterialTable

OutputTables

class modules.mergers.ConcatenateTables

Concatenate several tables.

Inherits from:: PipeModule

Methods:

__init__(mname: str = 'ConcatenateTables', auto_run: bool = True, tables: PortTypeHint.TableCollection | None = None, add_table_name_columns: str | None = None, add_table_title_columns: str | None = None) → None

Initialize a ConcatenateTables object.

Parameters

tablesPortTypeHint.TableCollection | None, default: None: The tables to concatenate.
add_table_name_columnsstr | None, default: None: If provided, adds a column with this name containing the table names.
add_table_title_columnsstr | None, default: None: If provided, adds a column with this name containing the table titles.

Notes

``NaN`` value will be filled for tables that do not the columns in their original data.

set_cal_params(reset: bool = True) → None

execute() → PortTypeHint.TableData | None

Properties:

InputTables

OutputTable

class modules.mergers.MergeTables

Merge multiple tables from a TableCollection or merge two TableData objects.

Inherits from:: PipeModule

Methods:

__init__(mname: str = 'MergeTables', auto_run: bool = True, tables: PortTypeHint.TableCollection | PortTypeHint.TableData | None = None, join_key: str | None = None, tables_to_merge: list[str] | str | None = None, how: Literal[(left, right, outer, inner)] = 'inner', suffixes: tuple[(str, str)] = <ast.Tuple object at 0x0000028E222E1840>, sort: bool = False, copy: bool = True, indicator: bool = False, validate: Literal[(one_to_one, one_to_many, many_to_one, many_to_many)] | None = None, ignore_index: bool = False) → None

Initialize a MergeTables object.

Parameters

tablesPortTypeHint.TableCollection | PortTypeHint.TableData | None, default: None: The input tables to merge. Can be a TableCollection containing multiple tables or a single TableData object.
join_keystr | None, default: None: The column name or field title to use for merging tables. If None, uses the first common column that exists in all tables. Tables without this column will be skipped.
tables_to_mergelist[str] | str | None, default: None: The names or titles of tables to include in the merge. If None, all tables in the collection will be considered. If a single string, converts to list. how: Literal[“left”, “right”, “outer”, “inner”], default: “inner” Type of merge to be performed. Use “inner” when you only want complete records (no missing data) Use “left” when you want to preserve all records from your main dataset Use “right” rarely used, when you want all records from the second dataset Use “outer” when you want a comprehensive view including all possible records suffixes: tuple[str, str], default: (“_x”, “_y”) Suffix to apply to overlapping column names.
sortbool, default: False: Sort the result DataFrame by the join keys.
copybool, default: True: If False, avoid copying data when possible.
indicatorbool, default: False: Add a column to the output DataFrame indicating the source. validate: Literal[“one_to_one”, “one_to_many”, “many_to_one”, “many_to_many”] | None, default: None Validation check on the merge operation. Use “one_to_one” when: Merging master records (employee info + employee contact) Each ID should appear exactly once in both tables You want to ensure no data duplication Use “one_to_many” when: Merging dimension tables with fact tables One category has multiple items (department → employees) Left table is the “lookup” table Use “many_to_one” when: Merging fact tables with dimension tables Multiple records reference the same lookup value Right table is the “lookup” table Use “many_to_many” when: Complex relationships exist You expect duplicates in both tables Junction/bridge table scenarios Use None when: You’re not sure about the relationship Performance is critical (validation adds overhead) You’ll handle data quality issues separately
ignore_indexbool, default: False: If True, do not use the index values along the concatenation axis. The resulting axis will be labeled 0, 1, …, n - 1.

Notes

If tables is a TableData object, it will be returned as-is.
If tables is a TableCollection, tables will be merged sequentially using the join_key.
Tables that don't contain the join_key will be skipped with a warning.

update_ui_schema(reset: bool = False) → dict[str, UIAttributeSchema]

execute() → PortTypeHint.TableData | None

Attributes:

InputTables: PortReference[PortTypeHint.TableCollection | PortTypeHint.TableData]

OutputTable: PortReference[PortTypeHint.TableData]

class modules.mergers.MergeGdimTables

Merge tables with tables with gdim_id column which is

useful for table data pre-processing before writing table data into GDIM.

Inherits from:: PipeModule

Methods:

__init__(mname: str = 'MergeGdimTables', auto_run: bool = True, tables: PortTypeHint.TableCollection | PortTypeHint.TableData | None = None, gdim_tables: PortTypeHint.TableCollection | None = None, how: Literal[ignore, overwrite] = 'ignore', auto_map_columns: bool = False) → None

Initialize a MergeGdimTables object.

Parameters

tablesPortTypeHint.TableCollection | PortTypeHint.TableData | None, default: None

The input tables to merge. Can be a TableCollection containing multiple tables or a single TableData object.

gdim_tablesPortTypeHint.TableCollection | None, default: None

The gdim tables to be merged with the input tables. how: Literal[“ignore”, “overwrite”], default: “ignore” How to handle rows in the input table that have the same primary key value as rows in the gdim table.

“ignore”: Skip rows with matching primary key (keeps original GDIM data, only inserts truly new rows)
“overwrite”: Keep rows with matching primary key and assign gdim_id (updates existing GDIM data)

Notes

The returned result has the same field structure as the gdim tables, not the input tables.
This ensures the output conforms to the GDIM database schema.

For columns that exist in gdim tables but are missing in input tables:
- When updating existing rows (matched by primary key with how="overwrite"),
  the original gdim table values are preserved.
- When inserting new rows, these columns are filled with None.
- If a column exists in the input table but contains None values, those None values
  will overwrite the original gdim data.

Output behavior based on ``how`` parameter:
- how="ignore": Matched rows (same primary key) are excluded from output. Only new rows
  (no matching primary key) appear in the result with gdim_id=None for insertion.
- how="overwrite": All input rows appear in the output. Matched rows have gdim_id assigned
  for updating, new rows have gdim_id=None for insertion.

If a table in ``InputTables`` has no corresponding table in ``InputGdimTables`` (no match by
name or title), the input table is returned unchanged:
- No ``gdim_id`` column is added
- The table structure remains unchanged
- No column mapping or transformation occurs
- The table is still included in the output collection

execute() → PortTypeHint.TableCollection | PortTypeHint.TableData | None

Attributes:

InputTables: PortReference[PortTypeHint.TableCollection | PortTypeHint.TableData]

InputGdimTables: PortReference[PortTypeHint.TableCollection]

OutputTables: PortReference[PortTypeHint.TableCollection | PortTypeHint.TableData]

class modules.mergers.MergeSingleResult

Merge multiple SingleResult objects into a SingleResult.

Inherits from:: PipeModule

Methods:

__init__(mname: str = 'MergeSingleResult', auto_run: bool = True, all_ports_required: bool = True, default_strategy: Literal[overwrite_first, overwrite_last, concat_list, concat_string] = 'overwrite_last', string_separator: str = ', ', key_strategies: dict[str, Literal[overwrite_first, overwrite_last, concat_list, concat_string]] | None = None) → None

Initialize a MergeSingleResult object.

Parameters

all_ports_requiredbool, default: True

If True, the execution will be blocked until all the dynamic ports are connected with valid data. default_strategy: Literal[“overwrite_first”, “overwrite_last”, “concat_list”, “concat_string”], default: “overwrite_last” The default strategy for handling conflicting keys:

“overwrite_first”: Keep the value from the first SingleResult (first has priority)
“overwrite_last”: Keep the value from the last SingleResult (last has priority)
“concat_list”: Concatenate all values into a list (handles existing lists properly)
“concat_string”: Concatenate all values into a string with separator

string_separator: str, default: “, ” The separator to use when concatenating values as strings (only used with “concat_string” strategy). key_strategies: dict[str, Literal[“overwrite_first”, “overwrite_last”, “concat_list”, “concat_string”]] | None, default: None A dictionary specifying strategies for specific keys (by result name or title). Keys not in this dictionary will use the default_strategy.

Notes

When merging SingleResult objects:
- For different keys (no conflict), they are simply combined like merging dictionaries
- For conflicting keys, the specified strategy is applied
- For "concat_list" strategy, if a value is already a list, its elements are added individually
- Key strategies can use either result names or titles for identification

execute() → PortTypeHint.SingleResult | None

Attributes:

OutputSingleResult: PortReference[PortTypeHint.SingleResult]

class modules.mergers.MergeResultModels

Merge multiple ResultModel and SingleResult objects into a single ResultModel.

Dynamic input ports accept either ``PortType.ResultModel`` or ``PortType.SingleResult``. Fields from all inputs are combined into one output ``ResultModel``. Conflicting field names (present in more than one input) are resolved with the same strategies available in :class:MergeSingleResult.

Inherits from:: PipeModule

Methods:

__init__(mname: str = 'MergeResultModels', auto_run: bool = True, all_ports_required: bool = True, default_strategy: Literal[overwrite_first, overwrite_last, concat_list, concat_string] = 'overwrite_last', string_separator: str = ', ', key_strategies: dict[str, Literal[overwrite_first, overwrite_last, concat_list, concat_string]] | None = None) → None

Initialize a MergeResultModels object.

Parameters

all_ports_requiredbool, default: True

If True, the execution will be blocked until all the dynamic ports are connected with valid data. default_strategy: Literal[“overwrite_first”, “overwrite_last”, “concat_list”, “concat_string”], default: “overwrite_last” The default strategy for handling conflicting field names:

“overwrite_first”: Keep the value from the first input (first has priority).
“overwrite_last”: Keep the value from the last input (last has priority).
“concat_list”: Concatenate all values into a list (flattens existing lists).
“concat_string”: Concatenate all values into a string with string_separator.

string_separator: str, default: “, ” The separator used when concatenating values as strings. Only used with the “concat_string” strategy. key_strategies: dict[str, Literal[…]] | None, default: None Per-field override strategies. Keys are field names (or, for ``SingleResult`` inputs, ``UnitResult.title`` values). Fields not present in this dict fall back to default_strategy.

Notes

- ````SingleResult```` inputs are expanded field-by-field using
  ````UnitResult.name```` as the field name and ````UnitResult.value```` as the
  value.  The ````UnitResult.title```` is used for ````key_strategies```` lookup.
- ````ResultModel```` inputs are expanded with ````model_dump()````.  The
  ````Field(title=...)```` metadata (if present) is used for
  ````key_strategies```` lookup.
- The output model is a dynamically created Pydantic ````BaseModel````
  whose field names are the union of all input field names.

execute() → PortTypeHint.ResultModel | None

Attributes:

OutputResultModel: PortReference[PortTypeHint.ResultModel]

class modules.mergers.AddTables

Add tables to a ``TableCollection`` or seed from a ``TableData``.

Inherits from:: PipeModule

Methods:

__init__(mname: str = 'AddTables', auto_run: bool = True, tables_to_add: PortTypeHint.TableCollection | PortTypeHint.TableData | None = None, tables_added_to: PortTypeHint.TableCollection | PortTypeHint.TableData | None = None, main_table_name: str | None = None, sub_table_names: list[str] | dict[str, list[str]] | None = None, primary_key: str | None = None, collection_metadata: TableMetadata | dict | Literal[tables_to_add, tables_added_to, combined] = 'tables_added_to', combine_sep: str = '\n') → None

Initialize the AddTables object.

Parameters

tables_to_addPortTypeHint.TableCollection | PortTypeHint.TableData | None, default: None: The tables to add to the collection.
tables_added_toPortTypeHint.TableCollection | PortTypeHint.TableData | None, default: None: The collection or base TableData to merge into. A lone TableData is wrapped in a new TableCollection.
main_table_namestr | None, default: None: Table name or title to treat as an additional main table (merged into existing main_table, which may be str or list[str]). sub_table_names: list[str] | dict[str, list[str]] | None, default: None Sub-tables as names or titles. If a list, entries are merged into ``sub_tables`` (list or ``dict[str, list[str]]``). If a dict, keys are main names or titles and values are lists of sub names or titles (see ``TableCollection.sub_tables``).
primary_keystr | None, default: None: Primary key field name or title (resolved per main table). Merged into existing primary_key (str or dict[str, str]). collection_metadata: TableMetadata | dict | Literal[“tables_to_add”, “tables_added_to”, “combined”], default: “tables_added_to” If TableMetadata or dict, it will be used to override the output TableCollection metadata. If “tables_to_add”, InputTablesToAdd metadata will be used for the output TableCollection metadata. if “tables_added_to”, InputTablesAddedTo metadata will be used for the output TableCollection metadata. if “combined”, InputTablesToAdd and InputTablesAddedTo metadata will be combined with combine_sep.
combine_sepstr, default: `”: “` Separator used when combining metadata field values from multiple input sources. Only used when collection_metadata is “combined”. Ports —–
InputTablesToAddPortTypeHint.TableCollection | PortTypeHint.TableData: The tables to add.
InputTablesAddedToPortTypeHint.TableCollection | PortTypeHint.TableData: The collection or base table to add into.
OutputTablesPortTypeHint.TableCollection: The resulting table collection after adding tables.

Notes

----
        If either ``InputTablesToAdd`` or ``InputTablesAddedTo`` is unset, execution yields
        ``None`` on ``OutputTables``. Relationship parameters merge into existing structure
        instead of replacing it.

execute() → PortTypeHint.TableCollection | None

Attributes:

InputTablesToAdd: PortReference[PortTypeHint.TableCollection | PortTypeHint.TableData]

InputTablesAddedTo: PortReference[PortTypeHint.TableCollection | PortTypeHint.TableData]

OutputTables: PortReference[PortTypeHint.TableCollection]