dbdicom 0.2.1__py3-none-any.whl → 0.2.4__py3-none-any.whl

dbdicom/types/series.py

@@ -3,15 +3,18 @@ from __future__ import annotations
 
 import os
 import math
+from numbers import Number
 
 import numpy as np
 import nibabel as nib
+import vreg
+
 
 from dbdicom.record import Record, read_dataframe_from_instance_array
 from dbdicom.ds import MRImage
 import dbdicom.utils.image as image_utils
 from dbdicom.manager import Manager
-# import dbdicom.wrappers.scipy as scipy_utils
+# import dbdicom.extensions.scipy as scipy_utils
 from dbdicom.utils.files import export_path
 
 
@@ -50,6 +53,8 @@ class Series(Record):
 
     # replace by clone(). Adopt implies move rather than copy
     def adopt(self, instances): 
+        if len(instances)==0:
+            return []
         uids = [i.uid for i in instances]
         uids = self.manager.copy_to_series(uids, self.uid, **self.attributes)
         if isinstance(uids, list):
@@ -65,10 +70,6 @@ class Series(Record):
         else:
             return self.record('Instance', uids, **attr)
 
-
-
-
-
     def export_as_dicom(self, path): 
         folder = self.label()
         path = export_path(path, folder)
@@ -81,24 +82,22 @@ class Series(Record):
             mgr.import_dataset(ds)
         copy.remove()
 
-
     def export_as_png(self, path, **kwargs):
         #Export all images as png files
         folder = self.label()
         path = export_path(path, folder)
         images = self.images()
         for i, img in enumerate(images):
-            img.status.progress(i+1, len(images), 'Exporting png..')
+            img.progress(i+1, len(images), 'Exporting png..')
             img.export_as_png(path, **kwargs)
 
-
     def export_as_csv(self, path):
         #Export all images as csv files
         folder = self.label()
         path = export_path(path, folder)
         images = self.images()
         for i, img in enumerate(images):
-            img.status.progress(i+1, len(images), 'Exporting csv..')
+            img.progress(i+1, len(images), 'Exporting csv..')
             img.export_as_csv(path)
 
     def export_as_npy(self, path, dims=None):
@@ -110,13 +109,12 @@ class Series(Record):
                 img.progress(i+1, len(images), 'Exporting npy..')
                 img.export_as_npy(path)
         else:
-            array = self.ndarray(dims)
+            array = self.pixel_values(dims)
             filepath = self.label()
             filepath = os.path.join(path, filepath + '.npy')
             with open(filepath, 'wb') as f:
                 np.save(f, array)
 
-
     def export_as_nifti(self, path, dims=None):
         if dims is None:
             folder = self.label()
@@ -142,469 +140,1724 @@ class Series(Record):
                 filepath = os.path.join(path, filepath + '[' + str(i) + '].nii')
                 nib.save(nifti1_image, filepath)
 
-
     def import_dicom(self, files):
         uids = self.manager.import_datasets(files)
         self.manager.move_to(uids, self.uid)
 
 
 
-    def subseries(self, **kwargs)->Series:
-        """Extract a subseries based on values of header elements.
+    def coords(self, dims=('InstanceNumber', ), mesh=False, slice={}, coords={}, exclude=False, **filters)->dict:
+        """return a dictionary of coordinates.
 
         Args:
-            kwargs: Any number of valid DICOM (tag, value) keyword arguments.
+            dims (tuple, optional): Dimensions along which the shape is to be determined. If dims is not provided, they default to InstanceNumber. 
+
+        Raises:
+            ValueError: If the dimensions do not produce suitable coordinates.
 
         Returns:
-            Series: a new series as a sibling under the same parent.
+            dict: dictionary of coordinates, one entry for each dimension. The values for each coordinate are returned as an darray with one dimension.
 
-        See Also:
-            :func:`~split_by`
+        See also:
+            `set_coords`
 
         Example:
 
-            Create a multi-slice series with multiple flip angles and repetition times:
+            Create an empty series with 3 slice dimensions:
 
             >>> coords = {
-            ...    'SliceLocation': np.arange(16),
-            ...    'FlipAngle': [2, 15, 30],
-            ...    'RepetitionTime': [2.5, 5.0, 7.5],
+            ...     'SliceLocation': np.array([0,1,2,0,1,2]),
+            ...     'FlipAngle': np.array([2,2,2,10,10,10]),
+            ...     'RepetitionTime': np.array([1,5,15,1,5,15]),
             ... }
-            >>> zeros = db.zeros((128, 128, 16, 3, 2), coords)
-
-            Create a new series containing only the data with flip angle 2 and repetition time 7.5:
+            >>> series = db.empty_series(coords)
+            
+            Retrieve the coordinates:
 
-            >>> volume = zeros.subseries(FlipAngle=2.0, RepetitionTime=7.5)
+            >>> coords = series.coords(tuple(coords))
+            >>> coords['FlipAngle']
+            [2,10,2,10,2,10]
+            >>> coords['RepetitionTime']
+            [1,1,5,5,15,15]
 
-            Check that the volume series now has two dimensions of size 1:
+            Check the result in default dimensions:
 
-            >>> array = volume.ndarray(dims=tuple(coords))
-            >>> print(array.shape)
-            (128, 128, 16, 1, 1)
+            >>> coords = series.coords()
+            >>> coords['InstanceNumber']
+            [1,2,3,4,5,6]
 
-            and only one flip angle and repetition time:
+            In this case the slice location and flip angle along are sufficient to identify the frames, so these are valid coordinates:
 
-            >>> print(volume.FlipAngle, volume.RepetitionTime)
-            2.0 7.5
+            >>> coords = series.coords(('SliceLocation', 'FlipAngle'))
+            >>> coords['SliceLocation']
+            [0,0,1,1,2,2]
 
-            and that the parent study now has two series:
+            # However slice location and acquisition time are not sufficient as coordinates because each combination appears twice. So this throws an error:
 
-            >>> volume.study().print()
-            ---------- STUDY ---------------
-            Study New Study [None]
-            Series 001 [New Series]
-                Nr of instances: 96
-            Series 002 [New Series]
-                Nr of instances: 16
-            --------------------------------
+            >>> series.coords(('SliceLocation','RepetitionTime'))
+            ValueError: These are not proper coordinates. Coordinate values must be unique.
         """
-        return subseries(self, move=False, **kwargs)
 
+        if np.isscalar(dims):
+            dims = (dims,)
+
+        # Default empty coordinates
+        vcoords = {}
+        for i, tag in enumerate(dims):
+            vcoords[tag] = np.array([])
+        
+        # Get all frames and return if empty
+        frames = self.instances()
+        if frames == []:
+            return vcoords
+         
+        # Read values and sort
+        fltr = {**slice, **filters}
+        values = [f[list(dims)+list(fltr)+list(tuple(coords))] for f in frames]
+        values.sort()
+
+        # Check dimensions
+        cvalues = [v[:len(dims)] for v in values]
+        cvalues = np.array(cvalues).T
+        _check_if_ivals(cvalues)
+
+        # Filter values
+        values = _filter_values(values, fltr, coords, exclude=exclude)
+
+        # If requested, mesh values
+        if mesh:
+            values = _meshvals(values)
+            mshape = values.shape[1:]
+
+        # Build coordinates
+        if values.size > 0:
+            for i, tag in enumerate(dims):
+                vcoords[tag] = values[i,...]
+                if mesh: # Is this necessary? Is already in the right shape
+                    vcoords[tag] = vcoords[tag].reshape(mshape)
+
+        return vcoords
     
-    def split_by(self, keyword: str | tuple) -> list:
-        """Split the series into multiple subseries based on keyword value.
 
-        Args:
-            keyword (str | tuple): A valid DICOM keyword or hexadecimal (group, element) tag.
+    def values(self, *tags, dims=('InstanceNumber', ), return_coords=False, mesh=True, slice={}, coords={}, exclude=False, **filters)->np.ndarray:
+        """Return the values of one or more attributes for each frame in the series.
 
-        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.
+        Args:
+            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:
-            list: A list of ``Series`` instances, where each element has the same value of the given keyword.
+            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:
-            :func:`~subseries`
+        See also:
+            `unique`
+            `coords`
+            `gridcoords`
 
-        Example: 
+        Note:
+            In order to list the values in the case one or more are absent in the headers, use `Series.unique()` instead.
 
-            Create a single-slice series with multiple flip angles and repetition times:
+        Example:
+
+            Create a zero-filled series with 3 slice dimensions:
 
             >>> 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
-            --------------------------------
+            ...     '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)
 
-            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:
+            # If values() is called without dimensions, a flat array is returned with one value per frame, ordered by instance number:
 
-            >>> 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
-            --------------------------------
+            >>> 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]
 
-            Check the flip angle of the split series:
-            >>> for series in FA: 
-            ...     print(series.FlipAngle)
-            2.0
-            15.0
-            30.0
-        """
-        
-        self.status.message('Reading values..')
-        try:
-            values = self[keyword]
-        except:
-            msg = str(keyword) + ' is not a valid DICOM keyword'
-            raise ValueError(msg)
-        if len(values) == 1:
-            msg = 'Cannot split by ' + str(keyword) + '\n' 
-            msg += 'All images have the same value'
-            raise ValueError(msg)
-        
-        self.status.message('Splitting series..')
-        split_series = []
-        desc = self.instance().SeriesDescription + '[' + keyword + ' = '
-        for v in values:
-            kwargs = {keyword: v}
-            new = self.subseries(**kwargs)
-            new.SeriesDescription = desc + str(v) + ']'
-            split_series.append(new)
-        return split_series
+            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
 
-    # TODO: This needs the same API as ndarray with coord and slice arguments.
-    # TODO: This also needs a set_slice_group.
-    # TODO: Currently based on image orientation only rather than complete affine.
-    def slice_groups(self, dims=('InstanceNumber',)) -> list:
-        """Return a list of slice groups in the series.
+            In this case all values are the same:
 
-        In dbdicom, a *slice group* is defined as a series of slices that have the same orientation. It is common for a single series to have images with multiple orientations, such as in localizer series in MRI. For such a series, returning all data in a single array may not be meaningful. 
+            >>> np.unique(tacq)
+            [28609.057496]
 
-        Formally, a *slice group* is a dictionary with two entries: 'ndarray' is the numpy.ndarray with the data along the dimensions provided by the dims argument, and 'affine' is the 4x4 affine matrix of the slice group. The function returns a list of such dictionaries, one for each slice group in the series.
+            If a value is not defined in the header, None is returned:
+            >>> series.values('Gobbledigook')[:2]
+            [None None]
 
-        Args:
-            dims (tuple, optional): Dimensions for the returned arrays. Defaults to ('InstanceNumber',).
+            Specify keywords to select a subset of values:
 
-        Returns:
-            list: A list of slice groups (dictionaries), one for each slice group in the series.
+            >>> tacq = zeros.values('AcquisitionTime', dims, FlipAngle=15)
+            >>> tacq.shape
+            (4, 1, 2)
 
-        Examples:
+            If none exist, and emptry array is returned:
 
-            >>> series = db.ones((128,128,5,10))
-            >>> sgroups = series.slice_groups(dims=('SliceLocation', 'AcquisitionTime'))
+            >>> tacq = zeros.values('AcquisitionTime', dims, FlipAngle=0)
+            >>> tacq.size
+            0
 
-            Since there is only one slice group in the series, ``sgroups`` is a list with one element:
+            Multiple possible values can be selected with arrays:
 
-            >>> print(len(sgroups))
-            1
+            >>> tacq = zeros.values('AcquisitionTime', dims, FlipAngle=np.array([15,30]))
+            >>> tacq.shape
+            (4, 2, 2)
 
-            The array of the slice group is the entire volume of the series:
+            Any number of keywords can be added as filters:
 
-            >>> print(sgroups[0]['ndarray'].shape)
-            (128, 128, 5, 10)
+            >>> tacq = zeros.values('AcquisitionTime', dims, FlipAngle=np.array([15,30]), SliceLocation=np.array([10,20]))
+            >>> tacq.shape
+            (2, 2, 2)
 
-            And the affine of the series has not changed from the default (identity):
+            Filters can alos be set using the *select* argument: 
 
-            >>> print(sgroups[0]['affine'])
-            [[1. 0. 0. 0.]
-             [0. 1. 0. 0.]
-             [0. 0. 1. 0.]
-             [0. 0. 0. 1.]]
+            >>> 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)
         """
+
+        if np.isscalar(dims):
+            dims = (dims,)
+
+        # Default return values
+        values = np.array([]).reshape((0,0))
+        vcoords = {}
+        for i, tag in enumerate(dims):
+            vcoords[tag] = np.array([])
         
-        slice_groups = []
-        image_orientation = self.ImageOrientationPatient
+        # Get all frames and return if empty
+        frames = self.instances()
+        if frames == []:
+            if return_coords:
+                return values, vcoords
+            return values
+              
+        # Read values and sort
+        filters = {**slice, **filters}
+        values = []
+        for i, f in enumerate(frames):
+            self.progress(i+1,len(frames), 'Reading values..')
+            v = f[list(dims)+list(tags)+list(tuple(filters))+list(tuple(coords))]
+            values.append(v)
+        fsort = sorted(range(len(values)), key=lambda k: values[k][:len(dims)])
+        values = [values[i] for i in fsort]
+        
+        # Check if dimensions are proper
+        # Need object array here because the values can be different type including lists.
+        cvalues = [v[:len(dims)] for v in values]
+        cvalues = np.array(cvalues, dtype=object).T
+        _check_if_ivals(cvalues)
+
+        # Filter values
+        values = _filter_values(values, filters, coords, exclude=exclude)
+        if values.size == 0:
+            if return_coords:
+                if len(tags) == 1: 
+                    return values, vcoords
+                else:
+                    values = [np.array([]) for _ in range(len(tags))]
+                    return tuple(values) + (vcoords,)
+            return values
+        cvalues = values[:len(dims),:]
+        values = values[len(dims):,:]
+
+        # If requested, mesh values
+        if mesh:
+            cmesh = _meshvals(cvalues)
+            values = _meshdata(values, cvalues, cmesh)
+            cvalues = cmesh
+            
+        # Create return values
+        if len(tags) == 1:
+            values = values[0,...]
+        else:
+            values = [values[i,...] for i in range(values.shape[0])]
+            values = tuple(values)
+
+        if return_coords:
+            for i, tag in enumerate(dims):
+                vcoords[tag] = cvalues[i,...] 
+            if len(tags) == 1: 
+                return values, vcoords
+            else:
+                return values + (vcoords,)
+        else:
+            return values
 
-        # Multiple slice groups in series - return list of cuboids
-        if isinstance(image_orientation[0], list):
-            for dir in image_orientation:
-                slice_group = instance_array(self, ImageOrientationPatient=dir)
-                affine = _slice_group_affine_matrix(list(slice_group), dir)
-                array, _ = _get_pixel_array_from_instance_array(slice_group, sortby=list(dims), pixels_first=True)
-                slice_groups.append({'ndarray': array[...,0], 'affine': affine})
+
+
+
+
+    def frames(
+            self, dims=('InstanceNumber', ), return_coords=False, 
+            return_vals=(), mesh=True, slice={}, coords={}, exclude=False, 
+            **filters):
+        """Return the frames of given coordinates in the correct order"""
+
+        if np.isscalar(dims):
+            dims = (dims,)
+
+        # Default return values
+        values = np.array([]).reshape((0,0))
+        vcoords = {}
+        for i, tag in enumerate(dims):
+            vcoords[tag] = np.array([])
+        if mesh:
+            fshape = tuple([0]*len(dims))
+        else:
+            fshape = (0,)
+            
+        # Get all frames and return if empty
+        frames_sel = self.instances()
+        if frames_sel == []:
+
+            # Empty return values
+            frames = np.array([]).reshape(fshape)
+            rval = (frames,)
+            if return_coords:
+                rval += (vcoords, )
+            if return_vals != ():
+                rval += (values, )
+            if len(rval)==1:
+                return rval[0]
+            else:
+                return rval
+              
+        # Read values and sort
+        filters = {**slice, **filters}
+        values = [f[list(dims)+list(return_vals)+list(tuple(filters))+list(tuple(coords))] for f in frames_sel]
+        fsort = sorted(range(len(values)), key=lambda k: values[k][:len(dims)])
+        values = [values[i] for i in fsort]
+
+        # Check dimensions
+        cvalues = [v[:len(dims)] for v in values]
+        cvalues = np.array(cvalues).T
+        _check_if_ivals(cvalues)
+
+        # Create array of frames.
+        frames = np.empty(len(frames_sel), dtype=object)
+        for i in range(len(fsort)):
+            frames[i] = frames_sel[fsort[i]]
+
+        # Filter values
+        finds = _filter_values_ind(values, filters, coords, exclude=exclude)
+        if finds.size==0:
+            # Empty return values
+            frames = np.array([]).reshape(fshape)
+            rval = (frames,)
+            if return_coords:
+                rval += (vcoords, )
+            if return_vals != ():
+                rval += (np.array([]), )
+            if len(rval)==1:
+                return rval[0]
+            else:
+                return rval           
+        frames = frames[finds]
+        values = _filter_values(values, filters, coords, exclude=exclude)
+        cvalues = values[:len(dims),:]
+        values = values[len(dims):,:]
+
+        # If requested, mesh values
+        if mesh:
+            cmesh = _meshvals(cvalues)
+            values = _meshdata(values, cvalues, cmesh)
+            frames = _meshdata(frames.reshape((1,frames.size)), cvalues, cmesh)
+            frames = frames[0,...]
+            cvalues = cmesh
+            
+        # Create return values
+        rval = (frames,)
+        if return_coords:
+            for i, tag in enumerate(dims):
+                vcoords[tag] = cvalues[i,...] 
+            rval += (vcoords, )
+        if return_vals != ():
+            rval += (values, )
+        if len(rval)==1:
+            return rval[0]
+        else:
+            return rval
         
-        # Single slice group in series - return a list with a single affine matrix
+
+    def expand(self, coords={}, gridcoords={}): # gridcoords -> slice
+
+        if coords != {}:
+            pass
+        elif gridcoords != {}:
+            coords = _grid_to_coords(gridcoords)
         else:
-            slice_group = instance_array(self)
-            affine = _slice_group_affine_matrix(list(slice_group), image_orientation)
-            array, _ = _get_pixel_array_from_instance_array(slice_group, sortby=list(dims), pixels_first=True)
-            slice_groups.append({'ndarray': array[...,0], 'affine': affine})
+            msg = 'Cannot expand without new coordinates'
+            raise ValueError(msg)
 
-        return slice_groups
+        # If the series is not empty, first check that the new coordinates are valid.
+        if not self.empty():
+            current_coords = self.coords(tuple(coords))
+            try:
+                _concatenate_coords((current_coords, coords))
+            except:
+                msg = 'Cannot expand - the new coordinates overlap with existing coordinates.'
+                raise ValueError(msg)
         
+        # Expand the series to the new coordinates
+        size = _coords_size(coords)
+        for i in range(size):
+            ds = self.init_dataset()
+            for c in coords:
+                ds.set_values(c, coords[c].ravel()[i])
+            self.new_instance(ds)
 
-    def affine(self)->list:
-        """Return a list of unique affine matrices in the series
 
-        Raises:
-            ValueError: if the file is corrupted and necessary DICOM attributes are not included.
+    def set_coords(self, new_coords:dict, dims=(), slice={}, coords={}, **filters):
+        """Set a dictionary of coordinates.
 
-        Returns:
-            list: list of 4x4 ndarrays with the unique affine matrices of the series.
+        Args:
+            coords (dict): Dictionary of coordinates.
+            dims (tuple, optional): Dimensions of at which the new coordinates are to be best. If *dims* is not set, the dimensions are assumed to be the same as those of *coords* or *grid*. Defaults to None.
+
+        Raises:
+            ValueError: if the coordinates provided are not properly formatted or have the wrong shape.
 
         See also:
-            :func:`~set_affine`
+            `coords`
+            `set_gridcoords`
 
         Example:
-            Check that the default affine is the identity:
 
-            >>> zeros = db.zeros((128,128,10))
-            >>> print(zeros.affine())
-            [array([
-                [1., 0., 0., 0.],
-                [0., 1., 0., 0.],
-                [0., 0., 1., 0.],
-                [0., 0., 0., 1.]], dtype=float32)]
+            Create an empty series:
 
-            Note this is a list of one single element as the series only has a single slice group.
-        """
-        image_orientation = self.ImageOrientationPatient
-        if image_orientation is None:
-            msg = 'ImageOrientationPatient not defined in the DICOM header \n'
-            msg += 'This is a required DICOM field \n'
-            msg += 'The data may be corrupted - please check'
-            raise ValueError(msg)
-        # Multiple slice groups in series - return list of affine matrices
-        if isinstance(image_orientation[0], list):
-            affine_matrices = []
-            for dir in image_orientation:
-                slice_group = self.instances(ImageOrientationPatient=dir)
-                affine = _slice_group_affine_matrix(slice_group, dir)
-                affine_matrices.append(affine)
-            return affine_matrices
-        # Single slice group in series - return a list with a single affine matrix
-        else:
-            slice_group = self.instances()
-            affine = _slice_group_affine_matrix(slice_group, image_orientation)
-            return [affine]
+            >>> coords = {
+            ...     'SliceLocation': np.array([0,1,2,0,1,2]),
+            ...     'FlipAngle': np.array([2,2,2,10,10,10]),
+            ...     'RepetitionTime': np.array([1,5,15,1,5,15]),
+            ... }
+            >>> series = db.empty_series(coords)
+            
+            Change the flip angle of 15 to 12:
 
+            >>> coords = series.coords(tuple(coords))
+            >>> fa = coords['FlipAngle']
+            >>> fa[np.where(fa==2)] = 5
+            >>> series.set_coords(coords)
 
-    def set_affine(self, affine:np.eye()):
-        """Set the affine matrix of a series.
+            Check the new coordinates:
 
-        The affine is defined as a 4x4 numpy array with bottom row [0,0,0,1]. The final column represents the position of the top right hand corner of the first slice. The first three columns represent rotation and scaling with respect to the axes of the reference frame.
+            >>> new_coords = series.coords(dims)
+            >>> new_coords['FlipAngle']
+            [5,10,5,10,5,10]
+
+            Create a new set of coordinates along slice location and acquisition time:
+
+            >>> new_coords = {
+            ...     'SliceLocation': np.array([0,0,1,1,2,2]),
+            ...     'AcquisitionTime': np.array([0,60,0,60,0,60]),
+            ... }
+            >>> series.set_coords(new_coords, ('SliceLocation', 'FlipAngle'))
+
+            # Inspect the new coordinates - each slice now has two acquisition times corresponding to the flip angles:
+
+            >>> coords['SliceLocation']
+            [0,0,1,1,2,2]
+            >>> coords['AcquisitionTime']
+            [0,60,0,60,0,60]
+            >>> coords['FlipAngle']
+            [5,10,5,10,5,10]
+
+            # Check that an error is raised if coordinate values have different sizes:
+            >>> new_coords = {
+            ...     'SliceLocation': np.zeros(24),
+            ...     'AcquisitionTime': np.ones(25),
+            ... }
+            >>> series.set_coords(new_coords, dims)
+            ValueError: Coordinate values must all have the same size
+
+            # An error is also raised if they have all the same size but the values are not unique:
+
+            >>> new_coords = {
+            ...     'SliceLocation': np.zeros(24),
+            ...     'AcquisitionTime': np.ones(24),
+            ... }
+            >>> series.set_coords(new_coords, dims)
+            ValueError: Coordinate values must all have the same size
+
+            # .. or when the number does not match up with the size of the series:
+
+            >>> new_coords = {
+            ...     'SliceLocation': np.arange(25),
+            ...     'AcquisitionTime': np.arange(25),
+            ... }
+            >>> series.set_coords(new_coords, dims)
+            ValueError: Shape of coordinates does not match up with the size of the series.
+
+        """
+        if dims == ():
+            dims = tuple(new_coords)
+        elif np.isscalar(dims):
+            dims = (dims,)
+        new_coords = _check_if_coords(new_coords)
+        frames = self.frames(dims, slice=slice, coords=coords, **filters)
+        if frames.size == 0:
+            # If the series is empty, assignment of coords is unambiguous
+            self.expand(new_coords)
+        else:
+            size = _coords_size(new_coords)
+            if size != frames.size:
+                msg = 'Cannot set ' + str(size) + ' coordinates in ' + str(frames.size) + ' frames.'
+                msg += '\nThe number of new coordinates must equal the number of frames.'
+                raise ValueError(msg)
+            # If setting a subset, check if the new set of coordinates is valid
+            if len({**slice, **coords, **filters}) > 0:
+                complement = self.coords(dims, slice=slice, coords=coords, exclude=True, **filters)
+                if _coords_size(complement) > 0:
+                    try:
+                        _concatenate_coords((new_coords, complement))
+                    except:
+                        msg = 'Cannot set coordinates - this would produce invalid coordinates for the series'
+                        raise ValueError(msg)
+            frames = frames.flatten()
+            values = _coords_vals(new_coords)
+            for f, frame in enumerate(frames):
+                frame[list(new_coords)] = list(values[:,f])
+
+
+    def set_values(self, values, tags, dims=('InstanceNumber', ), slice={}, coords={}, **filters):
+        # Note tags, values is a more logical order considering we have self.values(tags)
+        """Set the values of an attribute.
 
         Args:
-            affine (numpy.ndarray): 4x4 numpy array 
+            tag: either a keyword string or a (group, element) tag of a DICOM data element.
+            value: a single value or a numpy array of values for the attribute. 
+            dims (tuple, optional): Dimensions of *value*. If *value* is a single value, *dims* is ignored. Otherwise, if *dim* is not provided, values are ordered by instance number. Defaults to None.
 
-        Raises:
-            ValueError: if the series is empty. The information of the affine matrix is stored in the header and can not be stored in an empty series.
+        Raises: 
+            ValueError: if the size of *value* does not match the size of the series.
 
         See also:
-            :func:`~affine`
+            `value`
 
         Example:
-            Create a series with unit affine array:
 
-            >>> zeros = db.zeros((128,128,10))
-            >>> print(zeros.affine())
-            [array([
-                [1., 0., 0., 0.],
-                [0., 1., 0., 0.],
-                [0., 0., 1., 0.],
-                [0., 0., 0., 1.]], dtype=float32)]
+            Create a zero-filled series with 3 slice dimensions.
 
-            Rotate the volume over 90 degrees in the xy-plane:
+            >>> loc = np.arange(4)
+            >>> fa = [2, 15, 30]
+            >>> tr = [2.5, 5.0]
+            >>> coords = {
+            ...     'SliceLocation': np.arange(4),
+            ...     'FlipAngle': [2, 15, 30],
+            ...     'RepetitionTime': [2.5, 5.0] }
+            >>> series = db.zeros((128,128,8,3,2), coords)
 
-            >>> affine = np.array([
-            ... [1., 0., 0., 0.],
-            ... [0., 1., 0., 0.],
-            ... [0., 0., 1., 0.],
-            ... [0., 0., 0., 1.],
-            ... ]) 
-            >>> zeros.set_affine(affine)
+            Change the acquisition time of the series to midnight (0 sec):
 
-            Apart from the rotation, also change the resolution to (3mm, 3mm, 1.5mm):
+            >>> series.value('AcquisitionTime')
+            28609.057496
+            >>> series.set_value('AcquisitionTime', 0)
+            >>> series.value('AcquisitionTime')
+            0
 
-            >>> affine = np.array([
-            ... [0., -3., 0., 0.],
-            ... [3., 0., 0., 0.],
-            ... [0., 0., 1.5, 0.],
-            ... [0., 0., 0., 1.],
-            ... ])  
-            >>> zeros.set_affine(affine)
+            Set the acquisition time to a different value for each flip angle:
 
-            # Now rotate, change resolution, and shift the top right hand corner of the lowest slice to position (-30mm, 20mm, 120mm):
+            >>> tacq = np.repeat(60*np.arange(3), 8)
+            >>> series.set_value('AcquisitionTime', tacq, dims=('FlipAngle','InstanceNumber'))
 
-            >>> affine = np.array([
-            ... [0., -3., 0., -30.],
-            ... [3., 0., 0., 20.],
-            ... [0., 0., 1.5, 120.],
-            ... [0., 0., 0., 1.],
-            ... ])  
-            >>> zeros.set_affine(affine)
+            Set the acquisition time to a different value for each flip angle and acquisition time:
 
-            Note changing the affine will affect multiple DICOM tags, such as slice location and image positions:
+            >>> tacq = np.repeat(60*np.arange(6), 4)
+            >>> series.set_value('AcquisitionTime', tacq, dims=('FlipAngle','RepetitionTime','SliceLocation'))
 
-            >>> print(zeros.SliceLocation)
-            [120.0, 121.5, 123.0, 124.5, 126.0, 127.5, 129.0, 130.5, 132.0, 133.5]
+            Note: the size of the value and of the series need to match up. If not, an error is raised:
 
-            In this case, since the slices are stacked in parallel to the z-axis, the slice location starts at the lower z-coordinate of 120mm and then increments slice-by-slice with the slice thickness of 1.5mm.
+            >>> series.set_value('AcquisitionTime', np.arange(25), dims=tuple(coords))
+            ValueError: The size of the value array is different from the size of the series.
+            The value array has shape (25,), but the series has shape (4, 3).
+
+        """  
+
+        if np.isscalar(dims):
+            dims = (dims,)
+
+        if not isinstance(values, tuple):
+            self.set_values((values,), (tags,), dims=dims, slice=slice, coords=coords, **filters)
+            return
+        
+        # Get frames to set:
+        frames = self.frames(dims, mesh=False, slice=slice, coords=coords, **filters)
+        if frames.size == 0:
+            msg = 'Cannot set values to an empty series. Use Series.expand() to create empty frames first.'
+            raise ValueError(msg)
         
+        # Check that values all have the proper format:
+        values = list(values)
+        for i, v in enumerate(values):
+            #if not isinstance(v, np.ndarray):
+            #    values[i] = np.full(frames.shape, v) 
+            if isinstance(v, np.ndarray):
+                if values[i].size != frames.size:
+                    msg = 'Cannot set values: number of values does not match number of frames.'
+                    raise ValueError(msg)
+                values[i] = values[i].ravel()
+    
+        # Set values
+        for f, frame in enumerate(frames):
+            self.progress(f+1, frames.size, 'Writing values..')
+            frame[list(tags)] = [v if np.isscalar(v) else v[f] for v in values]
+            #frame[list(tags)] = [v[f] for v in values]
+
+
+    def set_gridcoords(self, gridcoords:dict, dims=(), slice={}, coords={}, **filters):
+        """ Set a dictionary of grid coordinates.
+
+        Args:
+            coords (dict): dictionary of grid coordinates
+            dims (tuple, optional): Dimensions of at which the new coordinates are to be best. If *dims* is not set, the dimensions are assumed to be the same as those of *coords* or *grid*. Defaults to None.
+
+        See also:
+            `gridcoords`
+            `set_coords`
+
+        Examples:
+
+            Create an empty series with 3 slice dimensions:
+
+            >>> gridcoords = {
+            ...     'SliceLocation': np.arange(4),
+            ...     'FlipAngle': np.array([2, 15, 30]),
+            ...     'RepetitionTime': np.array([2.5, 5.0]),
+            ... }
+            >>> series = db.empty_series()
+            >>> series.set_gridcoords(gridcoords)
+
+            Get the coordinates as a mesh
+
+            >>> dims = tuple(gridcoords)
+            >>> coords = series.meshcoords(dims)
+            >>> coords['SliceLocation'].shape
+            (4, 3, 2)
+            >>> coords['FlipAngle'][1,1,1]
+            15
+        """
+        setcoords = _grid_to_coords(gridcoords)
+        self.set_coords(setcoords, dims=dims, slice=slice, coords=coords, **filters)
+
+
+    def gridcoords(self, dims=('InstanceNumber', ), slice={}, coords={}, exclude=False, **filters)->dict:
+        """return a dictionary of grid coordinates.
+
+        Args:
+            dims (tuple): Attributes to be used as coordinates.
+
+        Returns:
+            dict: dictionary of coordinates, one entry for each dimension.
+
+        See also:
+            `coords`
+            `set_gridcoords`
+
+        Examples:
+
+            Create an empty series with 3 slice dimensions:
+
+            >>> gridcoords = {
+            ...     'SliceLocation': np.arange(4),
+            ...     'FlipAngle': np.array([2, 15, 30]),
+            ...     'RepetitionTime': np.array([2.5, 5.0]),
+            ... }
+            >>> series = db.empty_series(gridcoords=gridcoords)
+
+            Recover the grid coordinates:
+
+            >>> gridcoords_rec = series.gridcoords(tuple(gridcoords))
+            >>> coords_rec['SliceLocation']
+            [0. 1. 2. 3.]
+            >>> coords_rec['FlipAngle']
+            [ 2. 15. 30.]
+            >>> coords_rec['RepetitionTime']
+            [2.5 5. ]
+
+            Note an error is raised if the coordinates are not grid coordinates:
+
+            >>> coords = {
+            ...     'SliceLocation': np.array([0,1,2,0,1,2]),
+            ...     'FlipAngle': np.array([10,10,10,2,2,2]),
+            ...     'RepetitionTime': np.array([1,5,15,1,5,15]),
+            ... }
+            >>> series = db.empty_series(coords)
+
+            The coordinates form a proper mesh, so this works fine:
+
+            >>> coords = series.meshcoords(tuple(coords))
+
+            But this raises an error:
+
+            >>> series.gridcoords(tuple(coords))
+            ValueError: These are not grid coordinates.
+        """
+        meshcoords = self.coords(dims=dims, mesh=True, slice=slice, coords=coords, exclude=exclude, **filters)
+        return _meshcoords_to_grid(meshcoords)
+    
+
+    def shape(self, dims=('InstanceNumber', ), mesh=True, slice={}, coords={}, exclude=False, **filters)->tuple:
+        """Return the shape of the series along given dimensions.
+
+        Args:
+            dims (tuple, optional): Dimensions along which the shape is to be determined. If dims is not provided, the shape of the flattened series is returned. Defaults to None.
+        
+        Returns:
+            tuple: one value for each element of dims.
+        
+        Raises:
+            ValueError: if the shape in the specified dimensions is ambiguous (because the number of slices is not unique at each location) 
+            ValueError: if the shape in the specified dimensions is not well defined (because there is no slice at one or more locations).
+
+        See also:
+            `coords`
+            `gridcoords`
+            `spacing`
+
+        Example:
+
+            Create a zero-filled series with 3 dimensions.
+
+            >>> coords = {
+            >>>     'SliceLocation': np.arange(4),
+            >>>     'FlipAngle': [2, 15, 30],
+            >>>     'RepetitionTime': [2.5, 5.0] }
+            >>> series = db.zeros((128,128,4,3,2), coords)
+
+            Check the shape of a flattened series:
+            >>> series.shape()
+            (24,)
+
+            Check the shape along all 3 dimensions:
+
+            >>> dims = tuple(coords)
+            >>> series.shape(dims)
+            (4, 3, 2)
+
+            Swap the first two dimensions:
+
+            >>> series.shape((dims[1], dims[0], dims[2]))
+            (3, 4, 2)
+
+            Determine the shape along another DICOM attribute:
+
+            >>> series.shape(('FlipAngle', 'InstanceNumber'))
+            (3, 8)
+
+            The shape of an empty series is zero along any dimension:
+
+            >>> series.new_sibling().shape(dims)
+            (0, 0, 0)
+
+            If one or more of the dimensions is not defined in the header, this raises an error:
+
+            >>> series.shape(('FlipAngle', 'Gobbledigook'))
+            ValueError: series shape is not well defined in dimensions (FlipAngle, Gobbledigook, )
+            --> Some of the dimensions are not defined in the header.
+            --> Hint: use Series.value() to find the undefined values.
+
+            An error is also raised if the values are defined, but are not unique. In this case, all acquisition times are the same so this raises an error:
+
+            >>> series.shape(('FlipAngle', 'AcquisitionTime'))
+            ValueError: series shape is ambiguous in dimensions (FlipAngle, AcquisitionTime, )
+            --> Multiple slices exist at some or all locations.
+            --> Hint: use Series.unique() to list the values at all locations.
+
+        """
+        frames = self.frames(dims=dims, mesh=mesh, slice=slice, coords=coords, exclude=exclude, **filters)
+        return frames.shape
+
+
+    def unique(self, *tags, sortby=(), slice={}, coords={}, exclude=False, return_locs=False, **filters) -> np.ndarray:
+        """Return the unique values of an attribute, sorted by any number of variables.
+
+        Args:
+            tag: either a keyword string or a (group, element) tag of a DICOM data element.
+            sortby (tuple, optional): Dimensions of the resulting array. If *sortby* is not provided, then an array of unique values is returned.
+
+        Returns:
+            np.ndarray: a sorted array of unique values of the attribute, with dimensions as specified by *dims*. If *dims* is provided, the result has the dimensions of *dims* and each element of the array is an array unique values.
+
+        See also:
+            `value`
+            `unique_affines`
+            `coords`
+            `gridcoords`
+
+        Example:
+            Create a zero-filled series with 3 slice dimensions:
+
+            >>> loc = np.arange(4)
+            >>> fa = [2, 15, 30]
+            >>> tr = [2.5, 5.0]
+            >>> coords = {
+            ...     'SliceLocation': np.arange(4),
+            ...     'FlipAngle': [2, 15, 30],
+            ...     'RepetitionTime': [2.5, 5.0] }
+            >>> series = db.zeros((128,128,8,3,2), coords)
+
+            Recover the unique values of any coordinate, such as the flip angle:
+
+            >>> series.value('FlipAngle')
+            [ 2. 15. 30.]
+
+            List the flip angles for each slice location separately:
+
+            >>> fa = series.unique('FlipAngle', sortby=('SliceLocation', ))
+            >>> fa[0]
+            [ 2. 15. 30.]
+            >>> fa[3]
+            [ 2. 15. 30.]
+
+            List the flip angles for each slice location and repetition time:
+
+            >>> fa = series.unique('FlipAngle', sortby=('SliceLocation', 'RepetitionTime'))
+            >>> fa.shape
+            (4, 2)
+            >>> fa[1,1]
+            [ 2. 15. 30.]
+
+            Getting the values for a non-existing attribute produces an empty array:
+
+            >>> gbbl = series.unique('Gobbledigook')
+            >>> gbbl.size
+            0
+            >>> gbbl.shape
+            (0,)
+
+            Getting a non-existing attribute for each slice location produces an array of the expected shape, where each element is an empty array:
+
+            >>> gbbl = series.unique('Gobbledigook', sortby=('SliceLocation',))
+            >>> gbbl.shape
+            (4,)
+            >>> gbbl.size
+            4
+            >>> gbbl[-1].size
+            0
+        """
+        # If no sorting is required, return an array of unique values
+
+        vals = self.values(*(tags+sortby), slice=slice, coords=coords, exclude=exclude, **filters)
+
+        if sortby == ():
+            if len(tags) == 1:
+                uv = vals[vals != np.array(None)]
+                return np.unique(uv)
+            uvals = []
+            for v in vals:
+                uv = v[v != np.array(None)]
+                uvals.append(np.unique(uv))
+            return tuple(uvals)
+        
+        # Create a flat location array
+        loc = []
+        for k in range(len(sortby)):
+            v = vals[len(tags)+k]
+            v = v[v != np.array(None)]
+            loc.append(np.unique(v))
+        loc = np.meshgrid(*tuple(loc), indexing='ij')
+        shape = loc[0].shape
+        loc = [l.ravel() for l in loc]
+
+        # Build an array of unique values at each location and each tag
+        uvals = np.empty((len(tags), loc[0].size), dtype=np.ndarray)
+        for i in range(loc[0].size):
+            k = 0
+            ind = vals[len(tags)+k] == loc[k][i]
+            for k in range(1, len(sortby)):
+                ind = ind & (vals[len(tags)+k] == loc[k][i])
+            for t in range(len(tags)):
+                vti = vals[t][ind]
+                vti = vti[vti != np.array(None)]
+                uvals[t,i] = np.unique(vti)
+
+        # Refactor to return values
+        if len(tags) == 1:
+            uvals = uvals[0,:].reshape(shape)
+        else:
+            uvals = [uvals[t,:].reshape(shape) for t in range(len(tags))]
+            uvals = tuple(uvals)
+        if return_locs:
+            loc = [l.reshape(shape) for l in loc]
+            loc = tuple(loc)  
+            return uvals, loc
+        else:
+            return uvals
+    
+
+    def pixel_values(self, dims=('InstanceNumber', ), return_coords=False, slice={}, coords={}, **filters) -> np.ndarray:
+        """Return a numpy.ndarray with pixel data.
+
+        Args:
+            dims (tuple, optional): Dimensions of the result, as a tuple of valid DICOM tags of any length. If *dims* is not provided, pixel values are ordered by instance number. 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:
+            np.ndarray: pixel data. The number of dimensions will be 2 plus the number of elements in *dim*. The first two indices will enumerate (column, row) indices in the slice, the other dimensions are as specified by the *dims* argument. 
+            
+            The function returns an empty array when no data are found at the specified locations.
+
+        Raises:
+            ValueError: Indices must be in the dimensions provided. If *ind* is set but keys are not part of *dims*.
+            ValueError: if the images are different shapes.
+
+        See also:
+            `set_pixel_values`
+
+        Example:
+            Create a zero-filled array 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,64,4,3,2), coords)
+
+            Retrieve the pixel array of the series:
+
+            >>> dims = tuple(coords)
+            >>> array = zeros.pixel_values(dims)
+            >>> array.shape
+            (128, 64, 4, 3, 2)
+
+            To retrieve an array containing only the data with flip angle 15:
+
+            >>> array = zeros.pixel_values(dims, FlipAngle=15)
+            >>> array.shape
+            (128, 64, 4, 1, 2)
+
+            If no data fit the requirement, and empty array is returned:
+
+            >>> array = zeros.pixel_values(dims, FlipAngle=15)
+            >>> array.size
+            0
+
+            Multiple possible values can be specified as an array:
+
+            >>> array = zeros.pixel_values(dims, FlipAngle=np.array([15,30]))
+            >>> array.shape
+            (128, 64, 4, 2, 2)
+
+            And multiple filters can be specified by adding keyword arguments. The following returns an array of pixel values with flip angle of 15 or 30, and slice location of 10 or 20:
+
+            >>> array = zeros.pixel_values(dims, FlipAngle=np.array([15,30]), SliceLocation=np.array([10,20]))
+            >>> array.shape
+            (128, 64, 2, 2, 2)
+
+            The filters can be any DICOM attribute:
+
+            >>> array = zeros.pixel_values(dims, AcquisitionTime=0)
+            >>> array.size
+            0
+
+            The filters can also be specified as a dictionary of values:
+
+            >>> array = zeros.pixel_values(dims, select={'FlipAngle': 15})
+            >>> array.shape
+            (128, 64, 4, 1, 2)
+
+            Since keywords need to be strings in python, this is the only way to specify filters with (group, element) tags:
+
+            >>> array = zeros.pixel_values(dims, select={(0x0018, 0x1314): 15})
+            >>> array.shape
+            (128, 64, 4, 1, 2)
+
+            Using the *inds* argument, the pixel array can be indexed to avoid reading a large array if only a subarray is required:
+
+            >>> array = zeros.pixel_values(dims, inds={'FlipAngle': 1})
+            >>> array.shape
+            (128, 64, 4, 1, 2)
+
+            Note unlike filters defind by *value*, the indices must be provided in the dimensions of the array. If not, a `ValueError` is raised:
+
+            >>> zeros.pixel_values(dims, inds={'AcquisitionTime':0})
+            ValueError: Indices must be in the dimensions provided.
+        """
+        if np.isscalar(dims):
+            dims = (dims,)
+        frames = self.frames(dims, return_coords=return_coords, slice=slice, coords=coords, **filters)
+        if return_coords:
+            frames, fcoords = frames
+        if frames.size == 0:
+            shape = (0,0) + frames.shape
+            values = np.array([]).reshape(shape)
+            if return_coords:
+                return values, fcoords
+            else:
+                return values
+        
+        # Read values
+        fshape = frames.shape
+        frames = frames.ravel()
+        values = []
+        for f, frame in enumerate(frames):
+            self.progress(f+1, len(frames), 'Reading pixel values..')
+            values.append(frame.get_pixel_array())
+
+        # Check that all matrix sizes are the same
+        vshape = np.array([v.shape for v in values])
+        vshape = np.unique(vshape.T, axis=1)
+        if vshape.shape[1] > 1:
+            msg = 'Cannot extract an array of pixel values - not all frames have the same matrix size.'
+            raise ValueError(msg)
+        
+        # Create the array
+        values = np.stack(values, axis=-1)
+        values = values.reshape(values.shape[:2] + fshape)
+        if return_coords:
+            return values, fcoords
+        else:
+            return values
+    
+
+    def set_pixel_values(self, values:np.ndarray, dims:tuple=None, slice={}, coords={}, **filters):
+        """Set a numpy.ndarray with pixel data.
+
+        Args:
+            dims (tuple, optional): Dimensions of the pixel values, as a tuple of valid DICOM tags of any length. If *dims* is not provided, pixel values are ordered by instance number. Defaults to None.
+            inds (dict, optional): Dictionary with indices to set a slice of the entire array. Defaults to None.
+            select (dict, optional): A dictionary of values for DICOM attributes to set specific frames. 
+            filters (dict, optional): keyword arguments to set specific frames.
+
+        Raises:
+            ValueError: if the values are the incorrect shape for the dimensions.
+
+        See also:
+            `pixel_values`
+
+        Example:
+            Create a zero-filled array 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,64,4,3,2), coords)
+        """
+        if dims is None:
+            if slice != {}:
+                dims = tuple(slice)
+            elif coords != {}:
+                dims = tuple(coords)
+            else:
+                dims = ('InstanceNumber', )
+        elif np.isscalar(dims):
+            dims = (dims,)
+        # Get frames to set:
+        frames = self.frames(dims, slice=slice, coords=coords, **filters)
+        if frames.size == 0:
+            if slice != {}:
+                self.expand(gridcoords=slice)
+                frames = self.frames(dims)
+            else:
+                msg = 'Cannot set values to an empty series. Use Series.expand() to create empty frames first, or set the loc keyword to define coordinates for the new frames.'
+                raise ValueError(msg)
+        
+        if np.prod(values.shape[2:]) != frames.size:
+            msg = 'The size of the pixel value array is different from the size of the series.'
+            msg += '\nThe pixel array has shape ' + str(values.shape[2:]) + ', '
+            msg += 'but the series has shape ' + str(frames.shape) + '.'
+            raise ValueError(msg)
+        frames = frames.ravel()
+        values = values.reshape(values.shape[:2] + (-1,))
+        for f, frame in enumerate(frames):
+            self.progress(f+1, frames.size, 'Writing pixel values..')
+            frame.set_pixel_array(values[:,:,f])
+
+    def volume(self):
+        return self.volumes(stack=True)
+
+    def volumes(self,  dims='SliceLocation', mesh=True, stack=False):
+        """Return vreg volumes for each frame, or stacked"""
+
+        frames = self.frames(dims, mesh=mesh)
+        vols = [f.volume() for f in frames.reshape(-1)]
+        vols = np.asarray(vols).reshape(frames.shape)
+        if not stack:
+            return vols
+        shape = vols.shape
+        vols = vols.reshape((shape[0],-1))
+        vols_stack = []
+        for k in range(vols.shape[1]):
+            vstack = vreg.concatenate(vols[:,k], prec=3)
+            vols_stack.append(vstack)
+        if len(shape) == 1:
+            return vols_stack[0]
+        else:
+            return np.asarray(vols_stack).reshape(shape[1:])
+
+
+    def set_volumes(self, volumes, dims='SliceLocation', mesh=True):
+
+        # Convert affines to arrays if needed
+        if isinstance(volumes, list):
+            volumes = np.array(volumes)
+        
+        # Get frames
+        frames = self.frames(dims, mesh=mesh)
+
+        # One affine for each frame
+        if volumes.shape == frames.shape:
+            volumes = volumes.reshape(-1)
+            for i, f in enumerate(frames.reshape(-1)):
+                self.progress(i, frames.size, 'Setting affines.. ')
+                f.set_volume(volumes[i])
+
+        # Different number of affines and frames
+        else:
+            # A volumetric series
+            if frames.ndim==1:
+                volumes = volumes.reshape(-1)
+                if volumes.size > 1:
+                    raise ValueError(
+                        "Cannot set volumes. A volume can only "
+                        "have one element.")
+                volumes = volumes[0].split(frames.size)
+                for z, f in enumerate(frames):
+                    self.progress(z+1, frames.size, 'Setting volumes.. ')
+                    f.set_volume(volumes[z])
+
+            # Multislice affine replicated across all times
+            elif volumes.size == frames.shape[0]:
+                frames = frames.reshape((frames.shape[0],-1))
+                volumes = volumes.reshape(-1)
+                nz, nt = frames.shape
+                cnt=0
+                for z in range(nz):
+                    for t in range(nt):
+                        cnt+=1
+                        self.progress(cnt, nt*nz, 'Setting volumes.. ')
+                        frames[z,t].set_volume(volumes[z])
+
+            # One volume replicated across all times
+            elif volumes.size==1:
+                frames = frames.reshape((frames.shape[0],-1))
+                nz, nt = frames.shape
+                volumes = volumes[0].split(nz)
+                cnt=0
+                for z in range(nz):
+                    for t in range(nt):
+                        cnt+=1
+                        self.progress(cnt, nt*nz, 'Setting volumes.. ')
+                        frames[z,t].set_volume(volumes[z])
+
+            # Volume for each time point
+            elif volumes.shape == frames.shape[1:]:
+                frames = frames.reshape((frames.shape[0],-1))
+                volumes = volumes.reshape(-1)
+                nz, nt = frames.shape
+                cnt=0
+                for t in range(nt):
+                    volumes_t = volumes[t].split(nz)
+                    for z, f in enumerate(frames[:,t]):
+                        cnt+=1
+                        self.progress(cnt, nt*nz, 'Setting volumes.. ')
+                        f.set_volume(volumes_t[z])
+
+            # Incompatible shapes
+            else:
+                raise ValueError(
+                    "Cannot set volumes. The volume array has an incompatible "
+                    "shape or size.")
+        return self
+    
+
+    def affines(self,  dims='SliceLocation', mesh=True, stack=False):
+        """Return affines for each frame"""
+
+        frames = self.frames(dims, mesh=mesh)
+        affines = [f.affine() for f in frames.reshape(-1)]
+        affines = np.asarray(affines).reshape(frames.shape)
+        if not stack:
+            return affines
+        shape = affines.shape
+        affines = affines.reshape((shape[0],-1))
+        nt = affines.shape[1]
+        affines_stack = np.empty(nt, dtype=np.ndarray)
+        for t in range(nt):
+            affines_stack[t] = image_utils.stack_affines(affines[:,t])
+        if len(shape)==1:
+            return affines_stack[0]
+        else:
+            return affines_stack.reshape(shape[1:])
+
+    def set_affines(self, affines, dims='SliceLocation', mesh=True):
+
+        # Convert affines to arrays if needed
+        if isinstance(affines, np.ndarray):
+            aff = np.empty(1, dtype=np.ndarray)
+            aff[0] = affines
+            affines = aff
+        elif isinstance(affines, list):
+            aff = np.empty(len(affines), dtype=np.ndarray)
+            for i, a in enumerate(affines):
+                aff[i] = a
+            affines = aff
+        
+        # Get frames
+        frames = self.frames(dims, mesh=mesh)
+
+        # One affine for each frame
+        if affines.shape == frames.shape:
+            affines = affines.reshape(-1)
+            for i, f in enumerate(frames.reshape(-1)):
+                self.progress(i, frames.size, 'Setting affines.. ')
+                f.set_affine(affines[i])
+
+        # Different number of affines and frames
+        else:
+            # A volumetric series
+            if frames.ndim==1:
+                affines = affines.reshape(-1)
+                if affines.size > 1:
+                    raise ValueError(
+                        "Cannot set affines. A volumetric affine can only "
+                        "have one element.")
+                affines = image_utils.unstack_affine(affines[0], frames.shape[0])
+                for z, f in enumerate(frames):
+                    self.progress(z+1, frames.size, 'Setting affines.. ')
+                    f.set_affine(affines[z])
+
+            # Multislice affine replicated across all times
+            elif affines.size == frames.shape[0]:
+                frames = frames.reshape((frames.shape[0],-1))
+                affines = affines.reshape(-1)
+                nz, nt = frames.shape
+                cnt=0
+                for z in range(nz):
+                    for t in range(nt):
+                        cnt+=1
+                        self.progress(cnt, nt*nz, 'Setting affines.. ')
+                        frames[z,t].set_affine(affines[z])
+
+            # One volume affine replicated across all times
+            elif affines.size==1:
+                frames = frames.reshape((frames.shape[0],-1))
+                nz, nt = frames.shape
+                affines = image_utils.unstack_affine(affines[0], nz)
+                cnt=0
+                for z in range(nz):
+                    for t in range(nt):
+                        cnt+=1
+                        self.progress(cnt, nt*nz, 'Setting affines.. ')
+                        frames[z,t].set_affine(affines[z])
+
+            # Volume affine for each time point
+            elif affines.shape == frames.shape[1:]:
+                frames = frames.reshape((frames.shape[0],-1))
+                affines = affines.reshape(-1)
+                nz, nt = frames.shape
+                cnt=0
+                for t in range(nt):
+                    affines_t = image_utils.unstack_affine(affines[t], nz)
+                    for z, f in enumerate(frames[:,t]):
+                        cnt+=1
+                        self.progress(cnt, nt*nz, 'Setting affines.. ')
+                        f.set_affine(affines_t[z])
+
+            # Incompatible shapes
+            else:
+                raise ValueError(
+                    "Cannot set affines. The affine array has an incompatible "
+                    "shape or size.")
+        return self
+
+
+    # TODO: make obsolete (ignores dimensions or multi-volume series)
+    def affine(self, slice={}, coords={}, **filters) -> np.ndarray:
+        """Return the affine of the Series.
+
+        Raises:
+            ValueError: if the DICOM file is corrupted
+            ValueError: if the affine is not unique.
+
+        Returns:
+            np.ndarray: affine matrix as a 4x4 numpy array.
+
+        See also:
+            `set_affine`
+            `unique_affines`
+
+        Example:
+            Check that the default affine is the identity:
+
+            >>> zeros = db.zeros((128,128,10))
+            >>> zeros.affine()
+            [[1., 0., 0., 0.],
+             [0., 1., 0., 0.],
+             [0., 0., 1., 0.],
+             [0., 0., 0., 1.]]
+        """
+
+        # Read values
+        tags = ('ImageOrientationPatient', 'ImagePositionPatient', 'PixelSpacing', 'SliceThickness', )
+        orientation, pos, spacing, thick = self.values(*tags, slice=slice, coords=coords, **filters)
+
+        # Single slice
+        if len(pos) == 1:
+            return image_utils.affine_matrix(orientation[0], pos[0], spacing[0], thick[0])
+        
+        # Multiple orientations - raise error
+        orientation = np.unique(orientation)
+        if len(orientation) > 1:
+            msg = 'The series has multiple affines. '
+            msg += '\nUse Series.unique_affines() to return an array of unique affines.'
+            raise ValueError(msg)
+        orientation = orientation[0]
+
+        # Multiple pixel spacings - raise error
+        spacing = np.unique(spacing)
+        if len(spacing) > 1:
+            msg = 'The series has multiple pixel spacings. '
+            msg += '\nAffine array of the series is not well defined.'
+            raise ValueError(msg)     
+        spacing = spacing[0]
+    
+        # All the same slice locations
+        upos = np.unique(pos)
+        if len(upos) == 1:
+            return image_utils.affine_matrix(orientation, pos[0], spacing, thick[0])
+        
+        # Different slice locations but not all different - raise error
+        if len(upos) != len(pos): 
+            msg = 'Some frames have the same ImagePositionPatient. '
+            msg += '\nAffine matrix of the series is not well defined.'
+            raise ValueError(msg)  
+        
+        return image_utils.affine_matrix_multislice(orientation, pos, spacing)   
+
+    # TODO: amke obsolete - does not handle dimensions or multislice vs volume
+    def set_affine(self, affine:np.ndarray, dims=('InstanceNumber',), slice={}, coords={}, multislice=False, **filters):
+        """Set the affine matrix of a series.
+
+        The affine is defined as a 4x4 numpy array with bottom row [0,0,0,1]. The final column represents the position of the top right hand corner of the first slice. The first three columns represent rotation and scaling with respect to the axes of the reference frame.
+
+        Args:
+            affine (numpy.ndarray): 4x4 numpy array 
+
+        Raises:
+            ValueError: if the series is empty. The information of the affine matrix is stored in the header and can not be stored in an empty series.
+
+        See also:
+            `affine`
+            `unique_affines`
+
+        Example:
+            Create a series with unit affine array:
+
+            >>> zeros = db.zeros((128,128,10))
+            >>> zeros.affine()
+            [[1., 0., 0., 0.],
+             [0., 1., 0., 0.],
+             [0., 0., 1., 0.],
+             [0., 0., 0., 1.]]
+
+            Rotate the volume over 90 degrees in the xy-plane:
+
+            >>> affine = np.array([
+            ...     [1., 0., 0., 0.],
+            ...     [0., 1., 0., 0.],
+            ...     [0., 0., 1., 0.],
+            ...     [0., 0., 0., 1.],
+            ... ]) 
+            >>> zeros.set_affine(affine)
+
+            Apart from the rotation, also change the resolution to (3mm, 3mm, 1.5mm):
+
+            >>> affine = np.array([
+            ...     [0., -3., 0., 0.],
+            ...     [3., 0., 0., 0.],
+            ...     [0., 0., 1.5, 0.],
+            ...     [0., 0., 0., 1.],
+            ... ])  
+            >>> zeros.set_affine(affine)
+
+            Now rotate, change resolution, and shift the top right hand corner of the lowest slice to position (-30mm, 20mm, 120mm):
+
+            >>> affine = np.array([
+            ...     [0., -3., 0., -30.],
+            ...     [3., 0., 0., 20.],
+            ...     [0., 0., 1.5, 120.],
+            ...     [0., 0., 0., 1.],
+            ... ])  
+            >>> zeros.set_affine(affine)
+
+            Note: changing the affine will affect multiple DICOM tags, such as slice location and image positions:
+
+            >>> zeros.SliceLocation
+            [120.0, 121.5, 123.0, 124.5, 126.0, 127.5, 129.0, 130.5, 132.0, 133.5]
+
+            In this case, since the slices are stacked in parallel to the z-axis, the slice location starts at the lower z-coordinate of 120mm and then increments slice-by-slice with the slice thickness of 1.5mm.
+        
+        """
+
+        frames = self.frames(dims=dims, slice=slice, coords=coords, **filters)
+        if frames.size == 0:
+            msg = 'Cannot set affine matrix in an empty series. Use Series.expand() to create empty frames first.'
+            raise ValueError(msg)
+    
+        # For each slice location, the slice position needs to be updated too
+        # Need the coordinates of the vector parallel to the z-axis of the volume.
+        a = image_utils.dismantle_affine_matrix(affine)
+        ez = a['SpacingBetweenSlices']*np.array(a['slice_cosine'])
+
+        # if multislice:
+        #     slice_thickness = self.unique('SliceThickness')[0]
+
+        # Set the affine slice-by-slice
+        affine_z = affine.copy()
+        for z, frame in enumerate(frames):
+            self.progress(z+1, frames.size, 'Writing affine..')
+            affine_z[:3, 3] = affine[:3, 3] + z*ez
+            if multislice:
+                thickness = frame.SliceThickness
+            frame.affine_matrix = affine_z
+            if multislice:
+                frame.SliceThickness = thickness
+
+        # if multislice:
+        #     self.set_values(slice_thickness,'SliceThickness')
+
+
+    # consider renaming copy() - but breaks backward compatibility - this is not a slice really
+    def extract(self, slice={}, coords={}, **filters) -> Series:
+        """Get a slice of the series by dimension values
+
+        Args:
+            coordinates (dict, optional): dictionary of tag:value pairs where the value is either a single value or an array of values.
+            coords (dict): Provide coordinates for the slice, either as dimension=value pairs, or as a dictionary where the keys list the dimensions, and the values are provided as scalars, 1D or meshgrid arrays of coordinates. 
+
+        See also:
+            `islice`
+            `split_by`
+
+        Example:
+            Create a zero-filled array, describing 8 MRI images each measured at 3 flip angles and 2 repetition times:
+
+            >>> coords = {
+            ...    'SliceLocation': np.arange(8),
+            ...    'FlipAngle': [2, 15, 30],
+            ...    'RepetitionTime': [2.5, 5.0],
+            ... }
+            >>> series = db.zeros((128,128,8,3,2), coords)
+
+            Slice the series at flip angle 15:
+
+            >>> fa15 = series.slice(FlipAngle=15)
+
+            Retrieve the array and check the dimensions:
+
+            >>> array = fa15.pixel_values(dims=tuple(coords))
+            >>> print(array.shape)
+            (128, 128, 8, 1, 2)
+
+            Multiple possible values can be specified as a list or np.ndarray:
+
+            >>> fa15 = series.slice(SliceLocation=[0,5], FlipAngle=15)
+            >>> array = fa15.pixel_values(dims=tuple(coords))
+            >>> print(array.shape)
+            (128, 128, 2, 1, 2)
+
+            Values can also be provided as a dictionary, which is useful for instance for private tags that do not have a keyword string. So the following are equivalent:
+
+            >>> fa15 = series.slice(SliceLocation=[0,5], FlipAngle=15)
+            >>> fa15 = series.slice({SliceLocation:[0,5], FlipAngle:15})
+            >>> fa15 = series.slice({(0x0020, 0x1041):[0,5], (0x0018, 0x1314):15})
+        """
+
+        frames = self.frames(slice=slice, coords=coords, **filters)
+        result = self.new_sibling()
+        # result.adopt(frames) # faster but no progress bar
+        for f, frame in enumerate(frames):
+            self.progress(f+1, len(frames), 'Creating slice..')
+            frame.copy_to(result)
+        return result
+        
+    
+    def split_by(self, tag: str | tuple) -> list:
+        """Split the series into multiple subseries based on keyword value.
+
+        Args:
+            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:
+            list: A list of ``Series`` instances, where each element has the same value of the given keyword.
+
+        See Also:
+            `slice`
+            `islice`
+
+        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
+        """
+        
+        vals = self.unique(tag)
+        if len(vals)==1:
+            msg = 'Cannot split by ' + str(tag) + '\n' 
+            msg += 'All frames have the same value.'
+            raise ValueError(msg)
+        
+        desc = self.instance().SeriesDescription + '[' + str(tag) + ' = '
+        split_series = []
+        for v in vals:
+            new = self.extract(slice={tag: v})
+            new.SeriesDescription = desc + str(v) + ']'
+            split_series.append(new)
+        return split_series
+        
+
+    def spacing(self, **kwargs)->tuple:
+        """3D pixel spacing in mm
+
+        Returns:
+            tuple: (x-spacing, y-spacing, z-spacing)
+
+        See also:
+            `shape`
+
+        Examples:
+            Check the spacing of a digital reference object:
+
+            >>> series = db.dro.T1_mapping_vFATR()
+            >>> series.spacing()
+            (15, 15, 20)
+        """
+        affine = self.affine(**kwargs)
+        column_spacing = np.linalg.norm(affine[:3, 0])
+        row_spacing = np.linalg.norm(affine[:3, 1])
+        slice_spacing = np.linalg.norm(affine[:3, 2])
+        return column_spacing, row_spacing, slice_spacing
+
+
+   
+
+    def unique_affines(self)->np.ndarray:
+        """Return the array of unique affine matrices.
+
+        Raises:
+            ValueError: if the DICOM file is corrupted.
+
+        Returns:
+            np.ndarray: array of 4x4 ndarrays with the unique affine matrices of the series.
+
+        See also:
+            `set_affine`
+            `affine`
+
+        Example:
+            Check that the default affine is the identity:
+
+            >>> zeros = db.zeros((128,128,10))
+            >>> zeros.affine()
+            [array([
+                [1., 0., 0., 0.],
+                [0., 1., 0., 0.],
+                [0., 0., 1., 0.],
+                [0., 0., 0., 1.]], dtype=float32)]
         """
-        images = instance_array(self, sortby='SliceLocation')
-        if images.size == 0:
-            msg = 'Cannot set affine matrix in an empty series \n'
-            msg += 'Set some data with series.ndarray() and then try again.'
+        image_orientation = self.ImageOrientationPatient
+        if image_orientation is None:
+            msg = 'ImageOrientationPatient not defined in the DICOM header \n'
+            msg += 'This is a required DICOM field \n'
+            msg += 'The data may be corrupted - please check'
             raise ValueError(msg)
-        images = images[...,0]
-        affine_z = affine.copy()
-
-        # For each slice location, the slice position needs to be updated too
-        # Need the coordinates of the vector parallel to the z-axis of the volume.
-        a = image_utils.dismantle_affine_matrix(affine)
-        ez = a['SpacingBetweenSlices']*np.array(a['slice_cosine'])
+        # Multiple slice groups in series - return list of affine matrices
+        if self.is_multislice():
+            affine_matrices = []
+            for dir in image_orientation:
+                slice_group = self.instances(ImageOrientationPatient=dir)
+                affine = _slice_group_affine_matrix(slice_group, dir)
+                affine_matrices.append(affine)
+            return np.unique(affine_matrices)
+        # Single slice group in series - return a list with a single affine matrix
+        else:
+            slice_group = self.instances()
+            affine = _slice_group_affine_matrix(slice_group, image_orientation)
+            return np.array([affine])
 
-        # Set the affine slice-by-slice
-        nz = images.shape[0]
-        for z in range(nz):
-            self.progress(z+1, nz, 'Writing affine..')
-            affine_z[:3, 3] = affine[:3, 3] + z*ez
-            images[z].read()
-            images[z].affine_matrix = affine_z
-            images[z].clear()
+    def is_multislice(self)->bool:
+        """Check if the series is multislice
 
+        Returns:
+            bool: True if the series is multislice.
+        """
+        return is_multislice(self)
         
 
-    def ndarray(self, dims=('InstanceNumber',), coords:dict=None, slice:dict=None) -> np.ndarray:
-        """Return a numpy.ndarray with pixel data.
+    def islice(self, indices={}, **inds) -> Series:
+        """Get a slice of the series by dimension indics
 
         Args:
-            dims (tuple, optional): Dimensions of the result, as a tuple of valid DICOM tags of any length. Defaults to ('InstanceNumber',).
-            coords (dict, optional): Dictionary with coordinates to retrieve a slice of the entire array. If coords is provided, the dims argument is ignored.
-            slice (dict, optional): Dictionary with coordinates to retrieve a slice of the entire array. If slice is provided, then the dims argument is ignored. The difference with coords is that the dictionary values in slice specify the indices rather than the values of the coordinates.
+            indices (dict, optional): Dictionary with tag:value pairs, where the values are either a single index or an array of indices.
+            inds (dict, optional): Provide indices for the slice, either as keyword=index pairs or as a dictionary. The indices must be provided either as a scalar, a list or a numpy array.
 
-        Returns:
-            np.ndarray: pixel data. The number of dimensions will be 2 plus the number of elements in dim, or the number of entries in slice or islice. The first two indices will enumerate (x,y) coordinates in the slice, the other dimensions are as specified by the dims, slice or islice argument. 
-            
-            The function returns an empty array when no data are found at the specified slices.
+        Raises:
+            IndexError: when the indices in inds are out of range of the existing coordinates. 
 
         See also:
-            :func:`~set_ndarray`
+            `slice`
+            `split_by`
 
         Example:
-            Create a zero-filled array, describing 8 MRI slices (10mm apart) each measured at 3 flip angles and 2 repetition times:
+            Create a zero-filled array, describing 8 MRI images each measured at 3 flip angles and 2 repetition times:
 
             >>> coords = {
-            ...    'SliceLocation': 10*np.arange(8),
+            ...    'SliceLocation': np.arange(8),
             ...    'FlipAngle': [2, 15, 30],
             ...    'RepetitionTime': [2.5, 5.0],
             ... }
-            >>> zeros = db.zeros((128,128,8,3,2), coords)
+            >>> series = db.zeros((128,128,8,3,2), coords)
 
-            To retrieve the array, the dimensions need to be provided:
+            Slice the series at flip angle 15 (i.e. index 1):
 
-            >>> dims = ('SliceLocation', 'FlipAngle', 'RepetitionTime')
-            >>> array = zeros.ndarray(dims)
-            >>> print(array.shape)
-            (128, 128, 8, 3, 2)
+            >>> fa15 = series.islice(FlipAngle=1)
 
-            Note the dimensions are the keys of the coordinate dictionary, so this could also have been called as:
+            Retrieve the array and check the dimensions:
 
-            >>> array = zeros.ndarray(dims=tuple(coords)) 
+            >>> array = fa15.pixel_values(dims=tuple(coords))
             >>> print(array.shape)
-            (128, 128, 8, 3, 2)
-
-            To retrieve a slice of the volume, specify the coordinates of the slice as a dictionary. For instance, to retrieve the pixel data measured with a flip angle of 15:
-
-            >>> coords = {
-            ...    'SliceLocation': 10*np.arange(8),
-            ...    'FlipAngle': [15],
-            ...    'RepetitionTime': [2.5, 5.0],
-            ... }
+            (128, 128, 8, 1, 2)
 
-            Now pass this as coordinates in the call to ndarray:
+            Multiple possible indices can be specified as a list or np.ndarray:
 
-            >>> array = zeros.ndarray(coords=coords) 
+            >>> fa15 = series.slice(SliceLocation=[0,5], FlipAngle=1)
+            >>> array = fa15.pixel_values(dims=tuple(coords))
             >>> print(array.shape)
-            (128, 128, 8, 1, 2)
+            (128, 128, 2, 1, 2)
 
-            A slice can also be specified with indices rather than absolute values of the coordinates:
-
-            >>> slice = {
-            ...    'SliceLocation': np.arange(8),
-            ...    'FlipAngle': [1],
-            ...    'RepetitionTime': np.arange(2),
-            ... }
+            Values can also be provided as a dictionary, which is useful for instance for private tags that do not have a keyword string. So the following are equivalent:
 
-            Now pass this as index coordinates in the call to ndarray:
+            >>> fa15 = series.slice(SliceLocation=[0,5], FlipAngle=1)
+            >>> fa15 = series.slice({SliceLocation:[0,5], FlipAngle:1})
+            >>> fa15 = series.slice({(0x0020, 0x1041):[0,5], (0x0018, 0x1314):1})
 
-            >>> array = zeros.ndarray(slice=slice) 
-            >>> print(array.shape)
-            (128, 128, 8, 1, 2)
         """
-        if coords is not None:
-            dims = tuple(coords)
-        if slice is not None:
-            dims = tuple(slice)
-        source = instance_array(self, list(dims))
-        if source.size == 0:
-            return np.array([])
-        if slice is not None:
-            for d, dim in enumerate(slice):
-                ind = slice[dim]
-                source = source.take(ind, axis=d)
-        if coords is not None:
-            for d, dim in enumerate(coords):
-                ind = []
-                for i in range(source.shape[d]):
-                    si = source.take(i,axis=d).ravel()
-                    if si[0][dim] in coords[dim]:
-                        ind.append(i)
+        inds = {**indices, **inds}
+
+        # Check whether the arguments are valid, and initialize dims.
+        if inds == {}:
+            return self.new_sibling()
+        dims = list(inds.keys())
+        source = instance_array(self, sortby=dims)
+        
+        # Retrieve the instances of the slice.
+        for d, dim in enumerate(inds):
+            ind = inds[dim]
+            try:
                 source = source.take(ind, axis=d)
-        if source.size == 0:
-            return np.array([])
-        array = []
-        instances = source.ravel()
-        im = None
-        for i, im in enumerate(instances):
-            if im is None:
-                array.append(np.zeros((1,1)))
-            else:
-                im.progress(i+1, len(instances), 'Reading pixel data..')
-                array.append(im.get_pixel_array())
-        if im is not None:
-            im.status.hide()
-        array = _stack(array)
-        if array is None:
-            return np.array([])
-        array = array.reshape(source.shape + array.shape[1:])
-        # Move pixel coordinates to front
-        array = np.moveaxis(array, -1, 0)
-        array = np.moveaxis(array, -1, 0)
-        return array[...,0]
-    
+                # Insert dimensions of 1 back in
+                if isinstance(ind, Number):
+                    source = np.expand_dims(source, axis=d)
+            except IndexError as e:
+                msg = str(e) + '\n'
+                msg += 'The indices for ' + str(dim) + ' in the inds argument are out of bounds'
+                raise IndexError(msg)
+            
+        result = self.new_sibling()
+        source = source.ravel()
+        for i in range(source.size):
+            source[i].copy_to(result)
+        return result
+
+
+    #
+    # Following APIs are obsolete and will be removed in future versions
+    #
 
-    def set_ndarray(self, array:np.ndarray, coords:dict=None, slice:dict=None):
+
+    def _old_set_pixel_values(self, array:np.ndarray, coords:dict=None, inds:dict=None):
         """Assign new pixel data with a new numpy.ndarray. 
 
         Args:
             array (np.ndarray): array with new pixel data.
             coords (dict, optional): Provide coordinates for the array, using a dictionary where the keys list the dimensions, and the values are provided as 1D or meshgrid arrays of coordinates. If data already exist at the specified coordinates, these will be overwritten. If not, the new data will be added to the series.
-            slice (dict, optional): Provide a slice of existing data that will be overwritten with the new array. The format is the same as the dictionary of coordinates, except that the slice is identified by indices rather than values. 
+            inds (dict, optional): Provide a slice of existing data that will be overwritten with the new array. The format is the same as the dictionary of coordinates, except that the slice is identified by indices rather than values. 
 
         Raises:
-            ValueError: if neither coords or slice or provided, if both are provided, or if the dimensions in coords or slice does not match up with the dimensions of the array.
-            IndexError: when attempting to set a slice in an empty array, or when the indices in slice are out of range of the existing coordinates. 
+            ValueError: if neither coords or inds or provided, if both are provided, or if the dimensions in coords or inds does not match up with the dimensions of the array.
+            IndexError: when attempting to set a slice in an empty array, or when the indices in inds are out of range of the existing coordinates. 
 
         See also:
-            :func:`~ndarray`
+            `pixel_values`
 
         Example:
-            Create a zero-filled array, describing 8 MRI slices each measured at 3 flip angles and 2 repetition times:
+            Create a zero-filled array, describing 8 MRI images each measured at 3 flip angles and 2 repetition times:
 
             >>> coords = {
             ...    'SliceLocation': np.arange(8),
@@ -615,7 +1868,7 @@ class Series(Record):
 
             Retrieve the array and check that it is populated with zeros:
 
-            >>> array = series.ndarray(dims=tuple(coords)) 
+            >>> array = series.pixel_values(dims=tuple(coords)) 
             >>> print(np.mean(array))
             0.0
 
@@ -626,11 +1879,11 @@ class Series(Record):
             ...     'SliceLocation': np.arange(8),
             ... }
             >>> ones = np.ones(new_shape)
-            >>> series.set_ndarray(ones, coords=new_coords)
+            >>> series.set_pixel_values(ones, coords=new_coords)
 
             Retrieve the new array and check shape:
             
-            >>> array = series.ndarray(dims=tuple(new_coords))
+            >>> array = series.pixel_values(dims=tuple(new_coords))
             >>> print(array.shape)
             (128,128,8)
 
@@ -639,11 +1892,6 @@ class Series(Record):
             >>> print(np.mean(array))
             1.0
         """
-        
-        # TODO: set_pixel_array has **kwargs to allow setting other properties on the fly to save extra reading and writing. This makes sense but should be handled by a more general function, such as:
-        # #  
-        # series.set(ndarray:np.ndarray, coords:dict, affine:np.ndarray, **kwargs)
-        # #
 
         # Check whether the arguments are valid, and initialize dims.
         cnt = 0
@@ -657,17 +1905,17 @@ class Series(Record):
                 if len(coords[dim]) != array.shape[d+2]:
                     msg = str(dim) + ' in the coords must have the same number of elements as the corresponding dimension in the array'
                     raise ValueError(msg)
-        if slice is not None:
+        if inds is not None:
             cnt+=1
-            dims = tuple(slice)
+            dims = tuple(inds)
             if len(dims) != array.ndim-2:
                 msg = 'One coordinate must be specified for each dimensions in the array.'
                 raise ValueError(msg)
         if cnt == 0:
-            msg = 'At least one of the optional arguments coords or slice must be provided'
+            msg = 'At least one of the optional arguments coords or inds must be provided'
             raise ValueError(msg)
         if cnt == 2:
-            msg = 'Only one of the optional arguments coords or slice must be provided'
+            msg = 'Only one of the optional arguments coords or inds must be provided'
             raise ValueError(msg)
 
         source = instance_array(self, sortby=list(dims))
@@ -682,16 +1930,21 @@ class Series(Record):
                         if si[0][dim] in coords[dim]:
                             ind.append(i)
                     source = source.take(ind, axis=d)
-        elif slice is not None:
+                    # Insert dimensions of 1 back in
+                    if len(ind)==1:
+                        source = np.expand_dims(source, axis=d)
+        elif inds is not None:
             # Retrieve the instances of the slice, as well as their coordinates.
             coords = {}
-            for d, dim in enumerate(slice):
-                ind = slice[dim]
+            for d, dim in enumerate(inds):
+                ind = inds[dim]
+                if isinstance(ind, np.ndarray):
+                    ind = list(ind)
                 try:
                     source = source.take(ind, axis=d)
                 except IndexError as e:
                     msg = str(e) + '\n'
-                    msg += 'The indices for ' + str(dim) + ' in the slice argument are out of bounds'
+                    msg += 'The indices for ' + str(dim) + ' in the inds argument are out of bounds'
                     raise IndexError(msg)
                 coords[dim] = []
                 for i in range(source.shape[d]):
@@ -702,10 +1955,10 @@ class Series(Record):
         if source.size == 0:
             # If there are not yet any instances at the correct coordinates, they will be created from scratch
             source = [self.new_instance(MRImage()) for _ in range(nr_of_slices)]
-            set_ndarray(self, array, source=source, coords=coords, affine=np.eye(4))
+            set_pixel_values(self, array, source=source, coords=coords)
         elif array.shape[2:] == source.shape:
             # If the new array has the same shape, use the exact headers.
-            set_ndarray(self, array, source=source.ravel().tolist(), coords=coords)
+            set_pixel_values(self, array, source=source.ravel().tolist(), coords=coords)
         else:
             # If the new array has a different shape, use the first header for all and delete all the others
             # This happens when some of the new coordinates are present, but not all.
@@ -714,16 +1967,116 @@ class Series(Record):
             for series in source[1:]:
                 series.remove()
             source = [source[0]] + [source[0].copy_to(self) for _ in range(nr_of_slices-1)]
-            set_ndarray(self, array, source=source, coords=coords, affine=np.eye(4))
+            set_pixel_values(self, array, source=source, coords=coords)
+    
+    def subseries(self, **kwargs)->Series:
+        """Extract a subseries based on values of header elements.
 
+        Args:
+            kwargs: Any number of valid DICOM (tag, value) keyword arguments.
 
-    #
-    # Following APIs are obsolete and will be removed in future versions
-    #
+        Returns:
+            Series: a new series as a sibling under the same parent.
+
+        See Also:
+            :func:`~split_by`
+
+        Example:
+
+            Create a multi-slice series with multiple flip angles and repetition times:
+
+            >>> coords = {
+            ...    'SliceLocation': np.arange(16),
+            ...    'FlipAngle': [2, 15, 30],
+            ...    'RepetitionTime': [2.5, 5.0, 7.5],
+            ... }
+            >>> zeros = db.zeros((128, 128, 16, 3, 2), coords)
+
+            Create a new series containing only the data with flip angle 2 and repetition time 7.5:
+
+            >>> volume = zeros.subseries(FlipAngle=2.0, RepetitionTime=7.5)
+
+            Check that the volume series now has two dimensions of size 1:
+
+            >>> array = volume.pixel_values(dims=tuple(coords))
+            >>> print(array.shape)
+            (128, 128, 16, 1, 1)
+
+            and only one flip angle and repetition time:
+
+            >>> print(volume.FlipAngle, volume.RepetitionTime)
+            2.0 7.5
+
+            and that the parent study now has two series:
+
+            >>> volume.study().print()
+            ---------- STUDY ---------------
+            Study New Study [None]
+            Series 001 [New Series]
+                Nr of instances: 96
+            Series 002 [New Series]
+                Nr of instances: 16
+            --------------------------------
+        """
+        return subseries(self, move=False, **kwargs)
+    
+    def slice_groups(self, dims=('InstanceNumber',)) -> list:
+        """Return a list of slice groups in the series.
 
+        In dbdicom, a *slice group* is defined as a series of slices that have the same orientation. It is common for a single series to have images with multiple orientations, such as in localizer series in MRI. For such a series, returning all data in a single array may not be meaningful. 
+
+        Formally, a *slice group* is a dictionary with two entries: 'ndarray' is the numpy.ndarray with the data along the dimensions provided by the dims argument, and 'affine' is the 4x4 affine matrix of the slice group. The function returns a list of such dictionaries, one for each slice group in the series.
+
+        Args:
+            dims (tuple, optional): Dimensions for the returned arrays. Defaults to ('InstanceNumber',).
+
+        Returns:
+            list: A list of slice groups (dictionaries), one for each slice group in the series.
+
+        Examples:
+
+            >>> series = db.ones((128,128,5,10))
+            >>> sgroups = series.slice_groups(dims=('SliceLocation', 'AcquisitionTime'))
+
+            Since there is only one slice group in the series, ``sgroups`` is a list with one element:
+
+            >>> print(len(sgroups))
+            1
+
+            The array of the slice group is the entire volume of the series:
+
+            >>> print(sgroups[0]['ndarray'].shape)
+            (128, 128, 5, 10)
+
+            And the affine of the series has not changed from the default (identity):
+
+            >>> print(sgroups[0]['affine'])
+            [[1. 0. 0. 0.]
+             [0. 1. 0. 0.]
+             [0. 0. 1. 0.]
+             [0. 0. 0. 1.]]
 
-    # def slice_groups(*args, **kwargs):
-    #     return slice_groups(*args, **kwargs)
+        """
+        
+        slice_groups = []
+        image_orientation = self.ImageOrientationPatient
+
+        # Multiple slice groups in series - return list of cuboids
+        if isinstance(image_orientation[0], list):
+            for dir in image_orientation:
+                slice_group = instance_array(self, ImageOrientationPatient=dir)
+                affine = _slice_group_affine_matrix(list(slice_group), dir)
+                array, _ = _get_pixel_array_from_instance_array(slice_group, sortby=list(dims), pixels_first=True)
+                slice_groups.append({'ndarray': array[...,0], 'affine': affine})
+        
+        # Single slice group in series - return a list with a single affine matrix
+        else:
+            slice_group = instance_array(self)
+            affine = _slice_group_affine_matrix(list(slice_group), image_orientation)
+            array, _ = _get_pixel_array_from_instance_array(slice_group, sortby=list(dims), pixels_first=True)
+            slice_groups.append({'ndarray': array[...,0], 'affine': affine})
+
+        return slice_groups
     
     def affine_matrix(self):
         return affine_matrix(self)
@@ -740,42 +2093,348 @@ class Series(Record):
     def set_pixel_array(*args, **kwargs):
         set_pixel_array(*args, **kwargs)
 
+    def ndarray(self, *args, **kwargs):
+        return self.pixel_values(*args, **kwargs)
+
+    def set_ndarray(self, *args, **kwargs):
+        self.set_pixel_values(*args, **kwargs)
+
+
+
+def _filter_values(vframes, slice, coords, exclude=False):
+    # vframes: list with one item per frame, each item being a list of values.
+    # filters: dictionary of tag: value pairs.
+    if slice=={} and coords=={}:
+        fvalues = vframes
+    else:
+        fvalues = []
+        nf = len(slice)
+        nl = _coords_size(coords)
+        nc = len(coords)
+        for vframe in vframes:
+            in_slice = True
+            for i, s in enumerate(slice):
+                if isinstance(slice[s], np.ndarray):
+                    in_slice = vframe[i-nf-nc] in slice[s]
+                else:
+                    in_slice = vframe[i-nf-nc] == slice[s]
+                if exclude:
+                    in_slice = not in_slice
+                if not in_slice:
+                    break
+            if nl==0:
+                in_coords = True
+            else:
+                in_coords = False
+                for l in range(nl):
+                    at_l = True
+                    for i, loc in enumerate(coords):
+                        at_l = at_l and (vframe[i-nc] == coords[loc][l])
+                    in_coords = in_coords or at_l
+                    if at_l:
+                        break
+                if exclude:
+                    in_coords = not in_coords
+            if in_slice and in_coords:
+                fvalues.append(vframe[:-nf-nc])
+
+    if len(fvalues) == 0:
+        return np.array([]).reshape((0,0))
+    
+    # Create array of return values. Values can be of different types including lists so this must be an object array.
+    nd, nf = len(fvalues[0]), len(fvalues)
+    rvalues = np.empty((nd,nf), dtype=object)
+    for d in range(nd):
+        for f in range(nf):
+            rvalues[d,f] = fvalues[f][d]
+
+    return rvalues
+    
+
+
+def _filter_values_ind(vframes, slice, coords, exclude=False):
+    if slice=={} and coords=={}:
+        return np.arange(len(vframes), dtype=int)
+    finds = []
+    nf = len(slice)
+    nl = _coords_size(coords)
+    nc = len(coords)
+    for iv, vframe in enumerate(vframes):
+        in_slice = True
+        for i, s in enumerate(slice):
+            if isinstance(slice[s], np.ndarray):
+                in_slice = vframe[i-nf-nc] in slice[s]
+            else:
+                in_slice = vframe[i-nf-nc] == slice[s]
+            if exclude:
+                in_slice = not in_slice
+            if not in_slice:
+                break
+        if nl==0:
+            in_coords = True
+        else:
+            in_coords = False
+            for l in range(nl):
+                at_l = True
+                for i, loc in enumerate(coords):
+                    at_l = at_l and (vframe[i-nc] == coords[loc][l])
+                in_coords = in_coords or at_l
+                if at_l:
+                    break
+            if exclude:
+                in_coords = not in_coords
+        if in_slice and in_coords:
+            finds.append(iv)
+    return np.array(finds, dtype=int)
+
+
+def _coords_shape(coords):
+    if coords == {}:
+        return (0,)
+    
+    # Check that all values are arrays.
+    for c in coords:
+        if not isinstance(coords[c], np.ndarray):
+            msg = 'Coordinate values must be provided as numpy arrays.'
+            msg += '\nBut the value of ' + str(c) + ' is a ' + str(type(c))
+            raise ValueError(msg)
+        
+    shapes = [coords[tag].shape for tag in coords]
+    shape = shapes[0]
+    for s in shapes[1:]:
+        if s != shape:
+            msg = 'Dimensions are ambiguous - not all coordinates have the same shape.'
+            raise ValueError(msg)
+    return shapes[0]  
+
+
+def _coords_size(coords):
+
+    if coords == {}:
+        return 0 
+    
+    for c in coords:
+        if not isinstance(coords[c], np.ndarray):
+            msg = 'Coordinate values must be provided as numpy arrays.'
+            msg += '\nBut the value of ' + str(c) + ' is a ' + str(type(c))
+            raise ValueError(msg)
+    
+    # Coordinate values must a have the same size.
+    sizes = np.unique([coords[tag].size for tag in coords])
+    if len(sizes) > 1:
+        msg = 'These are not proper dimensions. Each coordinate must have the same number of values.'
+        raise ValueError(msg)
+    return sizes[0]  
+
+def _coords_vals(coords):
+    values = [coords[tag].ravel() for tag in coords]
+    values = np.stack(values)
+    return values
+ 
+def _check_if_ivals(values):
+    if None in values:
+        msg = 'These are not proper dimensions. Coordinate values must be defined everywhere.'
+        raise ValueError(msg)
+    
+    # Check if the values are unique
+    for f in range(values.shape[1]-1):
+        for g in range(f+1, values.shape[1]):
+            equal = True
+            for d in range(values.shape[0]):
+                if values[d,f] != values[d,g]:
+                    equal = False
+                    break
+            if equal:
+                msg = 'These are not proper dimensions. Coordinate values must be unique.'
+                raise ValueError(msg)
+    # if values.shape[1] != np.unique(values, axis=1).shape[1]:
+    #     msg = 'These are not proper dimensions. Coordinate values must be unique.'
+    #     raise ValueError(msg)
+
+def _check_if_coords(coords):
+
+    # Check that all values are arrays.
+    for c in coords:
+        if not isinstance(coords[c], np.ndarray):
+            msg = 'Coordinate values must be provided as numpy arrays.'
+            msg += '\nBut the value of ' + str(c) + ' is a ' + str(type(coords[c]))
+            raise ValueError(msg)
+
+    # Check if coordinates are unique
+    values = _coords_vals(coords)
+    _check_if_ivals(values)
+    return coords
+
+def _mesh_to_coords(coords):
+    for c in coords:
+        coords[c] = coords[c].ravel()
+    return _check_if_coords(coords)
+    
+
+def _grid_to_meshcoords(gridcoords):
+
+    grid = []
+    for c in gridcoords:
+        if not isinstance(gridcoords[c], np.ndarray):
+            msg = 'Grid coordinates have to be numpy arrays.'
+            raise TypeError(msg)
+        if len(gridcoords[c].shape) != 1:
+            msg = 'Grid coordinates have to be one-dimensionial.'
+            raise ValueError(msg)
+        if len(np.unique(gridcoords[c])) != len(gridcoords[c]):
+            msg = 'Grid coordinates have to be unique.'
+            raise ValueError(msg)
+        grid.append(gridcoords[c])
+
+    mesh = np.meshgrid(*tuple(grid), indexing='ij')
+    meshcoords = {}
+    for i, c in enumerate(gridcoords):
+        meshcoords[c] = mesh[i]
+    _check_if_coords(meshcoords)
+    return meshcoords
+
+
+def _meshcoords_to_grid(coords):
+    dims = tuple(coords)
+    gridcoords = {}
+    for d, dim in enumerate(dims):
+        gridcoords[dim] = []
+        dvals = coords[dim]
+        for i in range(dvals.shape[d]):
+            dvals_i = dvals.take(i, axis=d)
+            dvals_i = np.unique(dvals_i)
+            if len(dvals_i) > 1:
+                msg = 'These are not proper grid coordinates.'
+                raise ValueError(msg)
+            gridcoords[dim].append(dvals_i[0])
+        gridcoords[dim] = np.array(gridcoords[dim])
+    return gridcoords  
+
+
+def _grid_to_coords(grid):
+    if grid == {}:
+        return {}
+    coords = _grid_to_meshcoords(grid)
+    for c in coords:
+        coords[c] = coords[c].flatten()
+    return coords
+
+def _as_meshcoords(coords):
+
+    # First check that they are proper coordinates
+    values = _coords_vals(coords)
+    _check_if_ivals(values)
+    values = _meshvals(values)
+    meshcoords = {}
+    for i, c in enumerate(coords):
+        meshcoords[c] = values[i,...]
+    return meshcoords
+        
+def _meshvals(values):
+    # Input array shape: (d, f) with d = nr of dims and f = nr of frames
+    # Output array shape: (d, f1,..., fd)
+    if values.size == 0:
+        return np.array([])
+    # List the unique values of the first coordinate
+    vals, cnts = np.unique(values[0,:], return_counts=True)
+    # Check that there is an equal number of each value
+    if len(np.unique(cnts)) > 1:
+        msg = 'These are not mesh coordinates.'
+        raise ValueError(msg) 
+    # If there is only one dimension, we are done
+    if values.shape[0] == 1:
+        return values
+    mesh = []
+    for v in vals:
+        vind = np.where(values[0,:]==v)[0]
+        vmesh = _meshvals(values[1:,vind])
+        mesh.append(vmesh)
+    mesh = np.stack(mesh, axis=1)
+    a = [np.full(mesh.shape[2:], v) for v in vals]
+    a = np.stack(a)
+    a = np.expand_dims(a,0)
+    mesh = np.concatenate((a, mesh))
+    return mesh
+
+def _meshdata(vals, crds, cmesh):
+    mshape = (vals.shape[0],) + cmesh.shape[1:]
+    if mshape[0]==0:
+        return vals.reshape(mshape)
+    vmesh = np.zeros(mshape, dtype=object)
+    cmesh = cmesh.reshape((cmesh.shape[0],-1))
+    vmesh = vmesh.reshape((vmesh.shape[0],-1))
+    for i in range(vals.shape[1]):
+        # find location of coordinate i in cmesh
+        for j in range(cmesh.shape[1]):
+            if np.array_equal(cmesh[:,j], crds[:,i]):
+                break
+        # Write value i at the same location in vmesh
+        vmesh[:,j] = vals[:,i]
+    return vmesh.reshape(mshape)
+
+def _concatenate_coords(coords:tuple, mesh=False):
+    concat = {}
+    for c in coords[0]:
+        concat[c] = coords[0][c].flatten().copy()
+    for coord in coords[1:]: 
+        for c in coord:
+            if c not in concat:
+                msg = 'Cannot concatenate - all coordinates must have the same variables.'
+                raise ValueError(msg)
+            concat[c] = np.concatenate((concat[c], coord[c].flatten()))
+    _check_if_coords(concat)
+    if mesh:
+        return _as_meshcoords(concat)
+    else:
+        return concat
+
+
+### OBSOLETE BELOW HERE
 
-def set_ndarray(series, array, source=None, coords=None, affine=None, **kwargs): 
+
+def set_pixel_values(series, array, source=None, coords=None, **kwargs): 
 
     # If coordinates are given as 1D arrays, turn them into grids and flatten for iteration.
     if coords is not None:
         mesh_coords = {}
-        v0 = list(coords.values())[0]
-        if np.array(v0).ndim==1: # regular grid
-            pos = tuple([coords[c] for c in coords])
-            pos = np.meshgrid(*pos)
-            for i, c in enumerate(coords):
-                mesh_coords[c] = pos[i].ravel()
+        v = list(coords.values())
+        if v != []:
+            v0 = v[0]
+            if np.array(v0).ndim==1: # regular grid
+                pos = tuple([coords[c] for c in coords])
+                pos = np.meshgrid(*pos, indexing='ij')
+                for i, c in enumerate(coords):
+                    mesh_coords[c] = pos[i].ravel()
 
     # Flatten array for iterating
     nr_of_slices = int(np.prod(array.shape[2:]))
     array = array.reshape((array.shape[0], array.shape[1], nr_of_slices)) # shape (x,y,i)
+    attr = {**series.attributes, **kwargs}
+    if 'SliceLocation' in coords:
+        affine = series.affine()
     for i, image in enumerate(source):
         series.progress(i+1, len(source), 'Saving array..')
         image.read()
 
-        # If needed, use Defaults for geometry markers
-        if affine is not None:
-            affine[2, 3] = i
-            image.affine_matrix = affine
-
         # Update any other header data provided
-        for attr, vals in kwargs.items(): 
-            if isinstance(vals, list):
-                setattr(image, attr, vals[i])
-            else:
-                setattr(image, attr, vals)
+        for a, v in attr.items(): 
+            setattr(image, a, v)
+            # if isinstance(v, list):
+            #     setattr(image, a, v[i])
+            # else:
+            #     setattr(image, a, v)
+
+        # # If needed, use Defaults for geometry markers
+        # if affine is not None:
+        #     affine[2, 3] = i # not sufficiently general
+        #     image.affine_matrix = affine
 
         # Set coordinates.
         if mesh_coords is not None:
             for c in mesh_coords:
                 image[c] = mesh_coords[c][i] 
+                if c == 'SliceLocation':
+                    image['ImagePositionPatient'] = image_utils.image_position_from_slice_location(mesh_coords[c][i], affine) 
 
         image.set_pixel_array(array[:,:,i])
         image.clear()
@@ -793,7 +2452,7 @@ def subseries(record, move=False, **kwargs):
     series = record.new_sibling()
     instances = record.instances(**kwargs)
     for i, instance in enumerate(instances):
-        record.status.progress(i+1, len(instances), 'Extracting subseries..')
+        record.progress(i+1, len(instances), 'Extracting subseries..')
         if move:
             instance.move_to(series)
         else:
@@ -815,31 +2474,34 @@ def read_npy(record):
 
 
 
-def array(record, **kwargs):
+def array(record, sortby=None, pixels_first=False, first_volume=False):
     if isinstance(record, list): # array of instances
         arr = np.empty(len(record), dtype=object)
         for i, rec in enumerate(record):
             arr[i] = rec
-        return _get_pixel_array_from_instance_array(arr, **kwargs)
+        return _get_pixel_array_from_instance_array(arr, sortby=sortby, pixels_first=pixels_first, first_volume=first_volume)
     elif isinstance(record, np.ndarray): # array of instances
-        return _get_pixel_array_from_instance_array(record, **kwargs)
+        return _get_pixel_array_from_instance_array(record, sortby=sortby, pixels_first=pixels_first, first_volume=first_volume)
     else:
-        return get_pixel_array(record, **kwargs)
+        return get_pixel_array(record, sortby=sortby, pixels_first=pixels_first, first_volume=first_volume)
     
 
-def get_pixel_array(record, sortby=None, first_volume=False, **kwargs): 
-
+def get_pixel_array(record, sortby=None, first_volume=False, pixels_first=False):
     source = instance_array(record, sortby)
-    array, headers = _get_pixel_array_from_sorted_instance_array(source, **kwargs)
+    array, headers = _get_pixel_array_from_sorted_instance_array(source, pixels_first=pixels_first)
     if first_volume:
         return array[...,0], headers[...,0]
     else:
         return array, headers
 
 
-def _get_pixel_array_from_instance_array(instance_array, sortby=None, **kwargs):
+def _get_pixel_array_from_instance_array(instance_array, sortby=None, pixels_first=False, first_volume=False):
     source = sort_instance_array(instance_array, sortby)
-    return _get_pixel_array_from_sorted_instance_array(source, **kwargs)   
+    array, headers = _get_pixel_array_from_sorted_instance_array(source, pixels_first=pixels_first) 
+    if first_volume:
+        return array[...,0], headers[...,0]
+    else:
+        return array, headers  
 
 
 def _get_pixel_array_from_sorted_instance_array(source, pixels_first=False):
@@ -924,8 +2586,52 @@ def set_pixel_array(series, array, source=None, pixels_first=False, **kwargs):
         image.set_pixel_array(array[i,...])
         image.clear()
 
-
-
+# TODO: make this obsolete - only used ion affine_matrix
+def is_multislice(series):
+    orientation = series.ImageOrientationPatient
+    # Series is multislice if there are multiple unique orientations
+    if isinstance(orientation[0], list):
+        return True
+    #
+    # NOTE: 08/01/25: Added below conditions to correctly deal with situations
+    # where individual slices have been shifted but not rotated.
+    # From here: a series is multislice as soon as slices are not part of a 
+    # uniformly spaced 3D volume.
+    # 
+    pos = series.ImagePositionPatient
+    # If there is only one slice location, the series is not multislice
+    if not isinstance(pos[0], list):
+        return False
+    #
+    # If there are multiple positions, check that they are all on the slice 
+    # vector. If at least one if them is not, the series is multislice.
+    #
+    # Get slice vector
+    row_vec = np.array(orientation[:3])    
+    column_vec = np.array(orientation[3:]) 
+    slice_vec = np.cross(row_vec, column_vec)
+    for p in pos[1:]:
+        # Position relative to first slice position
+        prel = np.array(p)-np.array(pos[0])
+        # Parallel means cross product has length zero
+        norm = np.linalg.norm(np.cross(slice_vec, prel))
+        # Round to micrometers to avoid numerical error
+        if np.round(norm, 3) != 0:
+            return True
+    #
+    # If they are all on the slice vector, check that they have the same 
+    # spacing. If more than one spacing is found, the series is multislice.
+    #
+    # Get slice locations
+    loc = [np.dot(p, slice_vec) for p in pos]
+    # Sort slice locations
+    loc = np.sort(loc)
+    # Get unique slice spacing (to micrometer precision)
+    spacing = np.unique(np.around(loc[1:]-loc[:-1], 3))
+    # If there is more than 1 slice spacing, the series is multislice
+    return spacing.size != 1
+
+# TODO: make this obsolete   -replace by affines
 def affine_matrix(series):
     """Returns the affine matrix of a series.
     
@@ -939,14 +2645,30 @@ def affine_matrix(series):
         msg = 'This is a required DICOM field \n'
         msg += 'The data may be corrupted - please check'
         raise ValueError(msg)
+    
     # Multiple slice groups in series - return list of affine matrices
-    if isinstance(image_orientation[0], list):
+    if is_multislice(series):
+        #
+        # NOTE: 08/01/2025: Changed definition of slice groups from "frames with 
+        # the same orientation" to "frames with the same orientation and position"
+        #
+        # Get unique image positions
+        image_position = series.ImagePositionPatient
+        # Make sure orientations and positions are losts
+        if not isinstance(image_orientation[0], list):
+            image_orientation = [image_orientation]
+        if not isinstance(image_position[0], list):
+            image_position = [image_position]
+        # Return one affine per slice group
         affine_matrices = []
         for dir in image_orientation:
-            slice_group = series.instances(ImageOrientationPatient=dir)
-            affine = _slice_group_affine_matrix(slice_group, dir)
-            affine_matrices.append((affine, slice_group))
+            for pos in image_position:
+                slice_group = series.instances(ImageOrientationPatient=dir, ImagePositionPatient=pos)
+                if len(slice_group) > 0:
+                    affine = _slice_group_affine_matrix(slice_group, dir)
+                    affine_matrices.append((affine, slice_group))
         return affine_matrices
+    
     # Single slice group in series - return a single affine matrix
     else:
         slice_group = series.instances()
@@ -977,7 +2699,7 @@ def _slice_group_affine_matrix(slice_group, image_orientation):
                 slice_group[0].PixelSpacing)    # assume all the same pixel spacing
         
 
-def sort_instance_array(instance_array, sortby=None, status=True):
+def sort_instance_array(instance_array, sortby=None):
     if sortby is None:
         return instance_array
     else:
@@ -985,10 +2707,55 @@ def sort_instance_array(instance_array, sortby=None, status=True):
             sortby = [sortby]
         df = read_dataframe_from_instance_array(instance_array, sortby + ['SOPInstanceUID'])
         df.sort_values(sortby, inplace=True) 
-        return df_to_sorted_instance_array(instance_array[0], df, sortby, status=status)
-        
+        return df_to_sorted_instance_array(instance_array[0], df, sortby)
+
+
+def _instances(series, dims:tuple=None, inds:dict=None, select={}, **filters):
+
+    # Use default dimensions if needed.
+    if dims is None:
+        dims = ('InstanceNumber',)
 
-def instance_array(record, sortby=None, status=True, **filters): 
+    # If indices are provided, check that they are compatible with dims.
+    if inds is not None:
+        for dim in inds:
+            if dim not in dims:
+                msg = 'Indices must be in the dimensions provided.'
+                raise ValueError(msg)
+    
+    # Get the frames and sort by dim
+    frames = instance_array(series, list(dims), report_none=True, select=select, **filters)
+    if frames.size == 0:
+        return frames.reshape(tuple([0]*len(dims)))
+    if frames.shape[-1] > 1:
+        d = ''.join(['('] + [str(v)+', ' for v in dims] + [')'])
+        msg = 'series shape is ambiguous in dimensions ' + d
+        msg += '\n--> Multiple frames exist at some or all locations.'
+        msg += '\n--> Hint: use Series.unique() to list the values at all locations.'
+        raise ValueError(msg)
+    if None in frames:
+        d = ''.join(['('] + [str(v)+', ' for v in dims] + [')'])
+        msg = 'series shape is not well defined in dimensions ' + d
+        msg += '\n--> There are no frames at some locations.'
+        msg += '\n--> Hint: use Series.value() to find the values at all locations.'
+        raise ValueError(msg)
+    frames = frames[...,0]
+
+    # Extract indices and coordinates if provided
+    if inds is not None:
+        for dim in inds:
+            ind = inds[dim]
+            d = dims.index(dim)
+            frames = frames.take(ind, axis=d)
+            if not isinstance(ind, np.ndarray):
+                frames = np.expand_dims(frames, axis=d)
+    if frames.size == 0:
+        return frames.reshape(tuple([0]*len(dims)))
+    else:
+        return frames
+
+
+def instance_array(record, sortby=None, report_none=False, select={}, **filters): 
     """Sort instances by a list of attributes.
     
     Args:
@@ -998,7 +2765,7 @@ def instance_array(record, sortby=None, status=True, **filters):
         An ndarray holding the instances sorted by sortby.
     """
     if sortby is None:
-        instances = record.instances(**filters)
+        instances = record.instances(**filters) # Note filter values here cant be arrays
         array = np.empty(len(instances), dtype=object)
         for i, instance in enumerate(instances): 
             array[i] = instance
@@ -1006,26 +2773,30 @@ def instance_array(record, sortby=None, status=True, **filters):
     else:
         if not isinstance(sortby, list):
             sortby = [sortby]
-        df = record.read_dataframe(sortby + ['SOPInstanceUID']) # needs a **filters option
+        df = record.read_dataframe(sortby + ['SOPInstanceUID'], select=select, **filters) 
         df = df[df.SOPInstanceUID.values != None]
         if df.empty:
             return np.array([])
+        if report_none:
+            if None in df.values:
+                d = ''.join(['('] + [str(v)+', ' for v in sortby] + [')'])
+                msg = 'series shape is not well defined in dimensions ' + d
+                msg += '\n--> Some of the dimensions are not defined in the header.'
+                msg += '\n--> Hint: use Series.value() to find the undefined values.'                
+                raise ValueError(msg)
         df.sort_values(sortby, inplace=True) 
-        return df_to_sorted_instance_array(record, df, sortby, status=status)
+        return df_to_sorted_instance_array(record, df, sortby)
 
 
-def df_to_sorted_instance_array(record, df, sortby, status=True): 
-    # note record here only passed for access to the function instance() and progress()
-    # This really should be db.instance()
+def df_to_sorted_instance_array(record, df, sortby): 
 
     data = []
     vals = df[sortby[0]].unique()
-    for i, c in enumerate(vals):
-        if status: 
-            record.progress(i, len(vals), message='Sorting pixel data..')
+    for i, c in enumerate(vals): 
+        record.progress(i, len(vals), message='Sorting pixel data..')
         # if a type is not supported by np.isnan()
         # assume it is not a nan
-        if c is None: # this happens when undefined keywrod is used
+        if c is None: # this happens when undefined keyword is used
             dfc = df[df[sortby[0]].isnull()]
         else:
             try: 
@@ -1039,7 +2810,7 @@ def df_to_sorted_instance_array(record, df, sortby, status=True):
         if len(sortby) == 1:
             datac = df_to_instance_array(record, dfc)
         else:
-            datac = df_to_sorted_instance_array(record, dfc, sortby[1:], status=False)
+            datac = df_to_sorted_instance_array(record, dfc, sortby[1:])
         data.append(datac)
     return _stack(data, align_left=True)