Merge pull request #27 from mrphys/develop

Release 0.20.0

.gitignore

@@ -5,6 +5,7 @@
 .ipynb_checkpoints/
 __pycache__/
 artifacts/
+build/
 third_party/spiral_waveform
 tools/docs/_build
 tools/docs/_templates

README.rst

@@ -76,9 +76,9 @@ TensorFlow MRI contains operators for:
   etc.
 * Signal processing
   (`tfmri.signal <https://mrphys.github.io/tensorflow-mri/api_docs/tfmri/signal>`_):
-  N-dimensional FFT, non-uniform FFT
+  N-dimensional fast Fourier transform (FFT), non-uniform FFT (NUFFT)
   (see also `TensorFlow NUFFT <https://github.com/mrphys/tensorflow-nufft>`_),
-  *k*-space filtering, etc.
+  discrete wavelet transform (DWT), *k*-space filtering, etc.
 * Unconstrained optimization
   (`tfmri.optimize <https://mrphys.github.io/tensorflow-mri/api_docs/tfmri/optimize>`_):
   gradient descent, L-BFGS.

RELEASE.rst

@@ -1,71 +1,34 @@
-Release 0.19.0
+Release 0.20.0
 ==============
 
-This release bumps the supported TensorFlow version to 2.9.
-
 Major Features and Improvements
 -------------------------------
 
-* ``tfmri.image``:
-
-  * Added new arguments ``batch_dims`` and ``image_dims`` to
-    ``image_gradients``, ``gradient_magnitude``, ``psnr``, ``ssim`` and
-    ``ssim_multiscale``.
-  * Argument ``rank`` of ``psnr``, ``ssim`` and ``ssim_multiscale`` is now
-    deprecated. To update, use ``image_dims`` instead.
-  * ``image_gradients`` and ``gradient_magnitude`` now support complex inputs.
-
-* ``tfmri.losses``:
+* ``tfmri.layers``:
 
-  * Added new arguments ``batch_dims`` and ``image_dims`` to all image quality
-    losses. Argument ``rank`` is now deprecated (use ``image_dims`` instead).
-  * Added new arguments ``multichannel`` and ``complex_part`` to all image
-    quality losses. These mirror the behaviour of the corresponding metrics
-    and allows for single-channel inputs and extraction of parts from complex
-    numbers, respectively. 
-  * The canonical API names ``StructuralSimilarityLoss`` and
-    ``MultiscaleStructuralSimilarityLoss`` have been
-    changed to ``SSIMLoss`` and ``SSIMMultiscaleLoss``, respectively. The
-    old names are still available, but may be removed in the future.
+  * Added new layers ``MaxPooling1D``, ``MaxPooling2D``, ``MaxPooling3D``,
+    ``AveragePooling1D``, ``AveragePooling2D`` and ``AveragePooling3D``.
+    These are drop-in replacements for the core Keras layers of the same name,
+    but they also support complex values.
+  * Added new layers ``DWT1D``, ``DWT2D``, ``DWT3D``, ``IDWT1D``, ``IDWT2D``,
+    and ``IDWT3D`` to compute 1D, 2D and 3D forward and inverse discrete wavelet
+    transforms.
+  * Layer ``ConvBlock`` is now deprecated in favor of the new endpoints in
+    the ``tfmri.models`` submodule.
+  * Layer ``UNet`` is now deprecated in favor of the new endpoints in
+    the ``tfmri.models`` submodule.
 
-* ``tfmri.metrics``:
+* ``tfmri.models``:
 
-  * Image quality metrics can now accept complex inputs without also specifying
-    ``complex_part``, in which case the unmodified complex values will be passed
-    to the downstream function. This may not be supported for all metrics.
-  * Added new arguments ``batch_dims`` and ``image_dims`` to all image quality
-    metrics. Argument ``rank`` is now deprecated (use ``image_dims`` instead).
-  * The canonical API names ``PeakSignalToNoiseRatio``,
-    ``StructuralSimilarity`` and ``MultiscaleStructuralSimilarity`` have been
-    changed to ``PSNR``, ``SSIM`` and ``SSIMMultiscale``, respectively. The
-    old names are still available, but may be removed in the future.
+  * Added new models ``ConvBlock1D``, ``ConvBlock2D`` and ``ConvBlock3D``. These
+    replace the previous ``ConvBlock`` layer, which is now deprecated.
+  * Added new models ``UNet1D``, ``UNet2D`` and ``UNet3D``. These replace
+    the previous ``UNet`` layer, which is now deprecated.
 
-* ``tfmri.recon``:
-
-  * Added new argument ``preserve_phase`` to ``tfmri.recon.pf``. This allows
-    the user to recover the phase as well as the magnitude during partial
-    Fourier reconstruction. Argument ``return_complex`` has the same behaviour
-    and is now deprecated.
-  * Added new aliases ``adjoint`` (for ``adj``), ``least_squares``
-    (for ``lstsq``) and ``partial_fourier`` (for ``pf``). These are now the
-    canonical aliases, but the old ones will still be supported.
-
-* ``tfmri.signal``:
-
-  * Added new ops ``dwt`` and ``idwt`` to compute the N-dimensional discrete
-    wavelet transform and its inverse, respectively.
-
-* ``tfmri.plot``:
-
-  * Added new argument ``norm`` to ``image_sequence``, ``tiled_image`` and
-    ``tiled_image_sequence``. This allows the user to specify the scaling
-    to be applied before the colormap.
 
 Bug Fixes and Other Changes
 ---------------------------
 
-* Fixed a bug with *k*-space weighting in homodyne detection method of
-  ``tfmri.recon.partial_fourier``. 
-* Like core TensorFlow, we now compile with ``_GLIBCXX_USE_CXX11_ABI=1``.
-* Like core TensorFlow, Python wheels now conform to ``manylinux2014``, an
-  upgrade from ``manylinux2010``.
+* ``tfmri.signal``:
+
+  * Improved static shape inference for ``dwt`` op.

tensorflow_mri/__about__.py

@@ -29,7 +29,7 @@
 __summary__ = "A collection of TensorFlow add-ons for computational MRI."
 __uri__ = "https://github.com/mrphys/tensorflow-mri"
 
-__version__ = "0.19.0"
+__version__ = "0.20.0"
 
 __author__ = "Javier Montalt Tordera"
 __email__ = "[email protected]"

tensorflow_mri/__init__.py

@@ -29,11 +29,12 @@
 from tensorflow_mri._api import image
 from tensorflow_mri._api import initializers
 from tensorflow_mri._api import io
-from tensorflow_mri._api import math
 from tensorflow_mri._api import layers
 from tensorflow_mri._api import linalg
 from tensorflow_mri._api import losses
+from tensorflow_mri._api import math
 from tensorflow_mri._api import metrics
+from tensorflow_mri._api import models
 from tensorflow_mri._api import optimize
 from tensorflow_mri._api import plot
 from tensorflow_mri._api import recon

tensorflow_mri/_api/layers/__init__.py

@@ -3,7 +3,28 @@
 """Keras layers."""
 
 from tensorflow_mri.python.layers.convolutional import Conv1D as Conv1D
+from tensorflow_mri.python.layers.convolutional import Conv1D as Convolution1D
 from tensorflow_mri.python.layers.convolutional import Conv2D as Conv2D
+from tensorflow_mri.python.layers.convolutional import Conv2D as Convolution2D
 from tensorflow_mri.python.layers.convolutional import Conv3D as Conv3D
+from tensorflow_mri.python.layers.convolutional import Conv3D as Convolution3D
 from tensorflow_mri.python.layers.conv_blocks import ConvBlock as ConvBlock
 from tensorflow_mri.python.layers.conv_endec import UNet as UNet
+from tensorflow_mri.python.layers.pooling import AveragePooling1D as AveragePooling1D
+from tensorflow_mri.python.layers.pooling import AveragePooling1D as AvgPool1D
+from tensorflow_mri.python.layers.pooling import AveragePooling2D as AveragePooling2D
+from tensorflow_mri.python.layers.pooling import AveragePooling2D as AvgPool2D
+from tensorflow_mri.python.layers.pooling import AveragePooling3D as AveragePooling3D
+from tensorflow_mri.python.layers.pooling import AveragePooling3D as AvgPool3D
+from tensorflow_mri.python.layers.pooling import MaxPooling1D as MaxPooling1D
+from tensorflow_mri.python.layers.pooling import MaxPooling1D as MaxPool1D
+from tensorflow_mri.python.layers.pooling import MaxPooling2D as MaxPooling2D
+from tensorflow_mri.python.layers.pooling import MaxPooling2D as MaxPool2D
+from tensorflow_mri.python.layers.pooling import MaxPooling3D as MaxPooling3D
+from tensorflow_mri.python.layers.pooling import MaxPooling3D as MaxPool3D
+from tensorflow_mri.python.layers.signal_layers import DWT1D as DWT1D
+from tensorflow_mri.python.layers.signal_layers import DWT2D as DWT2D
+from tensorflow_mri.python.layers.signal_layers import DWT3D as DWT3D
+from tensorflow_mri.python.layers.signal_layers import IDWT1D as IDWT1D
+from tensorflow_mri.python.layers.signal_layers import IDWT2D as IDWT2D
+from tensorflow_mri.python.layers.signal_layers import IDWT3D as IDWT3D

tensorflow_mri/_api/models/__init__.py

@@ -0,0 +1,10 @@
+# This file was automatically generated by tools/build/create_api.py.
+# Do not edit.
+"""Keras models."""
+
+from tensorflow_mri.python.models.conv_blocks import ConvBlock1D as ConvBlock1D
+from tensorflow_mri.python.models.conv_blocks import ConvBlock2D as ConvBlock2D
+from tensorflow_mri.python.models.conv_blocks import ConvBlock3D as ConvBlock3D
+from tensorflow_mri.python.models.conv_endec import UNet1D as UNet1D
+from tensorflow_mri.python.models.conv_endec import UNet2D as UNet2D
+from tensorflow_mri.python.models.conv_endec import UNet3D as UNet3D

tensorflow_mri/python/__init__.py

@@ -20,6 +20,7 @@
 from tensorflow_mri.python import layers
 from tensorflow_mri.python import losses
 from tensorflow_mri.python import metrics
+from tensorflow_mri.python import models
 from tensorflow_mri.python import ops
 from tensorflow_mri.python import summary
 from tensorflow_mri.python import util

tensorflow_mri/python/layers/__init__.py

@@ -17,4 +17,6 @@
 from tensorflow_mri.python.layers import convolutional
 from tensorflow_mri.python.layers import conv_blocks
 from tensorflow_mri.python.layers import conv_endec
+from tensorflow_mri.python.layers import pooling
 from tensorflow_mri.python.layers import preproc_layers
+from tensorflow_mri.python.layers import signal_layers

tensorflow_mri/python/layers/conv_blocks.py

@@ -34,12 +34,16 @@
 import tensorflow as tf
 
 from tensorflow_mri.python.util import api_util
+from tensorflow_mri.python.util import deprecation
 from tensorflow_mri.python.util import check_util
 from tensorflow_mri.python.util import layer_util
 
 
 @api_util.export("layers.ConvBlock")
 @tf.keras.utils.register_keras_serializable(package='MRI')
+@deprecation.deprecated(
+    date=deprecation.REMOVAL_DATE['0.20.0'],
+    instructions='Use `tfmri.models.ConvBlockND` instead.')
 class ConvBlock(tf.keras.layers.Layer):
   """A basic convolution block.
 

tensorflow_mri/python/layers/conv_endec.py

@@ -19,11 +19,15 @@
 from tensorflow_mri.python.layers import conv_blocks
 from tensorflow_mri.python.util import api_util
 from tensorflow_mri.python.util import check_util
+from tensorflow_mri.python.util import deprecation
 from tensorflow_mri.python.util import layer_util
 
 
 @api_util.export("layers.UNet")
 @tf.keras.utils.register_keras_serializable(package='MRI')
+@deprecation.deprecated(
+    date=deprecation.REMOVAL_DATE['0.20.0'],
+    instructions='Use `tfmri.models.UNetND` instead.')
 class UNet(tf.keras.layers.Layer):
   """A UNet layer.
 

tensorflow_mri/python/layers/convolutional.py

@@ -118,16 +118,16 @@ def convolution_op(self, inputs, kernel):
 #  2. `register_keras_serializable`: Registers the new layer with the Keras
 #     serialization framework.
 #  3. `export`: Exports the new layer to the TFMRI API.
-Conv1D = api_util.export("layers.Conv1D")(
+Conv1D = api_util.export("layers.Conv1D", "layers.Convolution1D")(
     tf.keras.utils.register_keras_serializable(package='MRI')(
     complex_conv(tf.keras.layers.Conv1D)))
 
 
-Conv2D = api_util.export("layers.Conv2D")(
+Conv2D = api_util.export("layers.Conv2D", "layers.Convolution2D")(
     tf.keras.utils.register_keras_serializable(package='MRI')(
     complex_conv(tf.keras.layers.Conv2D)))
 
 
-Conv3D = api_util.export("layers.Conv3D")(
+Conv3D = api_util.export("layers.Conv3D", "layers.Convolution3D")(
     tf.keras.utils.register_keras_serializable(package='MRI')(
     complex_conv(tf.keras.layers.Conv3D)))