dbdicom.Series.values#

Series.values(*tags, dims=('InstanceNumber',), return_coords=False, mesh=True, slice={}, coords={}, exclude=False, **filters) → ndarray[source]#

Return the values of one or more attributes for each frame in the series.

Parameters:

  • tag (str or tuple) – either a keyword string or a (group, element) tag of a DICOM data element.

  • dims (tuple, optional) – Dimensions of the resulting array. If dims is not provided, values are ordered by InstanceNumber. Defaults to None.

  • inds (dict, optional) – Dictionary with indices to retrieve a slice of the entire array. Defaults to None.

  • select (dict, optional) – A dictionary of values for DICOM attributes to filter the result. By default the data are not filtered.

  • filters (dict, optional) – keyword arguments to filter the data by value of DICOM attributes.

Returns:

An numpy.ndarray of values with dimensions as specified by dims. If the value is not defined in one or more of the slices, an empty array is returned.

See also

unique coords gridcoords

Note

In order to list the values in the case one or more are absent in the headers, use Series.unique() instead.

Example

Create a zero-filled series with 3 slice dimensions:

>>> coords = {
...     'SliceLocation': 10*np.arange(4),
...     'FlipAngle': np.array([2, 15, 30]),
...     'RepetitionTime': np.array([2.5, 5.0]), }
>>> zeros = db.zeros((128,128,4,3,2), coords)

# If values() is called without dimensions, a flat array is returned with one value per frame, ordered by instance number:

>>> zeros.values('InstanceNumber')
[1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,191,20,21,22,23,24]
>>> zros.values('FlipAngle')
[2,2,15,15,30,30,2,2,15,15,30,30,2,2,15,15,30,30,2,2,15,15,30,30]

if dimensions are provided, an array of the appropriate shape is returned:

>>> dims = tuple(coords)
>>> tacq = series.values('AcquisitionTime', dims)
>>> tacq.shape
(4,3,2)
>>> tacq[0,0,0]
28609.057496

In this case all values are the same:

>>> np.unique(tacq)
[28609.057496]

If a value is not defined in the header, None is returned: >>> series.values(‘Gobbledigook’)[:2] [None None]

Specify keywords to select a subset of values:

>>> tacq = zeros.values('AcquisitionTime', dims, FlipAngle=15)
>>> tacq.shape
(4, 1, 2)

If none exist, and emptry array is returned:

>>> tacq = zeros.values('AcquisitionTime', dims, FlipAngle=0)
>>> tacq.size
0

Multiple possible values can be selected with arrays:

>>> tacq = zeros.values('AcquisitionTime', dims, FlipAngle=np.array([15,30]))
>>> tacq.shape
(4, 2, 2)

Any number of keywords can be added as filters:

>>> tacq = zeros.values('AcquisitionTime', dims, FlipAngle=np.array([15,30]), SliceLocation=np.array([10,20]))
>>> tacq.shape
(2, 2, 2)

Filters can alos be set using the select argument:

>>> tacq = zeros.values('AcquisitionTime', dims, select={'FlipAngle': 15})
>>> tacq.shape
(4, 1, 2)

This also allows (group, element) tags:

>>> tacq = zeros.values('AcquisitionTime', dims, select={(0x0018, 0x1314): 15})
>>> tacq.shape
(4, 1, 2)

Selections can also be made using indices rather than values:

>>> tacq = zeros.values('FlipAngle', dims, inds={'FlipAngle': 1})
>>> tacq.shape
(4, 1, 2)

>>> tacq = zeros.values('AcquisitionTime', dims, inds={'FlipAngle':np.arange(2)})
>>> tacq.shape
(4, 2, 2)
On this page

This Page