# pydicom.fileset.FileSet

class pydicom.fileset.FileSet(ds: Dataset | str | PathLike | None = None)

  Representation of a DICOM File-set.

  __init__(ds: Dataset | str | PathLike | None = None) → None

    Create or load a File-set.

    Parameters:

      ds (pydicom.dataset.Dataset, str or PathLike, optional) – If loading a File-set, the DICOMDIR dataset or the path to the DICOMDIR file.

  Methods

  `__init__`([ds]) | Create or load a File-set.
  `add`(ds_or_path) | Stage an instance for addition to the File-set.
  `add_custom`(ds_or_path, leaf) | Stage an instance for addition to the File-set using custom records.
  `clear`() | Clear the File-set.
  `copy`(path[, force_implicit]) | Copy the File-set to a new root directory and return the copied File-set.
  `find`([load]) | Return matching instances in the File-set
  `find_values`(elements[, instances, load]) | Return a list of unique values for given element(s).
  `load`(ds_or_path[, include_orphans, ...]) | Load an existing File-set.
  `remove`(instance) | Stage instance(s) for removal from the File-set.
  `write`([path, use_existing, force_implicit]) | Write the File-set, or changes to the File-set, to the file system.

  Attributes

  `ID` | Return the File-set ID (if available) or `None`.
  `UID` | Return the File-set's UID.
  `descriptor_character_set` | Return the Specific Character Set of File-set Descriptor File (if available) or `None`.
  `descriptor_file_id` | Return the File-set Descriptor File ID (if available) or `None`.
  `is_staged` | Return `True` if the File-set is new or has changes staged.
  `path` | Return the absolute path to the File-set root directory as `str` (if set) or `None` otherwise.
  `root_path` | Return the absolute path to the File-set root directory as `pathlib.Path`.

  property ID: str | None

    Return the File-set ID (if available) or `None`.

  property UID: <property object at 0x7dd5ab3cb4c0>

    Return the File-set’s UID.

  add(ds_or_path: Dataset | str | PathLike) → FileInstance

    Stage an instance for addition to the File-set.

    If the instance has been staged for removal then calling `add()` will cancel the staging and the instance will not be removed.

    Parameters:

      ds_or_path (pydicom.dataset.Dataset, str or PathLike) – The instance to add to the File-set, either as a `Dataset` or the path to the instance.

    Returns:

      The `FileInstance` that was added.

    Return type:

      FileInstance

    See also

    `add_custom()`

  add_custom(ds_or_path: Dataset | str | PathLike, leaf: RecordNode) → FileInstance

    Stage an instance for addition to the File-set using custom records.

    This method allows you to add a SOP instance and customize the directory records that will be used when writing the DICOMDIR file. It must be used when you require PRIVATE records and may be used instead of modifying `DIRECTORY_RECORDERS` with your own record definition functions when the default functions aren’t suitable.

    The following elements will be added automatically to the supplied directory records if required and not present:

    - (0004,1400) Offset of the Next Directory Record

    - (0004,1410) Record In-use Flag

    - (0004,1420) Offset of Referenced Lower-Level Directory Entity

    - (0004,1500) Referenced File ID

    - (0004,1510) Referenced SOP Class UID in File

    - (0004,1511) Referenced SOP Instance UID in File

    - (0004,1512) Referenced Transfer Syntax UID in File

    If the instance has been staged for removal then calling `add_custom()` will cancel the staging and the instance will not be removed.

    Examples

    Add a SOP Instance using a two record hierarchy of PATIENT -> PRIVATE

        from pydicom import Dataset, examples
        from pydicom.fileset import FileSet, RecordNode
        from pydicom.uid import generate_uid

        # The instance to be added
        ds = examples.ct

        # Define the leaf node (the PRIVATE record)
        record = Dataset()
        record.DirectoryRecordType = "PRIVATE"
        record.PrivateRecordUID = generate_uid()
        leaf_node = RecordNode(record)

        # Define the top node (the PATIENT record)
        record = Dataset()
        record.DirectoryRecordType = "PATIENT"
        record.PatientID = ds.PatientID
        record.PatientName = ds.PatientName
        top_node = RecordNode(record)

        # Set the node relationship
        leaf_node.parent = top_node

        # Add the instance to the File-set
        fs = FileSet()
        instance = fs.add_custom(ds, leaf_node)

    Parameters:

      - ds_or_path (pydicom.dataset.Dataset, str or PathLike) – The instance to add to the File-set, either as a `Dataset` or the path to the instance.

      - leaf (pydicom.fileset.RecordNode) – The leaf node for the instance, should have its ancestors nodes set correctly as well as their corresponding directory records. Should have no more than 7 ancestors due to the semantics used by `FileSet` when creating the directory structure.

    Returns:

      The `FileInstance` that was added.

    Return type:

      FileInstance

    See also

    `add()`

  clear() → None

    Clear the File-set.

  copy(path: str | PathLike, force_implicit: bool = False) → FileSet

    Copy the File-set to a new root directory and return the copied File-set.

    Changes staged to the original `FileSet` will be applied to the new File-set. The original `FileSet` will remain staged.

    Parameters:

      - path (str or PathLike) – The root directory where the File-set is to be copied to.

      - force_implicit (bool, optional) – If `True` force the DICOMDIR file to be encoded using Implicit VR Little Endian which is non-conformant to the DICOM Standard (default `False`).

    Returns:

      The copied File-set as a `FileSet`.

    Return type:

      pydicom.fileset.FileSet

  property descriptor_character_set: str | None

    Return the Specific Character Set of File-set Descriptor File (if available) or `None`.

  property descriptor_file_id: str | None

    Return the File-set Descriptor File ID (if available) or `None`.

  find(load: bool = False, **kwargs: Any) → list[FileInstance]

    Return matching instances in the File-set

    Limitations

    - Only single value matching is supported so neither `PatientID=['1234567', '7654321']` or `PatientID='1234567', PatientID='7654321'` will work (although the first example will work if the Patient ID is actually multi-valued).

    - Repeating group and private elements cannot be used when searching.

    Parameters:

      - load (bool, optional) – If `True`, then load the SOP Instances belonging to the File-set and perform the search against their available elements. Otherwise (default) search only the elements available in the corresponding directory records (more efficient, but only a limited number of elements are available).

      - **kwargs – Search parameters, as element keyword=value (i.e. `PatientID='1234567', StudyDescription="My study"`.

    Returns:

      A list of matching instances.

    Return type:

      list of pydicom.fileset.FileInstance

  find_values(elements: str | int | list[str | int], instances: list[FileInstance] | None = None, load: bool = False) → list[Any] | dict[str | int, list[Any]]

    Return a list of unique values for given element(s).

    Parameters:

      - elements (str, int or pydicom.tag.BaseTag, or list of these) – The keyword or tag of the element(s) to search for.

      - instances (list of pydicom.fileset.FileInstance, optional) – Search within the given instances. If not used then all available instances will be searched.

      - load (bool, optional) – If `True`, then load the SOP Instances belonging to the File-set and perform the search against their available elements. Otherwise (default) search only the elements available in the corresponding directory records (more efficient, but only a limited number of elements are available).

    Returns:

      - If single element was queried: A list of value(s) for the element available in the instances.

      - If list of elements was queried: A dict of element value pairs with lists of value(s) for the elements available in the instances.

    Return type:

      list of object(s), or dict of lists of object(s)

  property is_staged: bool

    Return `True` if the File-set is new or has changes staged.

  load(ds_or_path: Dataset | str | PathLike, include_orphans: bool = True, raise_orphans: bool = False) → None

    Load an existing File-set.

    Existing File-sets that do not use the same directory structure as pydicom will be staged to be moved to a new structure. This is because the DICOM Standard attaches no semantics to how the files in a File-set are to be structured so it’s impossible to determine what the layout will be when changes are to be made.

    Parameters:

      - ds_or_path (pydicom.dataset.Dataset, str or PathLike) – An existing File-set’s DICOMDIR, either as a `Dataset` or the path to the DICOMDIR file as `str` or pathlike.

      - include_orphans (bool, optional) – If `True` (default) include instances referenced by orphaned directory records in the File-set.

      - raise_orphans (bool, optional) – If `True` then raise an exception if orphaned directory records are found in the File-set (default `False`).

  property path: str | None

    Return the absolute path to the File-set root directory as `str` (if set) or `None` otherwise.

  remove(instance: FileInstance | list[FileInstance]) → None

    Stage instance(s) for removal from the File-set.

    If the instance has been staged for addition to the File-set, calling `remove()` will cancel the staging and the instance will not be added.

    Parameters:

      instance (pydicom.fileset.FileInstance or a list of FileInstance) – The instance(s) to remove from the File-set.

  property root_path: Path

    Return the absolute path to the File-set root directory as `pathlib.Path`.

    Raises:

      AttributeError – If the root path is not set.

  write(path: str | PathLike | None = None, use_existing: bool = False, force_implicit: bool = False) → None

    Write the File-set, or changes to the File-set, to the file system.

    Warning

    If modifying an existing File-set it’s strongly recommended that you follow standard data management practices and ensure that you have an up-to-date backup of the original data.

    By default, for both new or existing File-sets, pydicom uses the following directory structure semantics when writing out changes:

    - For instances defined using the standard four-levels of directory records (i.e. PATIENT/STUDY/SERIES + one of the record types such as IMAGE or RT DOSE): `PTxxxxxx/STxxxxxx/SExxxxxx/` with a filename such as `IMxxxxxx` (for IMAGE), where the first two characters are dependent on the record type and `xxxxxx` is a numeric or alphanumeric index.

    - For instances defined using the standard one-level directory record (i.e. PALETTE, IMPLANT): a filename such as `PAxxxxxx` (for PALETTE).

    - For instances defined using PRIVATE directory records then the structure will be along the lines of `P0xxxxxx/P1xxxxxx/P2xxxxxx` for PRIVATE/PRIVATE/PRIVATE, `PTxxxxxx/STxxxxxx/P2xxxxxx` for PATIENT/STUDY/PRIVATE.

    When only changes to the DICOMDIR file are required or instances have only been removed from an existing File-set you can use the use_existing keyword parameter to keep the existing directory structure and only update the DICOMDIR file.

    Parameters:

      - path (str or PathLike, optional) – For new File-sets, the absolute path to the root directory where the File-set will be written. Using path with an existing File-set will raise `ValueError`.

      - use_existing (bool, optional) – If `True` and no instances have been added to the File-set (removals are OK), then only update the DICOMDIR file, keeping the current directory structure rather than converting everything to the semantics used by pydicom for File-sets (default `False`).

      - force_implicit (bool, optional) – If `True` force the DICOMDIR file to be encoded using Implicit VR Little Endian which is non-conformant to the DICOM Standard (default `False`).

    Raises:

      ValueError – If use_existing is `True` but instances have been staged for addition to the File-set.