dcnum.write.writer ================== .. py:module:: dcnum.write.writer Attributes ---------- .. autoapisummary:: dcnum.write.writer.hdf5plugin Exceptions ---------- .. autoapisummary:: dcnum.write.writer.CreatingFileWithoutBasinWarning dcnum.write.writer.IgnoringBasinTypeWarning Classes ------- .. autoapisummary:: dcnum.write.writer.HDF5Writer Functions --------- .. autoapisummary:: dcnum.write.writer.create_with_basins dcnum.write.writer.copy_basins dcnum.write.writer.copy_features dcnum.write.writer.copy_metadata dcnum.write.writer.set_default_filter_kwargs Module Contents --------------- .. py:data:: hdf5plugin .. py:exception:: CreatingFileWithoutBasinWarning Bases: :py:obj:`UserWarning` Initialize self. See help(type(self)) for accurate signature. .. py:exception:: IgnoringBasinTypeWarning Bases: :py:obj:`UserWarning` Initialize self. See help(type(self)) for accurate signature. .. py:class:: HDF5Writer(obj: dcnum.common.h5py.File | pathlib.Path | str, mode: str = 'a', ds_kwds: dict | None = None) Write deformability cytometry HDF5 data :param obj: object to instantiate the writer from; If this is already a :class:`h5py.File` object, then it is used, otherwise the argument is passed to :class:`h5py.File` :type obj: h5py.File | pathlib.Path | str :param mode: opening mode when using :class:`h5py.File` :type mode: str :param ds_kwds: keyword arguments with which to initialize new Datasets (e.g. compression) :type ds_kwds: dict .. py:attribute:: events .. py:attribute:: ds_kwds :value: None .. py:method:: __enter__() .. py:method:: __exit__(exc_type, exc_val, exc_tb) .. py:method:: close() .. py:method:: get_best_nd_chunks(item_shape, feat_dtype=np.float64) :staticmethod: Return best chunks for HDF5 datasets Chunking has performance implications. It’s recommended to keep the total size of dataset chunks between 10 KiB and 1 MiB. This number defines the maximum chunk size as well as half the maximum cache size for each dataset. .. py:method:: require_feature(feat: str, item_shape: tuple[int], feat_dtype: numpy.dtype, ds_kwds: dict | None = None, group_name: str = 'events') Create a new feature in the "events" group :param feat: name of the feature :type feat: str :param item_shape: shape for one event of this feature, e.g. for a scalar event, the shape would be `(1,)` and for an image, the shape could be `(80, 300)`. :type item_shape: tuple[int] :param feat_dtype: dtype of the feature :type feat_dtype: np.dtype :param ds_kwds: HDF5 Dataset keyword arguments (e.g. compression, fletcher32) :type ds_kwds: dict :param group_name: name of the HDF5 group where the feature should be written to; defaults to the "events" group, but a different group can be specified for storing e.g. internal basin features. :type group_name: str .. py:method:: store_basin(name: str, paths: list[str | pathlib.Path] | None = None, features: list[str] | None = None, description: str | None = None, mapping: numpy.ndarray | None = None, internal_data: dict | None = None, identifier: str | None = None) Write an HDF5-based file basin :param name: basin name; Names do not have to be unique. :type name: str :param paths: location(s) of the basin; must be None when storing internal data, a list of paths otherwise :type paths: list of str or pathlib.Path or None :param features: list of features provided by `paths` :type features: list of str :param description: optional string describing the basin :type description: str :param mapping: integer array with indices that map the basin dataset to this dataset :type mapping: 1D array :param internal_data: internal basin data to store; If this is set, then `features` and `paths` must be set to `None`. :type internal_data: dict of ndarrays :param identifier: the measurement identifier of the basin as computed by the :func:`~dcnum.read.hdf5_data.get_measurement_identifier` function. :type identifier: str .. py:method:: store_feature_chunk(feat, data, group_name='events') Store feature data The "chunk" implies that always chunks of data are stored, never single events. .. py:method:: store_log(log: str, data: list[str], override: bool = False) -> dcnum.common.h5py.Dataset Store log data Store the log data under the key `log`. The `data` kwarg must be a list of strings. If the log entry already exists, `ValueError` is raised unless ``override`` is set to True. .. py:function:: create_with_basins(path_out: str | pathlib.Path, basin_paths: list[str | pathlib.Path] | list[list[str | pathlib.Path]]) Create an .rtdc file with basins :param path_out: The output .rtdc file where basins are written to :param basin_paths: The paths to the basins written to `path_out`. This can be either a list of paths (to different basins) or a list of lists for paths (for basins containing the same information, commonly used for relative and absolute paths). .. py:function:: copy_basins(h5_src: dcnum.common.h5py.File, h5_dst: dcnum.common.h5py.File, internal_basins: bool = True) Reassemble basin data in the output file This does not just copy the datasets defined in the "basins" group, but it also loads the "basinmap?" features and stores them as new "basinmap?" features in the output file. .. py:function:: copy_features(h5_src: dcnum.common.h5py.File, h5_dst: dcnum.common.h5py.File, features: list[str], mapping: numpy.ndarray | None = None, ds_kwds: dict | None = None) Copy feature data from one HDF5 file to another The feature must not exist in the destination file. :param h5_src: Input HDF5File containing `features` in the "events" group :type h5_src: h5py.File :param h5_dst: Output HDF5File opened in write mode not containing `features` :type h5_dst: h5py.File :param features: List of features to copy from source to destination :type features: list[str] :param mapping: If given, contains indices in the input file that should be written to the output file. If set to None, all features are written. :type mapping: 1D array :param ds_kwds: keyword arguments with which to initialize new Datasets (e.g. compression); only relevant when `mapping is not None` .. py:function:: copy_metadata(h5_src: dcnum.common.h5py.File, h5_dst: dcnum.common.h5py.File) Copy attributes, tables, and logs from one H5File to another .. rubric:: Notes Metadata in `h5_dst` are never overridden, only metadata that are not defined already are added. .. py:function:: set_default_filter_kwargs(ds_kwds: dict | None = None, compression: bool = True)