dbdicom 0.2.0__py3-none-any.whl → 0.2.3__py3-none-any.whl

dbdicom/types/series.py

@@ -3,14 +3,17 @@ from __future__ import annotations
 
 import os
 import math
+from numbers import Number
 
 import numpy as np
+import pandas as pd
+import nibabel as nib
 
 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
 
 
@@ -49,6 +52,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):
@@ -64,84 +69,1337 @@ class Series(Record):
         else:
             return self.record('Instance', uids, **attr)
 
-
-
-
-    def export_as_npy(self, directory=None, filename=None, sortby=None, pixels_first=False):
-        """Export array in numpy format"""
-
-        if directory is None: 
-            directory = self.dialog.directory(message='Please select a folder for the png data')
-        if filename is None:
-            filename = self.SeriesDescription
-        array, _ = self.get_pixel_array(sortby=sortby, pixels_first=pixels_first)
-        file = os.path.join(directory, filename + '.npy')
-        with open(file, 'wb') as f:
-            np.save(f, array)
-
-
     def export_as_dicom(self, path): 
-        # instance = self.instance()
-        # patient = "".join([c if c.isalnum() else "_" for c in instance.PatientID])
-        # study = "".join([c if c.isalnum() else "_" for c in instance.StudyDescription])
-        # series = "".join([c if c.isalnum() else "_" for c in instance.SeriesDescription])
-        # path = os.path.join(os.path.join(os.path.join(path, patient), study), series)
-        # path = export_path(path)
-
         folder = self.label()
         path = export_path(path, folder)
-
+        # Create a copy so that exported datasets have different UIDs.
         copy = self.copy()
         mgr = Manager(path, status=self.status)
         mgr.open(path)
-        mgr.import_datasets(copy.files())
+        for i in copy.instances():
+            ds = i.get_dataset()
+            mgr.import_dataset(ds)
         copy.remove()
 
-
-    def export_as_png(self, path):
-        """Export all images as png files"""
+    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.export_as_png(path)
-
+            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"""
+        #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):
+        if dims is None:
+            folder = self.label()
+            path = export_path(path, folder)
+            images = self.images()
+            for i, img in enumerate(images):
+                img.progress(i+1, len(images), 'Exporting npy..')
+                img.export_as_npy(path)
+        else:
+            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()
+            path = export_path(path, folder)
+            affine = self.affine_matrix()
+            if not isinstance(affine, list):
+                affine = [affine]
+            for a in affine:
+                matrix = a[0]
+                images = a[1]
+                for i, img in enumerate(images):
+                    img.progress(i+1, len(images), 'Exporting nifti..')
+                    img.export_as_nifti(path, matrix)
+        else:
+            ds = self.instance().get_dataset()
+            sgroups = self.slice_groups(dims=dims)
+            for i, sg in enumerate(sgroups):
+                self.progress(i+1, len(sgroups), 'Exporting nifti..')
+                dicom_header = nib.nifti1.Nifti1DicomExtension(2, ds)
+                nifti1_image = nib.Nifti1Image(sg['ndarray'], image_utils.affine_to_RAH(sg['affine']))
+                nifti1_image.header.extensions.append(dicom_header)
+                filepath = self.label()
+                filepath = os.path.join(path, filepath + '[' + str(i) + '].nii')
+                nib.save(nifti1_image, filepath)
 
-    def export_as_nifti(self, path: str):
-        """Export images in nifti format.
+    def import_dicom(self, files):
+        uids = self.manager.import_datasets(files)
+        self.manager.move_to(uids, self.uid)
+
+
+
+    def coords(self, dims=('InstanceNumber', ), mesh=False, slice={}, coords={}, exclude=False, **filters)->dict:
+        """return a dictionary of coordinates.
 
         Args:
-            path (str): path where results are to be saved.
+            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:
+            dict: dictionary of coordinates, one entry for each dimension. The values for each coordinate are returned as an darray with one dimension.
+
+        See also:
+            `set_coords`
+
+        Example:
+
+            Create an empty series with 3 slice dimensions:
+
+            >>> 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)
+            
+            Retrieve the coordinates:
+
+            >>> coords = series.coords(tuple(coords))
+            >>> coords['FlipAngle']
+            [2,10,2,10,2,10]
+            >>> coords['RepetitionTime']
+            [1,1,5,5,15,15]
+
+            Check the result in default dimensions:
+
+            >>> coords = series.coords()
+            >>> coords['InstanceNumber']
+            [1,2,3,4,5,6]
+
+            In this case the slice location and flip angle along are sufficient to identify the frames, so these are valid coordinates:
+
+            >>> coords = series.coords(('SliceLocation', 'FlipAngle'))
+            >>> coords['SliceLocation']
+            [0,0,1,1,2,2]
+
+            # However slice location and acquisition time are not sufficient as coordinates because each combination appears twice. So this throws an error:
+
+            >>> series.coords(('SliceLocation','RepetitionTime'))
+            ValueError: These are not proper coordinates. Coordinate values must be unique.
         """
-        folder = self.label()
-        path = export_path(path, folder)
-        affine = self.affine_matrix()
-        if not isinstance(affine, list):
-            affine = [affine]
-        for a in affine:
-            matrix = a[0]
-            images = a[1]
-            for i, img in enumerate(images):
-                img.status.progress(i+1, len(images), 'Exporting nifti..')
-                img.export_as_nifti(path, matrix)
 
+        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 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.
+
+        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:
+            An `numpy.ndarray` of values with dimensions as specified by *dims*. If the value is not defined in *one or more* of the slices, an empty array is returned.
+
+        See also:
+            `unique`
+            `coords`
+            `gridcoords`
+
+        Note:
+            In order to list the values in the case one or more are absent in the headers, use `Series.unique()` instead.
+
+        Example:
+
+            Create a zero-filled series with 3 slice dimensions:
+
+            >>> coords = {
+            ...     'SliceLocation': 10*np.arange(4),
+            ...     'FlipAngle': np.array([2, 15, 30]),
+            ...     'RepetitionTime': np.array([2.5, 5.0]), }
+            >>> zeros = db.zeros((128,128,4,3,2), coords)
+
+            # If values() is called without dimensions, a flat array is returned with one value per frame, ordered by instance number:
+
+            >>> zeros.values('InstanceNumber')
+            [1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,191,20,21,22,23,24]
+            >>> zros.values('FlipAngle')
+            [2,2,15,15,30,30,2,2,15,15,30,30,2,2,15,15,30,30,2,2,15,15,30,30]
+
+            if dimensions are provided, an array of the appropriate shape is returned:
+
+            >>> dims = tuple(coords)
+            >>> tacq = series.values('AcquisitionTime', dims)
+            >>> tacq.shape
+            (4,3,2)
+            >>> tacq[0,0,0]
+            28609.057496
+
+            In this case all values are the same:
+
+            >>> np.unique(tacq)
+            [28609.057496]
+
+            If a value is not defined in the header, None is returned:
+            >>> series.values('Gobbledigook')[:2]
+            [None None]
+
+            Specify keywords to select a subset of values:
+
+            >>> tacq = zeros.values('AcquisitionTime', dims, FlipAngle=15)
+            >>> tacq.shape
+            (4, 1, 2)
+
+            If none exist, and emptry array is returned:
+
+            >>> tacq = zeros.values('AcquisitionTime', dims, FlipAngle=0)
+            >>> tacq.size
+            0
+
+            Multiple possible values can be selected with arrays:
+
+            >>> tacq = zeros.values('AcquisitionTime', dims, FlipAngle=np.array([15,30]))
+            >>> tacq.shape
+            (4, 2, 2)
+
+            Any number of keywords can be added as filters:
+
+            >>> tacq = zeros.values('AcquisitionTime', dims, FlipAngle=np.array([15,30]), SliceLocation=np.array([10,20]))
+            >>> tacq.shape
+            (2, 2, 2)
+
+            Filters can alos be set using the *select* argument: 
+
+            >>> tacq = zeros.values('AcquisitionTime', dims, select={'FlipAngle': 15})
+            >>> tacq.shape
+            (4, 1, 2)
+
+            This also allows (group, element) tags:
+
+            >>> tacq = zeros.values('AcquisitionTime', dims, select={(0x0018, 0x1314): 15})
+            >>> tacq.shape
+            (4, 1, 2)
+
+            Selections can also be made using indices rather than values:
+
+            >>> tacq = zeros.values('FlipAngle', dims, inds={'FlipAngle': 1})
+            >>> tacq.shape
+            (4, 1, 2) 
+
+            >>> tacq = zeros.values('AcquisitionTime', dims, inds={'FlipAngle':np.arange(2)})
+            >>> tacq.shape
+            (4, 2, 2)
+        """
+
+        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([])
+        
+        # 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
+
+
+    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
+        
+
+    def expand(self, coords={}, gridcoords={}): # gridcoords -> slice
+
+        if coords != {}:
+            pass
+        elif gridcoords != {}:
+            coords = _grid_to_coords(gridcoords)
+        else:
+            msg = 'Cannot expand without new coordinates'
+            raise ValueError(msg)
+
+        # 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 set_coords(self, new_coords:dict, dims=(), slice={}, coords={}, **filters):
+        """Set a dictionary of coordinates.
+
+        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:
+            `coords`
+            `set_gridcoords`
+
+        Example:
+
+            Create an empty series:
+
+            >>> 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)
+
+            Check the new coordinates:
+
+            >>> 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:
+            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 size of *value* does not match the size of the series.
+
+        See also:
+            `value`
+
+        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)
+
+            Change the acquisition time of the series to midnight (0 sec):
+
+            >>> series.value('AcquisitionTime')
+            28609.057496
+            >>> series.set_value('AcquisitionTime', 0)
+            >>> series.value('AcquisitionTime')
+            0
+
+            Set the acquisition time to a different value for each flip angle:
+
+            >>> tacq = np.repeat(60*np.arange(3), 8)
+            >>> series.set_value('AcquisitionTime', tacq, dims=('FlipAngle','InstanceNumber'))
+
+            Set the acquisition time to a different value for each flip angle and acquisition time:
+
+            >>> tacq = np.repeat(60*np.arange(6), 4)
+            >>> series.set_value('AcquisitionTime', tacq, dims=('FlipAngle','RepetitionTime','SliceLocation'))
+
+            Note: the size of the value and of the series need to match up. If not, an error is raised:
+
+            >>> 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:
 
-    def subseries(*args, move=False, **kwargs):
-        return subseries(*args, move=move, **kwargs)
+            >>> 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 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)   
+
+
+    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)
     
-    def split_by(self, keyword: str | tuple) -> list:
+        # 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:
@@ -152,7 +1410,11 @@ class Series(Record):
             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 subseries, where each element has the same value of the given keyword.
+            list: A list of ``Series`` instances, where each element has the same value of the given keyword.
+
+        See Also:
+            `slice`
+            `islice`
 
         Example: 
 
@@ -160,10 +1422,10 @@ class Series(Record):
 
             >>> coords = {
             ...    'FlipAngle': [2, 15, 30],
-            ...    'RepetitionTime': [2.5, 5.0, 7.5],
+            ...    'RepetitionTime': [2.5, 7.5],
             ... }
-            >>> zeros = db.zeros((3,2,128,128), coords)
-            >>> print(zeros)
+            >>> zeros = db.zeros((128, 128, 3, 2), coords)
+            >>> zeros.print()
             ---------- SERIES --------------
             Series 001 [New Series]
                 Nr of instances: 6
@@ -177,7 +1439,7 @@ class Series(Record):
 
             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:
 
-            >>> zeros_FA = zeros.split_by('FlipAngle')
+            >>> FA = zeros.split_by('FlipAngle')
             >>> zeros.study().print()
             ---------- STUDY ---------------
             Study New Study [None]
@@ -190,151 +1452,421 @@ class Series(Record):
                 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
         """
         
-        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'
+        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)
         
-        self.status.message('Splitting series..')
+        desc = self.instance().SeriesDescription + '[' + str(tag) + ' = '
         split_series = []
-        desc = self.instance().SeriesDescription + '[' + keyword + ' = '
-        for v in values:
-            kwargs = {keyword: v}
-            new = self.subseries(**kwargs)
+        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
 
-    def import_dicom(self, files):
-        uids = self.manager.import_datasets(files)
-        self.manager.move_to(uids, self.uid)
+        Returns:
+            tuple: (x-spacing, y-spacing, z-spacing)
 
-    def slice_groups(*args, **kwargs):
-        return slice_groups(*args, **kwargs)
+        See also:
+            `shape`
 
+        Examples:
+            Check the spacing of a digital reference object:
 
-    def affine_matrix(self):
-        return affine_matrix(self)
-    
+            >>> 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 ndarray(self, dims=('InstanceNumber',)) -> 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. Defaults to ('InstanceNumber',).
+   
+
+    def unique_affines(self)->np.ndarray:
+        """Return the array of unique affine matrices.
+
+        Raises:
+            ValueError: if the DICOM file is corrupted.
 
         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 (x,y) coordinates in the slice, the other dimensions are as specified by the dims argument.
+            np.ndarray: array of 4x4 ndarrays with the unique affine matrices of the series.
 
         See also:
-            :func:`~set_ndarray`
+            `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)]
+        """
+        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 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])
+        
+
+    def islice(self, indices={}, **inds) -> Series:
+        """Get a slice of the series by dimension indics
+
+        Args:
+            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.
+
+        Raises:
+            IndexError: when the indices in inds are out of range of the existing coordinates. 
+
+        See also:
+            `slice`
+            `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 (i.e. index 1):
+
+            >>> fa15 = series.islice(FlipAngle=1)
+
+            Retrieve the array and check the dimensions:
+
+            >>> array = fa15.pixel_values(dims=tuple(coords))
+            >>> print(array.shape)
+            (128, 128, 8, 1, 2)
+
+            Multiple possible indices can be specified as a list or np.ndarray:
+
+            >>> fa15 = series.slice(SliceLocation=[0,5], FlipAngle=1)
+            >>> 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=1)
+            >>> fa15 = series.slice({SliceLocation:[0,5], FlipAngle:1})
+            >>> fa15 = series.slice({(0x0020, 0x1041):[0,5], (0x0018, 0x1314):1})
+
+        """
+        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)
+                # 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 _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.
+            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 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:
+            `pixel_values`
+
+        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)
+
+            Retrieve the array and check that it is populated with zeros:
+
+            >>> array = series.pixel_values(dims=tuple(coords)) 
+            >>> print(np.mean(array))
+            0.0
+
+            Now overwrite the values with a new array of ones in a new shape:
+
+            >>> new_shape = (128,128,8)
+            >>> new_coords = {
+            ...     'SliceLocation': np.arange(8),
+            ... }
+            >>> ones = np.ones(new_shape)
+            >>> series.set_pixel_values(ones, coords=new_coords)
+
+            Retrieve the new array and check shape:
+            
+            >>> array = series.pixel_values(dims=tuple(new_coords))
+            >>> print(array.shape)
+            (128,128,8)
+
+            Check that the value is overwritten:
+
+            >>> print(np.mean(array))
+            1.0
+        """
+
+        # Check whether the arguments are valid, and initialize dims.
+        cnt = 0
+        if coords is not None:
+            cnt+=1
+            dims = tuple(coords)
+            if len(dims) != array.ndim-2:
+                msg = 'One coordinate must be specified for each dimensions in the array.'
+                raise ValueError(msg)
+            for d, dim in enumerate(coords):
+                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 inds is not None:
+            cnt+=1
+            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 inds must be provided'
+            raise ValueError(msg)
+        if cnt == 2:
+            msg = 'Only one of the optional arguments coords or inds must be provided'
+            raise ValueError(msg)
+
+        source = instance_array(self, sortby=list(dims))
+        
+        if coords is not None:
+            # Retrieve the instances corresponding to the coordinates.
+            if source.size != 0:
+                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)
+                    source = source.take(ind, axis=d)
+                    # 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(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 inds argument are out of bounds'
+                    raise IndexError(msg)
+                coords[dim] = []
+                for i in range(source.shape[d]):
+                    si = source.take(i,axis=d).ravel()
+                    coords[dim].append(si[0][dim])  
+
+        nr_of_slices = int(np.prod(array.shape[2:]))
+        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_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_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.
+            # TODO: This is overkill - only fill in the gaps with copies.
+            source = source.ravel().tolist()
+            for series in source[1:]:
+                series.remove()
+            source = [source[0]] + [source[0].copy_to(self) for _ in range(nr_of_slices-1)]
+            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.
+
+        Returns:
+            Series: a new series as a sibling under the same parent.
+
+        See Also:
+            :func:`~split_by`
 
         Example:
-            Create a zero-filled array, describing 8 MRI slices each measured at 3 flip angles and 2 repetition times:
+
+            Create a multi-slice series with multiple flip angles and repetition times:
 
             >>> coords = {
-            ...    'SliceLocation': np.arange(8),
+            ...    'SliceLocation': np.arange(16),
             ...    'FlipAngle': [2, 15, 30],
-            ...    'RepetitionTime': [2.5, 5.0],
+            ...    'RepetitionTime': [2.5, 5.0, 7.5],
             ... }
-            >>> zeros = db.zeros((128,128,8,3,2), coords)
+            >>> zeros = db.zeros((128, 128, 16, 3, 2), coords)
 
-            To retrieve the array, the dimensions need to be provided:
+            Create a new series containing only the data with flip angle 2 and repetition time 7.5:
 
-            >>> dims = ('SliceLocation', 'FlipAngle', 'RepetitionTime')
-            >>> array = zeros.ndarray(dims)
-            >>> print(array.shape)
-            (128, 128, 8, 3, 2)
+            >>> volume = zeros.subseries(FlipAngle=2.0, RepetitionTime=7.5)
 
-            The dimensions are the keys of the coordinate dictionary, so this could also have been called as:
+            Check that the volume series now has two dimensions of size 1:
 
-            >>> array = zeros.ndarray(dims=tuple(coords)) 
+            >>> array = volume.pixel_values(dims=tuple(coords))
             >>> print(array.shape)
-            (128, 128, 8, 3, 2)
-        """
-        array, _ = get_pixel_array(self, sortby=list(dims), first_volume=True, pixels_first=True)
-        return array
-
+            (128, 128, 16, 1, 1)
 
-    def set_ndarray(self, array:np.ndarray, dims=('InstanceNumber',), coords:dict=None):
-        """Assign new pixel data with a new numpy.ndarray. 
-
-        Args:
-            array (np.ndarray): array with new pixel data.
-            dims (tuple, optional): Dimensions of the result, as a tuple of valid DICOM tags of any length. Defaults to ('InstanceNumber',). Must be provided if coords are not given.
-            coords (dict, optional): Provide coordinates for the array explicitly, using a dictionary with dimensions as keys and as values either 1D or meshgrid arrays of coordinates. If coords are not provided, then dimensions a default range array will be used. If coordinates are provided, then the dimensions argument is ignored.
+            and only one flip angle and repetition time:
 
-        Raises:
-            ValueError: if dimensions and coordinates are both provided with incompatible dimensions.
+            >>> print(volume.FlipAngle, volume.RepetitionTime)
+            2.0 7.5
 
-        See also:
-            :func:`~ndarray`
+            and that the parent study now has two series:
 
-        Warning:
-            Currently this function assumes that the new array has the same shape as the current array. This will be generalised in an upcoming update - for now please look at the pipelines examples for saving different dimensions using the current interface. 
+            >>> 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.
 
-        Example:
-            Create a zero-filled array, describing 8 MRI slices each measured at 3 flip angles and 2 repetition times:
+        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. 
 
-            >>> coords = {
-            ...    'SliceLocation': np.arange(8),
-            ...    'FlipAngle': [2, 15, 30],
-            ...    'RepetitionTime': [2.5, 5.0],
-            ... }
-            >>> series = db.zeros((128,128,8,3,2), coords)
+        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.
 
-            Retrieve the array and check that it is populated with zeros:
+        Args:
+            dims (tuple, optional): Dimensions for the returned arrays. Defaults to ('InstanceNumber',).
 
-            >>> array = series.ndarray(dims=tuple(coords)) 
-            >>> print(np.mean(array))
-            0.0
+        Returns:
+            list: A list of slice groups (dictionaries), one for each slice group in the series.
 
-            Now overwrite the values with a new array of ones. Coordinates are not changed so only dimensions need to be specified:
+        Examples:
 
-            >>> ones = np.ones((128,128,8,3,2))
-            >>> series.set_ndarray(ones, dims=tuple(coords))
+            >>> series = db.ones((128,128,5,10))
+            >>> sgroups = series.slice_groups(dims=('SliceLocation', 'AcquisitionTime'))
 
-            Retrieve the array and check that it is now populated with ones:
+            Since there is only one slice group in the series, ``sgroups`` is a list with one element:
 
-            >>> array = series.ndarray(dims=tuple(coords)) 
-            >>> print(np.mean(array))
-            1.0
-        """
-        # TODO: Include a reshaping option!!!!
-        
-        # 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_properties(ndarray:np.ndarray, coords:{}, affine:np.ndarray, **kwargs)
-        # #
+            >>> print(len(sgroups))
+            1
 
-        # Lazy solution - first get the header information (slower than propagating explicitly but conceptually more convenient - can be rationalised later - pixel values can be set on the fly as the header is retrieved)
+            The array of the slice group is the entire volume of the series:
 
-        # If coordinates are provided, the dimensions are taken from that. Dimensions are not needed in this case but if they are set they need to be the same as those specified in the coordinates. Else an error is raised.
-        if coords is not None:
-            if dims != tuple(coords):
-                msg = 'Coordinates do not have the correct dimensions \n'
-                msg += 'Note: if coordinates are defined than the dimensions argument is ignored. Hence you can remove the dimensions argument in this call, or else make sure it matches up with the dimensions in coordinates.'
-                raise ValueError(msg)
-            else:
-                dims = tuple(coords)
-        _, headers = get_pixel_array(self, sortby=list(dims), first_volume=True, pixels_first=True)
-        set_pixel_array(self, array, source=headers, pixels_first=True, coords=coords)
+            >>> print(sgroups[0]['ndarray'].shape)
+            (128, 128, 5, 10)
 
+            And the affine of the series has not changed from the default (identity):
 
-    #
-    # Following APIs are obsolete and will be removed in future versions
-    #
+            >>> print(sgroups[0]['affine'])
+            [[1. 0. 0. 0.]
+             [0. 1. 0. 0.]
+             [0. 0. 1. 0.]
+             [0. 0. 0. 1.]]
 
+        """
+        
+        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)
+    
     def array(*args, **kwargs):
         return get_pixel_array(*args, **kwargs)
 
@@ -347,24 +1879,366 @@ 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_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 = {}
+        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()
 
+        # Update any other header data provided
+        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()
 
 
+# def slice_groups(series): # not yet in use
+#     slice_groups = []
+#     for orientation in series.ImageOrientationPatient:
+#         sg = series.instances(ImageOrientationPatient=orientation)
+#         slice_groups.append(sg)
+#     return slice_groups
 
-def slice_groups(series): # not yet in use
-    slice_groups = []
-    for orientation in series.ImageOrientationPatient:
-        sg = series.instances(ImageOrientationPatient=orientation)
-        slice_groups.append(sg)
-    return slice_groups
 
 def subseries(record, move=False, **kwargs):
-    """Extract subseries"""
     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:
@@ -374,6 +2248,7 @@ def subseries(record, move=False, **kwargs):
     # series.adopt(instances)
     return series
 
+
 def read_npy(record):
     # Not in use - loading of temporary numpy files
     file = record.manager.npy()
@@ -384,123 +2259,35 @@ def read_npy(record):
     return array
 
 
-def affine_matrix(series):
-    """Returns the affine matrix of a series.
-    
-    If the series consists of multiple slice groups with different 
-    image orientations, then a list of affine matrices is returned,
-    one for each slice orientation.
-    """
-    image_orientation = series.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 = series.instances(ImageOrientationPatient=dir)
-            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()
-        affine = _slice_group_affine_matrix(slice_group, image_orientation)
-        return affine, slice_group
-
-
-def _slice_group_affine_matrix(slice_group, image_orientation):
-    """Return the affine matrix of a slice group"""
-
-    # single slice
-    if len(slice_group) == 1:
-        return slice_group[0].affine_matrix
-    # multi slice
-    else:
-        pos = [s.ImagePositionPatient for s in slice_group]
-        # Find unique elements
-        pos = [x for i, x in enumerate(pos) if i==pos.index(x)]
-
-        # One slice location
-        if len(pos) == 1: 
-            return slice_group[0].affine_matrix
-        
-        # Slices with different locations
-        else:
-            return image_utils.affine_matrix_multislice(
-                image_orientation, pos,
-                slice_group[0].PixelSpacing)    # assume all the same pixel spacing
-
 
-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): 
-    """Pixel values of the object as an ndarray
-    
-    Args:
-        sortby: 
-            Optional list of DICOM keywords by which the volume is sorted
-        pixels_first: 
-            If True, the (x,y) dimensions are the first dimensions of the array.
-            If False, (x,y) are the last dimensions - this is the default.
-
-    Returns:
-        An ndarray holding the pixel data.
-
-        An ndarry holding the datasets (instances) of each slice.
-
-    Examples:
-        ``` ruby
-        # return a 3D array (z,x,y)
-        # with the pixel data for each slice
-        # in no particular order (z)
-        array, _ = series.array()    
-
-        # return a 3D array (x,y,z)   
-        # with pixel data in the leading indices                               
-        array, _ = series.array(pixels_first = True)    
-
-        # Return a 4D array (x,y,t,k) sorted by acquisition time   
-        # The last dimension (k) enumerates all slices with the same acquisition time. 
-        # If there is only one image for each acquision time, 
-        # the last dimension is a dimension of 1                               
-        array, data = series.array('AcquisitionTime', pixels_first=True)                         
-        v = array[:,:,10,0]                 # First image at the 10th location
-        t = data[10,0].AcquisitionTIme      # acquisition time of the same image
-
-        # Return a 4D array (loc, TI, x, y) 
-        sortby = ['SliceLocation','InversionTime']
-        array, data = series.array(sortby) 
-        v = array[10,6,0,:,:]            # First slice at 11th slice location and 7th inversion time    
-        Loc = data[10,6,0][sortby[0]]    # Slice location of the same slice
-        TI = data[10,6,0][sortby[1]]     # Inversion time of the same slice
-        ```  
-    """
-
+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):
@@ -529,112 +2316,19 @@ def _get_pixel_array_from_sorted_instance_array(source, pixels_first=False):
     return array, source 
 
 
-def set_pixel_array(series, array, source=None, pixels_first=False, coords=None, **kwargs): 
-    """
-    Set pixel values of a series from a numpy ndarray.
-
-    Since the pixel data do not hold any information about the 
-    image such as geometry, or other metainformation,
-    a dataset must be provided as well with the same 
-    shape as the array except for the slice dimensions. 
-
-    If a dataset is not provided, header info is 
-    derived from existing instances in order.
-
-    Args:
-        array: 
-            numpy ndarray with pixel data.
-
-        dataset: 
-            numpy ndarray
-
-            Instances holding the header information. 
-            This *must* have the same shape as array, minus the slice dimensions.
-
-        pixels_first: 
-            bool
-
-            Specifies whether the pixel dimensions are the first or last dimensions of the series.
-            If not provided it is assumed the slice dimensions are the last dimensions
-            of the array.
-
-        inplace: 
-            bool
-
-            If True (default) the current pixel values in the series 
-            are overwritten. If set to False, the new array is added to the series.
-    
-    Examples:
-        ```ruby
-        # Invert all images in a series:
-        array, _ = series.array()
-        series.set_array(-array)
-
-        # Create a maximum intensity projection of the series.
-        # Header information for the result is taken from the first image.
-        # Results are saved in a new sibling series.
-        array, data = series.array()
-        array = np.amax(array, axis=0)
-        data = np.squeeze(data[0,...])
-        series.new_sibling().set_array(array, data)
-
-        # Create a 2D maximum intensity projection along the SliceLocation direction.
-        # Header information for the result is taken from the first slice location.
-        # Current data of the series are overwritten.
-        array, data = series.array('SliceLocation')
-        array = np.amax(array, axis=0)
-        data = np.squeeze(data[0,...])
-        series.set_array(array, data)
-
-        # In a series with multiple slice locations and inversion times,
-        # replace all images for each slice location with that of the shortest inversion time.
-        array, data = series.array(['SliceLocation','InversionTime']) 
-        for loc in range(array.shape[0]):               # loop over slice locations
-            slice0 = np.squeeze(array[loc,0,0,:,:])     # get the slice with shortest TI 
-            TI0 = data[loc,0,0].InversionTime           # get the TI of that slice
-            for TI in range(array.shape[1]):            # loop over TIs
-                array[loc,TI,0,:,:] = slice0            # replace each slice with shortest TI
-                data[loc,TI,0].InversionTime = TI0      # replace each TI with shortest TI
-        series.set_array(array, data)
-        ```
-    """
+def set_pixel_array(series, array, source=None, pixels_first=False, **kwargs): 
 
     # Move pixels to the end (default)
     if pixels_first:    
         array = np.moveaxis(array, 0, -1)
         array = np.moveaxis(array, 0, -1)
 
-    # If source data are provided, then coordinates are optional. 
-    # If no source data are given, then coordinates MUST be defined to ensure array data can be retrieved in the proper order..
-    if source is None:
-        if coords is None:
-            if array.ndim > 4:
-                msg = 'For arrays with more than 4 dimensions, \n'
-                msg += 'either coordinate labels or headers must be provided'
-                raise ValueError(msg)
-            elif array.ndim == 4:
-                coords = {
-                    'SliceLocation':np.arange(array.shape[0]),
-                    'AcquisitionTime':np.arange(array.shape[1]),
-                }
-            elif array.ndim == 3:
-                coords = {
-                    'SliceLocation':np.arange(array.shape[0]),
-                }
-
-    # If coordinates are given as 1D arrays, turn them into grids and flatten for iteration.
-    if coords is not None:
-        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):
-                coords[c] = pos[i].ravel()
-
     # if no header data are provided, use template headers.
     nr_of_slices = int(np.prod(array.shape[:-2]))
     if source is None:
         source = [series.new_instance(MRImage()) for _ in range(nr_of_slices)]
+    if source.size == 0:
+        source = [series.new_instance(MRImage()) for _ in range(nr_of_slices)]
 
     # If the header data are not the same size, use only the first one.
     else:
@@ -670,40 +2364,67 @@ def set_pixel_array(series, array, source=None, pixels_first=False, coords=None,
     for i, image in enumerate(copy_source):
         series.progress(i+1, len(copy_source), 'Saving array..')
         image.read()
-
         for attr, vals in kwargs.items(): 
             if isinstance(vals, list):
                 setattr(image, attr, vals[i])
             else:
                 setattr(image, attr, vals)
-
-        # If coordinates are provided, these will override the values from the sources.
-        if coords is not None: # ADDED 31/05/2023
-            for c in coords:
-                image[c] = coords[c][i]
         image.set_pixel_array(array[i,...])
         image.clear()
 
 
+def affine_matrix(series):
+    """Returns the affine matrix of a series.
+    
+    If the series consists of multiple slice groups with different 
+    image orientations, then a list of affine matrices is returned,
+    one for each slice orientation.
+    """
+    image_orientation = series.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 = series.instances(ImageOrientationPatient=dir)
+            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()
+        affine = _slice_group_affine_matrix(slice_group, image_orientation)
+        return affine, slice_group
+    
 
-    # More compact but does not work with pause extensions
-    # for i, s in enumerate(source):
-    #     series.status.progress(i+1, len(source), 'Writing array..')
-    #     if s not in instances:
-    #         s.copy_to(series).set_pixel_array(array[i,...])
-    #     else:
-    #         s.set_pixel_array(array[i,...])
-
-
-
-
+def _slice_group_affine_matrix(slice_group, image_orientation):
+    """Return the affine matrix of a slice group"""
 
+    # single slice
+    if len(slice_group) == 1:
+        return slice_group[0].affine_matrix
+    # multi slice
+    else:
+        pos = [s.ImagePositionPatient for s in slice_group]
+        # Find unique elements
+        pos = [x for i, x in enumerate(pos) if i==pos.index(x)]
 
-##
-## Helper functions
-##
+        # One slice location
+        if len(pos) == 1: 
+            return slice_group[0].affine_matrix
+        
+        # Slices with different locations
+        else:
+            return image_utils.affine_matrix_multislice(
+                image_orientation, pos,
+                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:
@@ -711,10 +2432,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): 
+    # 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:
@@ -724,7 +2490,7 @@ def instance_array(record, sortby=None, status=True):
         An ndarray holding the instances sorted by sortby.
     """
     if sortby is None:
-        instances = record.instances()
+        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
@@ -732,34 +2498,44 @@ def instance_array(record, sortby=None, status=True):
     else:
         if not isinstance(sortby, list):
             sortby = [sortby]
-        df = record.read_dataframe(sortby + ['SOPInstanceUID'])
+        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
-        try: 
-            nan = np.isnan(c)
-        except: 
-            nan = False
-        if nan:
+        if c is None: # this happens when undefined keyword is used
             dfc = df[df[sortby[0]].isnull()]
         else:
-            dfc = df[df[sortby[0]] == c]
+            try: 
+                nan = np.isnan(c)
+            except: 
+                nan = False
+            if nan:
+                dfc = df[df[sortby[0]].isnull()]
+            else:
+                dfc = df[df[sortby[0]] == c]
         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)
 
@@ -784,9 +2560,10 @@ def _stack(arrays, align_left=False):
 
     # Get the dimensions of the stack
     # For each dimension, look for the largest values across all arrays
-    arrays = [a for a in arrays if a is not None]
+    #arrays = [a for a in arrays if a is not None]
+    arrays = [a for a in arrays if a.size != 0]
     if arrays == []:
-        return
+        return np.array([])
     ndim = len(arrays[0].shape)
     dim = [0] * ndim
     for array in arrays:
@@ -814,3 +2591,9 @@ def _stack(arrays, align_left=False):
 
     return stack
 
+
+
+
+
+
+