jcmsuite-xarray 1.0.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,609 @@
1
+ # SPDX-License-Identifier: MIT
2
+ # Copyright (c) 2001-2026 JCMwave GmbH
3
+
4
+ """Grouped postprocess helpers for internal `xarray` exports."""
5
+
6
+ from __future__ import annotations
7
+
8
+ import logging
9
+ from collections.abc import Mapping, Sequence
10
+ from dataclasses import dataclass
11
+ from typing import cast
12
+
13
+ import numpy as np
14
+
15
+ from jcmsuite.exceptions import InvalidConfigurationError
16
+ from jcmsuite.results.internal.export.pandas.payload import is_numeric_key_mapping
17
+ from jcmsuite.results.internal.export.xarray.types import XarrayDataset
18
+
19
+ from .runtime import _XarrayModule
20
+ from .shared import (
21
+ _array_dtype_for_padding,
22
+ _ensure_generated_companion_dim_coords,
23
+ _ensure_generated_value_dim_coords,
24
+ _field_key_sort_key,
25
+ _normalize_scalar_coord_value,
26
+ _ordered_union,
27
+ _stack_sample_coordinate_arrays,
28
+ )
29
+ from .tabular import _BatchIndexedKeys
30
+
31
+ logger = logging.getLogger(f"{__package__}.export")
32
+
33
+
34
+ @dataclass(slots=True, frozen=True)
35
+ class _GroupedPostprocessTensor:
36
+ """Normalized grouped postprocess tensor ready for xarray export."""
37
+
38
+ primary_field_name: str
39
+ postprocess_title: str | None
40
+ source_file: str | None
41
+ field_index: tuple[object, ...]
42
+ sample_index: tuple[int, ...]
43
+ grouped_values: dict[str, np.ndarray]
44
+ grouped_dims: dict[str, tuple[str, ...]]
45
+ is_valid: np.ndarray
46
+ is_padded: np.ndarray
47
+ sample_coords: dict[str, tuple[tuple[str, ...], np.ndarray]]
48
+ attrs: dict[str, object]
49
+
50
+
51
+ @dataclass(slots=True, frozen=True)
52
+ class _StructuredPayloadParts:
53
+ """Partitioned mapping payload for one tree node."""
54
+
55
+ grouped_fields: dict[str, Mapping[object, object]]
56
+ companion_fields: dict[str, object]
57
+ nested_fields: dict[str, Mapping[object, object]]
58
+
59
+
60
+ def postprocess_payload_to_grouped_tensor(
61
+ payload: object,
62
+ *,
63
+ postprocess_title: str | None,
64
+ source_file: object,
65
+ ) -> _GroupedPostprocessTensor:
66
+ """Normalize one supported grouped postprocess payload into arrays and labels."""
67
+
68
+ payload_parts: _StructuredPayloadParts
69
+ if isinstance(payload, _StructuredPayloadParts):
70
+ payload_parts = payload
71
+ elif isinstance(payload, Mapping):
72
+ payload_parts = _split_structured_payload(payload)
73
+ else:
74
+ raise InvalidConfigurationError(
75
+ "Postprocess payload is not mapping-like and cannot be exported via to_xarray()."
76
+ )
77
+
78
+ grouped_fields: dict[str, Mapping[object, object]] = payload_parts.grouped_fields
79
+ companion_fields: dict[str, object] = payload_parts.companion_fields
80
+
81
+ if not grouped_fields:
82
+ raise InvalidConfigurationError(
83
+ "Postprocess payload does not contain a grouped numeric-key field supported by to_xarray()."
84
+ )
85
+ grouped_field_names: tuple[str, ...] = tuple(grouped_fields.keys())
86
+ first_field_name: str = grouped_field_names[0]
87
+ first_payload: Mapping[object, object] = grouped_fields[first_field_name]
88
+ first_tensor: _GroupedPostprocessTensor = _build_grouped_field_tensor(
89
+ first_payload,
90
+ field_name=first_field_name,
91
+ postprocess_title=postprocess_title,
92
+ source_file=source_file,
93
+ companion_fields=companion_fields,
94
+ multi_field_payload=len(grouped_field_names) > 1,
95
+ )
96
+ grouped_values: dict[str, np.ndarray] = dict(first_tensor.grouped_values)
97
+ grouped_dims: dict[str, tuple[str, ...]] = dict(first_tensor.grouped_dims)
98
+
99
+ grouped_field_name: str
100
+ for grouped_field_name in grouped_field_names[1:]:
101
+ grouped_payload: Mapping[object, object] = grouped_fields[grouped_field_name]
102
+ grouped_tensor: _GroupedPostprocessTensor = _build_grouped_field_tensor(
103
+ grouped_payload,
104
+ field_name=grouped_field_name,
105
+ postprocess_title=postprocess_title,
106
+ source_file=source_file,
107
+ companion_fields=companion_fields,
108
+ multi_field_payload=True,
109
+ )
110
+ if grouped_tensor.field_index != first_tensor.field_index:
111
+ raise InvalidConfigurationError(
112
+ "Postprocess payload contains grouped fields with different field-index keys; to_xarray() requires aligned grouped fields."
113
+ )
114
+ if not np.array_equal(grouped_tensor.is_valid, first_tensor.is_valid):
115
+ raise InvalidConfigurationError(
116
+ "Postprocess payload contains grouped fields with different per-field sample counts; to_xarray() requires aligned grouped fields."
117
+ )
118
+ if not np.array_equal(grouped_tensor.is_padded, first_tensor.is_padded):
119
+ raise InvalidConfigurationError(
120
+ "Postprocess payload contains grouped fields with different padding structure; to_xarray() requires aligned grouped fields."
121
+ )
122
+ grouped_values.update(grouped_tensor.grouped_values)
123
+ grouped_dims.update(grouped_tensor.grouped_dims)
124
+
125
+ attrs: dict[str, object] = dict(first_tensor.attrs)
126
+ if len(grouped_field_names) == 1:
127
+ attrs["field_name"] = first_field_name
128
+ else:
129
+ attrs["field_names"] = grouped_field_names
130
+
131
+ return _GroupedPostprocessTensor(
132
+ primary_field_name=first_field_name,
133
+ postprocess_title=first_tensor.postprocess_title,
134
+ source_file=first_tensor.source_file,
135
+ field_index=first_tensor.field_index,
136
+ sample_index=first_tensor.sample_index,
137
+ grouped_values=grouped_values,
138
+ grouped_dims=grouped_dims,
139
+ is_valid=first_tensor.is_valid,
140
+ is_padded=first_tensor.is_padded,
141
+ sample_coords=first_tensor.sample_coords,
142
+ attrs=attrs,
143
+ )
144
+
145
+
146
+ def grouped_tensor_to_xarray_dataset(
147
+ tensor: _GroupedPostprocessTensor,
148
+ *,
149
+ xarray_module: _XarrayModule,
150
+ ) -> XarrayDataset:
151
+ """Convert one normalized grouped tensor into an `xarray.Dataset`."""
152
+
153
+ coords: dict[str, object] = {
154
+ "field_index": list(tensor.field_index),
155
+ "sample_index": list(tensor.sample_index),
156
+ }
157
+ data_vars: dict[str, object] = {}
158
+
159
+ field_name: str
160
+ for field_name, value_array in tensor.grouped_values.items():
161
+ value_dims: tuple[str, ...] = tensor.grouped_dims[field_name]
162
+ _ensure_generated_value_dim_coords(
163
+ coords,
164
+ value_dims=value_dims,
165
+ value_array=value_array,
166
+ )
167
+ data_vars[field_name] = (value_dims, value_array)
168
+
169
+ coord_name: str
170
+ coord_value: tuple[tuple[str, ...], np.ndarray]
171
+ for coord_name, coord_value in tensor.sample_coords.items():
172
+ coord_dims, coord_array = coord_value
173
+ _ensure_generated_companion_dim_coords(
174
+ coords,
175
+ coord_dims=coord_dims,
176
+ coord_array=coord_array,
177
+ )
178
+ coords[coord_name] = (coord_dims, coord_array)
179
+
180
+ attrs: dict[str, object] = dict(tensor.attrs)
181
+ attrs["postprocess_title"] = tensor.postprocess_title
182
+ attrs["source_file"] = tensor.source_file
183
+
184
+ data_vars["is_valid"] = (("field_index", "sample_index"), tensor.is_valid)
185
+ data_vars["is_padded"] = (("field_index", "sample_index"), tensor.is_padded)
186
+ return xarray_module.Dataset(
187
+ data_vars=data_vars,
188
+ coords=coords,
189
+ attrs=attrs,
190
+ )
191
+
192
+
193
+ def _build_grouped_field_tensor(
194
+ grouped_payload: Mapping[object, object],
195
+ *,
196
+ field_name: str,
197
+ postprocess_title: str | None,
198
+ source_file: object,
199
+ companion_fields: Mapping[str, object],
200
+ multi_field_payload: bool,
201
+ ) -> _GroupedPostprocessTensor:
202
+ """Build one normalized tensor for a grouped numeric-key payload."""
203
+
204
+ field_keys: list[object] = sorted(grouped_payload.keys(), key=_field_key_sort_key)
205
+ arrays: list[np.ndarray] = []
206
+ field_key: object
207
+ for field_key in field_keys:
208
+ value_object: object = grouped_payload[field_key]
209
+ if not isinstance(value_object, np.ndarray):
210
+ raise InvalidConfigurationError(
211
+ "Grouped postprocess values must be numpy arrays for to_xarray()."
212
+ )
213
+ if value_object.ndim == 0:
214
+ raise InvalidConfigurationError(
215
+ "Grouped scalar postprocess values are not supported by to_xarray() in this slice."
216
+ )
217
+ arrays.append(value_object)
218
+
219
+ first_array: np.ndarray = arrays[0]
220
+ trailing_shape: tuple[int, ...] = tuple(int(axis) for axis in first_array.shape[1:])
221
+ value_ndim: int = int(first_array.ndim)
222
+ if value_ndim < 1:
223
+ raise InvalidConfigurationError(
224
+ "Grouped postprocess values must have at least one sample dimension for to_xarray()."
225
+ )
226
+ array_value: np.ndarray
227
+ for array_value in arrays[1:]:
228
+ if array_value.ndim != value_ndim:
229
+ raise InvalidConfigurationError(
230
+ "Grouped postprocess arrays must share the same dimensionality for to_xarray()."
231
+ )
232
+ if tuple(int(axis) for axis in array_value.shape[1:]) != trailing_shape:
233
+ raise InvalidConfigurationError(
234
+ "Grouped postprocess arrays must share trailing dimensions for to_xarray()."
235
+ )
236
+
237
+ sample_lengths: list[int] = [int(array.shape[0]) for array in arrays]
238
+ max_samples: int = max(sample_lengths)
239
+ requires_padding: bool = any(length != max_samples for length in sample_lengths)
240
+ if requires_padding:
241
+ logger.debug(
242
+ "Padding grouped postprocess %r to sample length %d from lengths %s.",
243
+ field_name,
244
+ max_samples,
245
+ sample_lengths,
246
+ )
247
+
248
+ value_dtype: np.dtype[np.generic] = _array_dtype_for_padding(
249
+ arrays,
250
+ requires_padding=requires_padding,
251
+ )
252
+ value_shape: tuple[int, ...] = (len(field_keys), max_samples) + trailing_shape
253
+ value_array: np.ndarray = np.full(value_shape, np.nan, dtype=value_dtype)
254
+ is_valid: np.ndarray = np.zeros((len(field_keys), max_samples), dtype=bool)
255
+ is_padded: np.ndarray = np.zeros((len(field_keys), max_samples), dtype=bool)
256
+
257
+ field_position: int
258
+ for field_position, array_value in enumerate(arrays):
259
+ sample_count: int = int(array_value.shape[0])
260
+ value_array[field_position, :sample_count, ...] = array_value.astype(
261
+ value_dtype,
262
+ copy=False,
263
+ )
264
+ is_valid[field_position, :sample_count] = True
265
+ if sample_count < max_samples:
266
+ is_padded[field_position, sample_count:] = True
267
+
268
+ value_dims: tuple[str, ...] = _grouped_value_dims(
269
+ field_name=field_name,
270
+ value_ndim=value_ndim,
271
+ )
272
+
273
+ sample_coords, attrs = _partition_companion_fields(
274
+ companion_fields,
275
+ sample_count=max_samples,
276
+ )
277
+
278
+ return _GroupedPostprocessTensor(
279
+ primary_field_name=field_name,
280
+ postprocess_title=postprocess_title,
281
+ source_file=None if source_file is None else str(source_file),
282
+ field_index=tuple(field_keys),
283
+ sample_index=tuple(range(max_samples)),
284
+ grouped_values={field_name: value_array},
285
+ grouped_dims={field_name: value_dims},
286
+ is_valid=is_valid,
287
+ is_padded=is_padded,
288
+ sample_coords=sample_coords,
289
+ attrs=attrs,
290
+ )
291
+
292
+
293
+ def _grouped_value_dims(
294
+ *,
295
+ field_name: str,
296
+ value_ndim: int,
297
+ ) -> tuple[str, ...]:
298
+ """Return xarray dimension names for one grouped postprocess data variable."""
299
+
300
+ if value_ndim == 1:
301
+ return ("field_index", "sample_index")
302
+ if value_ndim == 2:
303
+ return ("field_index", "sample_index", "component")
304
+ trailing_dims: tuple[str, ...] = tuple(
305
+ f"{field_name}_dim_{dimension_index}"
306
+ for dimension_index in range(value_ndim - 1)
307
+ )
308
+ return ("field_index", "sample_index") + trailing_dims
309
+
310
+
311
+ def _stack_batch_grouped_tensors(
312
+ entries: Sequence[_BatchIndexedKeys],
313
+ tensors: Sequence[_GroupedPostprocessTensor],
314
+ *,
315
+ index: int | None,
316
+ title: str | None,
317
+ xarray_module: _XarrayModule,
318
+ batch_axis_name: str = "index",
319
+ available: Sequence[bool] | None = None,
320
+ ) -> XarrayDataset:
321
+ """Stack selected grouped tensors from batch entries onto one batch axis."""
322
+
323
+ first_tensor: _GroupedPostprocessTensor = tensors[0]
324
+ grouped_field_names: tuple[str, ...] = tuple(first_tensor.grouped_values.keys())
325
+ postprocess_title: str | None = first_tensor.postprocess_title
326
+
327
+ tensor: _GroupedPostprocessTensor
328
+ for tensor in tensors[1:]:
329
+ if tuple(tensor.grouped_values.keys()) != grouped_field_names:
330
+ raise InvalidConfigurationError(
331
+ "Selected batch postprocess stream mixes grouped payloads with different grouped field names and cannot be stacked via to_xarray()."
332
+ )
333
+ grouped_name: str
334
+ for grouped_name in grouped_field_names:
335
+ if (
336
+ tensor.grouped_dims[grouped_name]
337
+ != first_tensor.grouped_dims[grouped_name]
338
+ ):
339
+ raise InvalidConfigurationError(
340
+ "Selected batch postprocess stream mixes incompatible grouped field shapes and cannot be stacked via to_xarray()."
341
+ )
342
+
343
+ global_field_index: tuple[object, ...] = _ordered_union(
344
+ [tensor.field_index for tensor in tensors]
345
+ )
346
+ max_samples: int = max(len(tensor.sample_index) for tensor in tensors)
347
+ requires_batch_padding: bool = any(
348
+ len(tensor.field_index) != len(global_field_index)
349
+ or len(tensor.sample_index) != max_samples
350
+ for tensor in tensors
351
+ )
352
+ if requires_batch_padding:
353
+ logger.debug(
354
+ "Padding batch-selected postprocess %r to field/sample shape (%d, %d) from field counts %s and sample counts %s.",
355
+ title if title is not None else first_tensor.primary_field_name,
356
+ len(global_field_index),
357
+ max_samples,
358
+ [len(tensor.field_index) for tensor in tensors],
359
+ [len(tensor.sample_index) for tensor in tensors],
360
+ )
361
+ is_valid: np.ndarray = np.zeros(
362
+ (len(entries), len(global_field_index), max_samples),
363
+ dtype=bool,
364
+ )
365
+ is_padded: np.ndarray = np.ones(
366
+ (len(entries), len(global_field_index), max_samples),
367
+ dtype=bool,
368
+ )
369
+
370
+ field_position_lookup: dict[object, int] = {
371
+ field_value: position for position, field_value in enumerate(global_field_index)
372
+ }
373
+
374
+ stacked_values: dict[str, np.ndarray] = {}
375
+ field_name: str
376
+ for field_name in grouped_field_names:
377
+ value_arrays: list[np.ndarray] = [
378
+ tensor.grouped_values[field_name] for tensor in tensors
379
+ ]
380
+ value_dtype: np.dtype[np.generic] = _array_dtype_for_padding(
381
+ value_arrays,
382
+ requires_padding=requires_batch_padding,
383
+ )
384
+ first_value_array: np.ndarray = first_tensor.grouped_values[field_name]
385
+ trailing_shape: tuple[int, ...] = tuple(
386
+ int(axis) for axis in first_value_array.shape[2:]
387
+ )
388
+ value_shape: tuple[int, ...] = (
389
+ len(entries),
390
+ len(global_field_index),
391
+ max_samples,
392
+ ) + trailing_shape
393
+ stacked_values[field_name] = np.full(value_shape, np.nan, dtype=value_dtype)
394
+
395
+ entry_position: int
396
+ for entry_position, tensor in enumerate(tensors):
397
+ local_position: int
398
+ field_value: object
399
+ for local_position, field_value in enumerate(tensor.field_index):
400
+ global_position: int = field_position_lookup[field_value]
401
+ sample_count: int = len(tensor.sample_index)
402
+ grouped_data_name: str
403
+ for grouped_data_name in grouped_field_names:
404
+ source_array: np.ndarray = tensor.grouped_values[grouped_data_name]
405
+ target_array: np.ndarray = stacked_values[grouped_data_name]
406
+ target_array[
407
+ (entry_position, global_position, slice(0, sample_count))
408
+ ] = source_array[(local_position, slice(0, sample_count))].astype(
409
+ target_array.dtype,
410
+ copy=False,
411
+ )
412
+ is_valid[entry_position, global_position, :sample_count] = tensor.is_valid[
413
+ local_position,
414
+ :sample_count,
415
+ ]
416
+ is_padded[entry_position, global_position, :sample_count] = (
417
+ tensor.is_padded[
418
+ local_position,
419
+ :sample_count,
420
+ ]
421
+ )
422
+ if available is not None and not available[entry_position]:
423
+ is_valid[entry_position, :, :] = False
424
+ is_padded[entry_position, :, :] = True
425
+
426
+ coords: dict[str, object] = {
427
+ batch_axis_name: [entry.index for entry in entries],
428
+ "field_index": list(global_field_index),
429
+ "sample_index": list(range(max_samples)),
430
+ "source_file": (
431
+ batch_axis_name,
432
+ np.asarray(
433
+ [
434
+ "" if tensor.source_file is None else tensor.source_file
435
+ for tensor in tensors
436
+ ],
437
+ dtype=object,
438
+ ),
439
+ ),
440
+ }
441
+
442
+ for field_name in grouped_field_names:
443
+ _ensure_generated_value_dim_coords(
444
+ coords,
445
+ value_dims=first_tensor.grouped_dims[field_name],
446
+ value_array=first_tensor.grouped_values[field_name],
447
+ )
448
+
449
+ common_key_names: set[str] = set(entries[0].keys)
450
+ entry: _BatchIndexedKeys
451
+ for entry in entries[1:]:
452
+ common_key_names &= set(entry.keys)
453
+ key_name: str
454
+ for key_name in sorted(common_key_names):
455
+ normalized_values: list[object] = []
456
+ supported: bool = True
457
+ entry_value: object
458
+ for entry in entries:
459
+ entry_value = entry.keys[key_name]
460
+ normalized_value: object | None = _normalize_scalar_coord_value(entry_value)
461
+ if normalized_value is None:
462
+ supported = False
463
+ break
464
+ normalized_values.append(normalized_value)
465
+ if supported:
466
+ coords[key_name] = (batch_axis_name, np.asarray(normalized_values))
467
+
468
+ common_sample_coord_names: set[str] = set(tensors[0].sample_coords)
469
+ for tensor in tensors[1:]:
470
+ common_sample_coord_names &= set(tensor.sample_coords)
471
+ coord_name: str
472
+ for coord_name in sorted(common_sample_coord_names):
473
+ first_coord_dims, _first_coord_array = tensors[0].sample_coords[coord_name]
474
+ candidate_tensor: _GroupedPostprocessTensor
475
+ for candidate_tensor in tensors[1:]:
476
+ candidate_dims, _candidate_array = candidate_tensor.sample_coords[
477
+ coord_name
478
+ ]
479
+ if candidate_dims != first_coord_dims:
480
+ raise InvalidConfigurationError(
481
+ f"Selected batch postprocess stream mixes incompatible companion coordinate shapes for {coord_name!r} and cannot be stacked via to_xarray()."
482
+ )
483
+ coord_arrays: list[np.ndarray] = [
484
+ tensor.sample_coords[coord_name][1] for tensor in tensors
485
+ ]
486
+ _ensure_generated_companion_dim_coords(
487
+ coords,
488
+ coord_dims=first_coord_dims,
489
+ coord_array=coord_arrays[0],
490
+ )
491
+ coords[coord_name] = (
492
+ (batch_axis_name,) + first_coord_dims,
493
+ _stack_sample_coordinate_arrays(coord_arrays, sample_count=max_samples),
494
+ )
495
+
496
+ attrs: dict[str, object] = {
497
+ "postprocess_title": postprocess_title,
498
+ }
499
+ if len(grouped_field_names) == 1:
500
+ attrs["field_name"] = grouped_field_names[0]
501
+ else:
502
+ attrs["field_names"] = grouped_field_names
503
+ if index is not None:
504
+ attrs["postprocess_index"] = index
505
+ if title is not None:
506
+ attrs["postprocess_selector"] = title
507
+
508
+ coord_tensor: _GroupedPostprocessTensor = first_tensor
509
+ for coord_name, coord_value in coord_tensor.attrs.items():
510
+ attrs[coord_name] = coord_value
511
+
512
+ data_vars: dict[str, object] = {}
513
+ for field_name in grouped_field_names:
514
+ data_vars[field_name] = (
515
+ (batch_axis_name,) + first_tensor.grouped_dims[field_name],
516
+ stacked_values[field_name],
517
+ )
518
+ data_vars["is_valid"] = ((batch_axis_name, "field_index", "sample_index"), is_valid)
519
+ data_vars["is_padded"] = (
520
+ (batch_axis_name, "field_index", "sample_index"),
521
+ is_padded,
522
+ )
523
+
524
+ return xarray_module.Dataset(
525
+ data_vars=data_vars,
526
+ coords=coords,
527
+ attrs=attrs,
528
+ )
529
+
530
+
531
+ def _partition_companion_fields(
532
+ companion_fields: Mapping[str, object],
533
+ *,
534
+ sample_count: int,
535
+ ) -> tuple[dict[str, tuple[tuple[str, ...], np.ndarray]], dict[str, object]]:
536
+ """Split companion fields into sample-aligned coords and scalar attrs."""
537
+
538
+ sample_coords: dict[str, tuple[tuple[str, ...], np.ndarray]] = {}
539
+ attrs: dict[str, object] = {}
540
+ field_name: str
541
+ field_value: object
542
+ for field_name, field_value in companion_fields.items():
543
+ if isinstance(field_value, np.ndarray):
544
+ if field_value.ndim == 0:
545
+ attrs[field_name] = cast(object, field_value[()])
546
+ continue
547
+ if int(field_value.shape[0]) == sample_count:
548
+ trailing_dims: tuple[str, ...] = tuple(
549
+ f"{field_name}_dim_{dimension_index}"
550
+ for dimension_index in range(max(field_value.ndim - 1, 0))
551
+ )
552
+ sample_coords[field_name] = (
553
+ ("sample_index",) + trailing_dims,
554
+ field_value,
555
+ )
556
+ continue
557
+ raise InvalidConfigurationError(
558
+ f"Companion field {field_name!r} is not supported by to_xarray() in this slice."
559
+ )
560
+ if isinstance(field_value, (str, bytes, bytearray, int, float, complex, bool)):
561
+ attrs[field_name] = field_value
562
+ continue
563
+ raise InvalidConfigurationError(
564
+ f"Companion field {field_name!r} is not supported by to_xarray() in this slice."
565
+ )
566
+ return sample_coords, attrs
567
+
568
+
569
+ def _split_structured_payload(
570
+ payload: Mapping[object, object],
571
+ ) -> _StructuredPayloadParts:
572
+ """Split one mapping payload into node-local and child-node fields."""
573
+
574
+ grouped_fields: dict[str, Mapping[object, object]] = {}
575
+ companion_fields: dict[str, object] = {}
576
+ nested_fields: dict[str, Mapping[object, object]] = {}
577
+ field_key: object
578
+ field_value: object
579
+ for field_key, field_value in payload.items():
580
+ field_name: str = str(field_key)
581
+ if field_name == "header":
582
+ continue
583
+ if isinstance(field_value, Mapping):
584
+ if is_numeric_key_mapping(field_value):
585
+ grouped_fields[field_name] = field_value
586
+ continue
587
+ nested_fields[field_name] = field_value
588
+ continue
589
+ companion_fields[field_name] = field_value
590
+ return _StructuredPayloadParts(
591
+ grouped_fields=grouped_fields,
592
+ companion_fields=companion_fields,
593
+ nested_fields=nested_fields,
594
+ )
595
+
596
+
597
+ def _common_ordered_child_names(
598
+ payload_parts_list: Sequence[_StructuredPayloadParts],
599
+ ) -> tuple[str, ...]:
600
+ """Return shared child-node names, requiring identical nested structure."""
601
+
602
+ first_names: tuple[str, ...] = tuple(payload_parts_list[0].nested_fields.keys())
603
+ payload_parts: _StructuredPayloadParts
604
+ for payload_parts in payload_parts_list[1:]:
605
+ if tuple(payload_parts.nested_fields.keys()) != first_names:
606
+ raise InvalidConfigurationError(
607
+ "Selected batch postprocess stream mixes incompatible nested payload namespaces and cannot be stacked via to_xarray()."
608
+ )
609
+ return first_names