concatenate

concatenate(
    self ,
    check_behavior: Literal[‘warn’, ‘raise’, ‘ignore’] | None = None,
    conflict: Literal[‘drop’, ‘raise’, ‘keep_first’] = raise,
    group: str | collections.abc.Sequence[str, collections.abc.Sequence[str], None] = None,
    **kwargs ,
)-> ‘Self’

Concatenate patches in order along a dimension.

Patches are partitioned as chunk partitions them — by kind (see the patch compatibility note), dimensions, the identity of every other dimension, and the concatenated dimension’s units — and each partition’s patches are then joined by the requested count in the order of the dimension (spool order when its step is unknown, or along a new dimension), contiguous or not. Patches which cannot be concatenated together land in separate outputs; nothing is skipped and planning does not raise. A coordinate the index describes only by a summary cannot be told from another with the same summary, so such an output is settled when it loads: equal values concatenate, and different ones raise there rather than being silently mixed. Remaining attributes must agree within an output, policed by conflict as chunk polices them. Coordinates are not policed: a coordinate riding the concatenated dimension is joined along it, every other coordinate must agree, and one which cannot be reconciled raises when the output loads rather than being dropped from a patch the catalog describes.

Parameters

Parameter	Description
check_behavior	Deprecated and ignored (kept in its old place for callers who passed it positionally): patches which cannot be concatenated together are placed in separate outputs rather than skipped.
conflict	Indicates how to handle attributes which hold conflicting values across the patches being combined (eg data_type, data_units, custom attrs). A missing value (None, NaN, ““) is a value like any other: it equals another missing one and nothing else, so a patch which never stated an attribute conflicts with one which did. History and the ids are never compared. If”raise” (default) raise an AttributeMergeError for conflicting values. If “drop”, omit the conflicting attributes from the output. If “keep_first”, keep the first patch’s value of each.

group	Attributes which partition patches into separate outputs, instead of the config option `patch_kind_attrs`.
**kwargs	One keyword naming the dimension and the number of patches per output; `None` puts every patch of a partition in one output. A dimension no patch has concatenates along a new one.

Examples

import dascore as dc
spool = dc.get_example_spool()

# Concatenate every patch along time, contiguous or not.
merged = spool.concatenate(time=None)
assert len(merged) == 1

# Concatenate copies of a patch along a new dimension; patches
# sharing a new dimension must agree on the existing ones.
patch = dc.get_example_patch()
stacked = dc.spool([patch, patch.new()]).concatenate(wave_rank=None)
assert stacked[0].shape[stacked[0].get_axis("wave_rank")] == 2

Note

Spool.chunk performs a similar operation but accounts for coordinate values.
concatenate_patches concatenates a list of patches directly, relative to the first.