pisces.particles.utils.concatenate_particles

pisces.particles.utils.concatenate_particles(output_path: str | Path, *datasets: ParticleDataset, overwrite: bool = False, groups: list[str] = None, **kwargs) → ParticleDataset

Concatenate multiple ParticleDataset objects into a new dataset file.

This method creates a new dataset by copying the first input dataset to output_path and then concatenates the remaining datasets into it using the concatenate_inplace method.

Parameters:

• output_path (str or Path) – Path where the new HDF5 file will be created.

• *datasets (ParticleDataset) – A sequence of particle datasets to concatenate. Must include at least one dataset.

• overwrite (bool, optional) – Whether to overwrite the file if it already exists. Defaults to False.

• groups (list of str, optional) – Specific groups to concatenate. If None, all groups in each dataset will be used.

• **kwargs – Additional keyword arguments passed to the final dataset constructor.

Returns:

A new dataset containing the concatenated data.

Return type:

ParticleDataset

Raises:

• ValueError – If no input datasets are provided.

• FileExistsError – If the output path exists and overwrite is False.