dbdicom.Series.split_by#

Series.split_by(keyword: str | tuple) → list[source]#

Split the series into multiple subseries based on keyword value.

Parameters:

keyword (str | tuple) – A valid DICOM keyword or hexadecimal (group, element) tag.

Raises:

ValueError – if an invalid or missing keyword is provided.
ValueError – if all images have the same value for the keyword, so no subseries can be derived. An exception is raised rather than a copy of the series to avoid unnecessary copies being made. If that is the intention, use series.copy() instead.

Returns:

A list of Series instances, where each element has the same value of the given keyword.

Return type:

list

See also

subseries()

Example

Create a single-slice series with multiple flip angles and repetition times:

>>> coords = {
...    'FlipAngle': [2, 15, 30],
...    'RepetitionTime': [2.5, 7.5],
... }
>>> zeros = db.zeros((128, 128, 3, 2), coords)
>>> zeros.print()
---------- SERIES --------------
Series 001 [New Series]
    Nr of instances: 6
        MRImage 000001
        MRImage 000002
        MRImage 000003
        MRImage 000004
        MRImage 000005
        MRImage 000006
--------------------------------

Splitting this series by FlipAngle now creates 3 new series in the same study, with 2 images each. By default the fixed value of the splitting attribute is written in the series description:

>>> FA = zeros.split_by('FlipAngle')
>>> zeros.study().print()
---------- STUDY ---------------
Study New Study [None]
    Series 001 [New Series]
        Nr of instances: 6
    Series 002 [New Series[FlipAngle = 2.0]]
        Nr of instances: 2
    Series 003 [New Series[FlipAngle = 15.0]]
        Nr of instances: 2
    Series 004 [New Series[FlipAngle = 30.0]]
        Nr of instances: 2
--------------------------------

Check the flip angle of the split series: >>> for series in FA: … print(series.FlipAngle) 2.0 15.0 30.0