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

dbdicom/extensions/numpy.py

@@ -0,0 +1,271 @@
+"""
+``dbdicom`` extensions calling numpy functions. These do not require additional packages to be installed.
+"""
+
+import numpy as np
+import dbdicom as dbd
+
+
+def mean_intensity_projection(series:dbd.Series, dims=('SliceLocation','InstanceNumber'), axis=-1) -> dbd.Series:
+    """Create a mean intensity projection along a specified dimension.
+
+    Args:
+        series (dbdicom.Series): Original series.
+        dims (tuple, optional): Dimensions of the array. Defaults to ('SliceLocation','InstanceNumber').
+        axis (int, optional): axis along which the maximum is to be taken. Defaults to -1.
+        
+    Returns:
+        dbicom.Series: mean intensity projection. 
+
+    Example:
+
+        Get the MIP function from the numpy extension to dbdicom:
+
+        >>> from db.extensions.numpy import mean_intensity_projection
+
+        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)
+
+        Create a mean intensity projection on the slice locations and check the dimensions:
+
+        >>> mip = mean_intensity_projection(series)
+        >>> array = mip.pixel_values(dims=('SliceLocation', 'ImageNumber'))
+        >>> print(array.shape)
+        (128, 128, 8, 1)
+
+        Create a mean intensity projection along the Slice Location axis:
+
+        >>> mip = mean_intensity_projection(series, dims=tuple(coords), axis=0)
+        >>> array = mip.pixel_values(dims=tuple(coords))
+        >>> print(array.shape)
+        (128, 128, 1, 3, 2)
+
+        Create a mean intensity projection along the Flip Angle axis:
+
+        >>> mip = mean_intensity_projection(series, dims=tuple(coords), axis=1)
+        >>> array = mip.pixel_values(dims=tuple(coords))
+        >>> print(array.shape)
+        (128, 128, 8, 1, 2)
+
+        Create a mean intensity projection along the Repetition Time axis:
+
+        >>> mip = mean_intensity_projection(series, dims=tuple(coords), axis=2)
+        >>> array = mip.pixel_values(dims=tuple(coords))
+        >>> print(array.shape)
+        (128, 128, 8, 3, 1)
+    """
+    array = series.pixel_values(dims=dims)
+    array = np.mean(array, axis=axis)
+
+    # Save as DICOM
+    proj = series.new_sibling(SeriesDescription = series.SeriesDescription + '[mean axis ' + str(axis) + ']')
+    frames = series.frames(dims)
+    frames = np.take(frames, 0, axis=axis)
+    frames = frames.ravel()
+    array = array.reshape((array.shape[0], array.shape[1], -1))
+    for z in range(frames.size):
+        series.progress(z+1, frames.size, 'Saving results.. ')
+        frames_z = frames[z].copy_to(proj)
+        frames_z.set_pixel_values(array[:,:,z])
+
+    return proj
+
+
+def maximum_intensity_projection(series:dbd.Series, dims=('SliceLocation','InstanceNumber'), axis=-1) -> dbd.Series:
+    """Create a maximum intensity projection along a specified dimension.
+
+    Args:
+        series (dbdicom.Series): Original series.
+        dims (tuple, optional): Dimensions of the array. Defaults to ('SliceLocation','InstanceNumber').
+        axis (int, optional): axis along which the maximum is to be taken. Defaults to -1.
+        
+    Returns:
+        dbicom.Series: maximum intensity projection. 
+
+    Example:
+
+        Get the MIP function from the numpy extension to dbdicom:
+
+        >>> from db.extensions.numpy import maximum_intensity_projection
+
+        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)
+
+        Create a maximum intensity projection on the slice locations and check the dimensions:
+
+        >>> mip = maximum_intensity_projection(series)
+        >>> array = mip.pixel_values(dims=('SliceLocation', 'ImageNumber'))
+        >>> print(array.shape)
+        (128, 128, 8, 1)
+
+        Create a maximum intensity projection along the Slice Location axis:
+
+        >>> mip = maximum_intensity_projection(series, dims=tuple(coords), axis=0)
+        >>> array = mip.pixel_values(dims=tuple(coords))
+        >>> print(array.shape)
+        (128, 128, 1, 3, 2)
+
+        Create a maximum intensity projection along the Flip Angle axis:
+
+        >>> mip = maximum_intensity_projection(series, dims=tuple(coords), axis=1)
+        >>> array = mip.pixel_values(dims=tuple(coords))
+        >>> print(array.shape)
+        (128, 128, 8, 1, 2)
+
+        Create a maximum intensity projection along the Repetition Time axis:
+
+        >>> mip = maximum_intensity_projection(series, dims=tuple(coords), axis=2)
+        >>> array = mip.pixel_values(dims=tuple(coords))
+        >>> print(array.shape)
+        (128, 128, 8, 3, 1)
+    """
+
+    array = series.pixel_values(dims=dims)
+    array = np.amax(array, axis=axis)
+
+    # Save as DICOM
+    proj = series.new_sibling(SeriesDescription = series.SeriesDescription + '[max axis ' + str(axis) + ']')
+    frames = series.frames(dims)
+    frames = np.take(frames, 0, axis=axis)
+    frames = frames.ravel()
+    array = array.reshape((array.shape[0], array.shape[1], -1))
+    for z in range(frames.size):
+        series.progress(z+1, frames.size, 'Saving results.. ')
+        frames_z = frames[z].copy_to(proj)
+        frames_z.set_pixel_values(array[:,:,z])
+
+    return proj
+
+
+def norm_projection(series:dbd.Series, dims=('SliceLocation','InstanceNumber'), axis=-1, ord=None) -> dbd.Series:
+    """Projection along a specified dimension using the vector norm.
+
+    This functions uses numpy.linalg.norm to calculate the projection, see: https://numpy.org/doc/stable/reference/generated/numpy.linalg.norm.html
+
+    Args:
+        series (dbdicom.Series): Original series.
+        dims (tuple, optional): Dimensions of the array. Defaults to ('SliceLocation','InstanceNumber').
+        axis (int, optional): axis along which the maximum is to be taken. Defaults to -1.
+        ord (int, optional): order of the norm - see documentation of numpy.linalg.norm for details
+        
+    Returns:
+        dbicom.Series: maximum intensity projection. 
+
+    Example:
+
+        Get the function from the numpy extension to dbdicom:
+
+        >>> from db.extensions.numpy import norm_projection
+
+        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)
+
+        Create a norm projection on the slice locations and check the dimensions:
+
+        >>> mip = norm_projection(series)
+        >>> array = mip.pixel_values(dims=('SliceLocation', 'ImageNumber'))
+        >>> print(array.shape)
+        (128, 128, 8, 1)
+
+        Create a norm projection along the Slice Location axis:
+
+        >>> mip = norm_projection(series, dims=tuple(coords), axis=0)
+        >>> array = mip.pixel_values(dims=tuple(coords))
+        >>> print(array.shape)
+        (128, 128, 1, 3, 2)
+
+        Create a norm projection along the Flip Angle axis:
+
+        >>> mip = norm_projection(series, dims=tuple(coords), axis=1)
+        >>> array = mip.pixel_values(dims=tuple(coords))
+        >>> print(array.shape)
+        (128, 128, 8, 1, 2)
+
+        Create a norm projection along the Repetition Time axis:
+
+        >>> mip = norm_projection(series, dims=tuple(coords), axis=2)
+        >>> array = mip.pixel_values(dims=tuple(coords))
+        >>> print(array.shape)
+        (128, 128, 8, 3, 1)
+    """
+    array = series.pixel_values(dims=dims)
+    array = np.linalg.norm(array, ord=ord, axis=axis)
+
+    # Save as DICOM
+    proj = series.new_sibling(SeriesDescription = series.SeriesDescription + '[norm axis ' + str(axis) + ']')
+    frames = series.frames(dims)
+    frames = np.take(frames, 0, axis=axis)
+    frames = frames.ravel()
+    array = array.reshape((array.shape[0], array.shape[1], -1))
+    for z in range(frames.size):
+        series.progress(z+1, frames.size, 'Saving results.. ')
+        frames_z = frames[z].copy_to(proj)
+        frames_z.set_pixel_values(array[:,:,z])
+
+    return proj
+    
+
+
+def threshold(input:dbd.Series, low_threshold=0, high_threshold=1, method='absolute')-> dbd.Series:
+    """Create a mask series by thresholding.
+
+    Args:
+        input (dbd.Series): original data to be masked
+        low_threshold (int, optional): Lower threshold for masking. Defaults to 0.
+        high_threshold (int, optional): Upper threshold for masking. Defaults to 1.
+        method (str, optional): Type of thresholding, either 'absolute' (thresholds are absolute signal values), 'quantiles' (thresholds are quantiles), or 'range' (thresholds are between 0 and 1). Defaults to 'absolute'.
+
+    Returns:
+        dbd.Series: mask series with values = 1 inside and 0 outside.
+    """
+    suffix = ' [Threshold segmentation]'
+    desc = input.instance().SeriesDescription
+    filtered = input.copy(SeriesDescription = desc+suffix)
+    #images = filtered.instances()
+    images = filtered.images()
+    for i, image in enumerate(images):
+        input.status.progress(i+1, len(images), 'Filtering ' + desc)
+        image.read()
+        array = image.array()
+        if method == 'quantiles':
+            range = np.quantile(array, [low_threshold, high_threshold])
+        elif method == 'range':
+            min, max = np.amin(array), np.amax(array)
+            range = [min+low_threshold*(max-min), min+high_threshold*(max-min)]
+        else:
+            range = [low_threshold, high_threshold]
+        array = np.logical_and(array > range[0],  array < range[1])
+        image.set_array(array)
+        array = array.astype(np.ubyte)
+        _reset_window(image, array)
+        image.clear()
+    input.status.hide()
+    return filtered
+
+
+
+# Helper functions
+
+def _reset_window(image, array):
+    min = np.amin(array)
+    max = np.amax(array)
+    image.WindowCenter= (max+min)/2
+    image.WindowWidth = 0.9*(max-min)

dbdicom/{wrappers → extensions}/scipy.py

@@ -7,6 +7,7 @@ from dbdicom.utils.image import multislice_affine_transform
 
 
 
+# OBSOLETE - replaced by vreg._equal_geometry
 def _equal_geometry(affine1, affine2):
     # Check if both are the same, 
     # ignoring the order in the list
@@ -34,6 +35,7 @@ def _equal_geometry(affine1, affine2):
 
 
 # Better use set(tuple())
+# OBSOLETE - unused
 def _lists_have_equal_items(list1, list2):
     # Convert the lists to sets
     set1 = set([tuple(x) for x in list1])
@@ -101,7 +103,7 @@ def _mask_curve_3d_data(msk_arr, img_hdrs, ids, dim):
     data = []
     nt = msk_arr[0].shape[-1]
     for t in range(nt):
-        img_hdrs[0][0,0].status.progress(t+1, nt, 'Extracting mask time curves..')
+        img_hdrs[0][0,0].progress(t+1, nt, 'Extracting mask time curves..')
         # Concatenate data at time t for each slice group
         arr = [_mask_data(arr_i[...,t], img_hdrs[i][...,t]) for i, arr_i in enumerate(msk_arr)]
         arr = [d for d in arr if d is not None]
@@ -120,7 +122,7 @@ def _mask_curve_3d_data(msk_arr, img_hdrs, ids, dim):
         data.append(ids + vals)
     return data
 
-
+# OBSOLETE to vreg
 def mask_statistics(masks, images):
     if not isinstance(masks, list):
         masks = [masks]
@@ -141,7 +143,7 @@ def mask_statistics(masks, images):
             df_all_masks = pd.concat([df_all_masks, df_mask], ignore_index=True)
     return df_all_masks
 
-
+# OBSOLETE to vreg
 def _mask_statistics(mask, image):
 
     # Get mask array
@@ -157,7 +159,7 @@ def _mask_statistics(mask, image):
         data.append(row)
     return pd.DataFrame(data, columns=columns)
 
-
+# OBSOLETE to vreg
 def _mask_data_slice_groups(msk_arr, img_hdrs):
     if isinstance(msk_arr, list): 
         # Loop over slice groups
@@ -172,7 +174,7 @@ def _mask_data_slice_groups(msk_arr, img_hdrs):
         data = _mask_data(msk_arr, img_hdrs)
     return data
 
-
+# OBSOLETE to vreg
 def _mask_data(msk_arr, imgs):
     data = []
     for i, image in np.ndenumerate(imgs):
@@ -190,7 +192,7 @@ def _mask_data(msk_arr, imgs):
     else:
         return np.concatenate(data)
     
-
+# OBSOLETE to vreg
 def _summary_stats(data):
     if data is None:
         return {}
@@ -217,7 +219,7 @@ def _summary_stats(data):
         'Skewness': scipy.stats.skew(data),
     }
         
-
+# Obsolete - moved to vreg
 def array(series, on=None, **kwargs):
     """Return the array overlaid on another series"""
 
@@ -242,7 +244,7 @@ def overlay(features):
         mapped_features.append(mapped)
     return mapped_features
     
-
+# OBSOLETE - see vreg
 def map_to(source, target, **kwargs):
     """Map non-zero pixels onto another series"""
 
@@ -273,16 +275,67 @@ def map_to(source, target, **kwargs):
 def _map_series_to_slice_group(source, target, affine_source, affine_target, **kwargs):
 
     if isinstance(affine_source, list):
-        mapped_series = []
+        array_target, headers_target = target.array(['SliceLocation','AcquisitionTime'], pixels_first=True)
+        array = None
         for affine_slice_group in affine_source:
             slice_group_source = source.new_sibling()
             slice_group_source.adopt(affine_slice_group[1])
-            mapped = _map_slice_group_to_slice_group(slice_group_source, affine_slice_group[0], target, affine_target, **kwargs)
-            mapped_series.append(mapped)
+            array_sg, weight_sg = _map_slice_group_to_slice_group_array(slice_group_source, affine_slice_group[0], target, affine_target, array_target.shape[:3], **kwargs)
             slice_group_source.remove()
-        return dbdicom.merge(mapped_series, inplace=True)
+            if array is None:
+                array = array_sg
+                weight = weight_sg
+            else:
+                array += weight_sg*array_sg
+                weight += weight_sg   
+        nozero = np.where(weight > 0)
+        array[nozero] = array[nozero]/weight[nozero]
+
+        # Create new series
+        mapped_series = source.new_sibling(suffix='overlay')
+        ns, nt, nk = array.shape[2], array.shape[3], array.shape[4]
+        cnt=0
+        for t in range(nt):
+            for k in range(nk):
+                for s in range(ns):
+                    cnt+=1
+                    source.progress(cnt, ns*nt*nk, 'Saving results..')
+                    image = headers_target[s,0,0].copy_to(mapped_series)
+                    image.AcquisitionTime = t
+                    image.set_array(array[:,:,s,t,k])
+        return mapped_series
     else:
         return _map_slice_group_to_slice_group(source, affine_source[0], target, affine_target, **kwargs)
+    
+
+def _map_slice_group_to_slice_group_array(source, affine_source, target, output_affine, target_shape, **kwargs):
+
+    # Get source arrays
+    array_source, headers_source = source.array(['SliceLocation','AcquisitionTime'], pixels_first=True)
+    
+    # Get message status updates
+    source_desc = source.instance().SeriesDescription
+    target_desc = target.instance().SeriesDescription
+    message = 'Mapping ' + source_desc + ' onto ' + target_desc
+    source.message(message)
+
+    array_mapped = multislice_affine_transform(
+        array_source, 
+        affine_source, 
+        output_affine, 
+        output_shape = target_shape, 
+        slice_thickness = headers_source[0,0,0].SliceThickness, 
+        **kwargs,
+    )
+    weights_mapped = multislice_affine_transform(
+        np.ones(array_source.shape), 
+        affine_source, 
+        output_affine, 
+        output_shape = target_shape, 
+        slice_thickness = headers_source[0,0,0].SliceThickness, 
+        **kwargs,
+    )
+    return array_mapped, weights_mapped
 
 
 def _map_slice_group_to_slice_group(source, affine_source, target, output_affine, **kwargs):
@@ -306,19 +359,13 @@ def _map_slice_group_to_slice_group(source, affine_source, target, output_affine
         **kwargs,
     )
 
-    # TODO
-    # Preserve source window settings and set the same in result
-    # 
-
+    # Create new series
     # Retain source acquisition times
     # Assign acquisition time of slice=0 to all slices
-    nt = headers_source.shape[1]
-    acq_times = [headers_source[0,t,0].AcquisitionTime for t in range(nt)]
-
-    # Create new series
     mapped_series = source.new_sibling(suffix='overlay')
     nt, nk = array_source.shape[3], array_source.shape[4]
     ns = headers_target.shape[0] 
+    acq_times = [headers_source[0,t,0].AcquisitionTime for t in range(nt)]
     cnt=0
     for t in range(nt):
         for k in range(nk):
@@ -331,7 +378,7 @@ def _map_slice_group_to_slice_group(source, affine_source, target, output_affine
     return mapped_series
 
 
-
+# OBSOLETE - see vreg
 def mask_array(mask, on=None, dim='InstanceNumber'):
     """Map non-zero pixels onto another series"""
 
@@ -1009,6 +1056,29 @@ def uniform_filter(input, size=3, **kwargs):
         image.clear()
     input.status.hide()
     return filtered
+
+
+#https://docs.scipy.org/doc/scipy/reference/generated/scipy.ndimage.uniform_filter.html#scipy.ndimage.uniform_filter
+# This has a bug it seems
+def uniform_filter_3d(input, size=3, **kwargs):
+    """
+    wrapper for scipy.ndimage.uniform_filter.
+
+    Parameters
+    ----------
+    input: dbdicom series
+
+    Returns
+    -------
+    filtered : dbdicom series
+    """
+    array, headers = input.array(sortby='SliceLocation', pixels_first=True, first_volume=True)
+    input.message('Computing uniform filter..')
+    array = scipy.ndimage.uniform_filter(array, size=size, **kwargs)
+    suffix = ' [Uniform Filter x ' + str(size) + ']'
+    output = input.new_sibling(suffix=suffix)
+    output.set_array(array, headers, pixels_first=True)
+    return output
     
 
 # https://docs.scipy.org/doc/scipy/reference/generated/scipy.ndimage.gaussian_filter.html#scipy.ndimage.gaussian_filter
@@ -1043,6 +1113,28 @@ def gaussian_filter(input, sigma, **kwargs):
     return filtered
 
 
+# https://docs.scipy.org/doc/scipy/reference/generated/scipy.ndimage.gaussian_filter.html#scipy.ndimage.gaussian_filter
+def gaussian_filter_3d(input, sigma, **kwargs):
+    """
+    wrapper for scipy.ndimage.gaussian_filter.
+
+    Parameters
+    ----------
+    input: dbdicom series
+
+    Returns
+    -------
+    filtered : dbdicom series
+    """
+    suffix = ' [Gaussian Filter x ' + str(sigma) + ' ]'
+    array, headers = input.array(sortby='SliceLocation', pixels_first=True, first_volume=True)
+    input.message('Computing Gaussian filter..')
+    array = scipy.ndimage.gaussian_filter(array, sigma, **kwargs)
+    output = input.new_sibling(suffix=suffix)
+    output.set_array(array, headers, pixels_first=True)
+    return output
+
+
 # https://docs.scipy.org/doc/scipy/reference/generated/scipy.ndimage.fourier_shift.html#scipy.ndimage.fourier_shift
 def fourier_shift(input, shift, **kwargs):
     """
@@ -1080,13 +1172,13 @@ def fourier_shift(input, shift, **kwargs):
 
 
 
-def series_calculator(series, operation='1 - series'):
+def series_calculator(series, operation='1 - series', param=None):
 
     desc = series.instance().SeriesDescription
     result = series.copy(SeriesDescription = desc + ' [' + operation + ']')
     images = result.images()
     for i, img in enumerate(images):
-        series.status.progress(i+1, len(images), 'Calculating..')
+        series.progress(i+1, len(images), 'Calculating..')
         img.read()
         array = img.array()
         if operation == '1 - series':
@@ -1101,6 +1193,10 @@ def series_calculator(series, operation='1 - series'):
             array = np.exp(array)
         elif operation == 'integer(series)':
             array = np.around(array)
+        elif operation == 'abs(series)':
+            array = np.abs(array)
+        elif operation == 'a * series':
+            array = array*param
         array[~np.isfinite(array)] = 0
         img.set_array(array)
         _reset_window(img, array)
@@ -1109,7 +1205,7 @@ def series_calculator(series, operation='1 - series'):
     return result
 
 
-def image_calculator(series1, series2, operation='series 1 - series 2', integer=False):
+def image_calculator(series1, series2, operation='series 1 - series 2', integer=False, series_desc=None):
 
     result = map_to(series2, series1)
     if result == series2: # same geometry
@@ -1124,22 +1220,22 @@ def image_calculator(series1, series2, operation='series 1 - series 2', integer=
         img2.read()
         array1 = img1.array()
         array2 = img2.array()
-        if operation == 'series 1 + series 2':
+        if operation in ['series 1 + series 2', '+', 'sum']:
             array = array1 + array2
             desc = ' [add]'
-        elif operation == 'series 1 - series 2':
+        elif operation in ['series 1 - series 2', '-', 'diff']:
             array = array1 - array2
             desc = ' [difference]'
-        elif operation == 'series 1 / series 2':
+        elif operation in ['series 1 / series 2', '/', 'div']:
             array = array1 / array2
             desc = ' [divide]'
-        elif operation == 'series 1 * series 2':
+        elif operation in ['series 1 * series 2', '*', 'mult']:
             array = array1 * array2
             desc = ' [multiply]'
-        elif operation == '(series 1 - series 2)/series 2':
+        elif operation in ['(series 1 - series 2)/series 2', 'rdiff']:
             array = (array1 - array2)/array2
             desc = ' [relative difference]'
-        elif operation == 'average(series 1, series 2)':
+        elif operation in ['average(series 1, series 2)', 'avr', 'mean']:
             array = (array1 + array2)/2
             desc = ' [average]'
         array[~np.isfinite(array)] = 0
@@ -1148,7 +1244,10 @@ def image_calculator(series1, series2, operation='series 1 - series 2', integer=
         img2.set_array(array)
         _reset_window(img2, array.astype(np.ubyte))
         img2.clear()
-    result.SeriesDescription = result.instance().SeriesDescription + desc
+    if series_desc is None:
+        result.SeriesDescription = result.instance().SeriesDescription + desc
+    else:
+        result.SeriesDescription = series_desc
     return result
 
 

dbdicom/{wrappers → extensions}/skimage.py

@@ -3,7 +3,7 @@ import pandas as pd
 import scipy.ndimage as ndi
 import skimage
 
-from dbdicom.wrappers import scipy
+from dbdicom.extensions import scipy
 from dbdicom.utils.image import interpolate3d_isotropic