deploy: phasorpy/phasorpy@3d0e71c

Author: cgohlke

docs/main/_downloads/08259e68fc838871e73e49dc5a3a2eb1/phasorpy_cursor.ipynb

@@ -29,7 +29,7 @@
       "cell_type": "markdown",
       "metadata": {},
       "source": [
-        "Open a hyperspectral dataset used throughout this tutorial:\n\n"
+        "Load a hyperspectral dataset used throughout this tutorial:\n\n"
       ]
     },
     {
@@ -47,7 +47,7 @@
       "cell_type": "markdown",
       "metadata": {},
       "source": [
-        "## Circular cursors\n\nUse circular cursors to mask regions of interest in the phasor space:\n\n"
+        "## Circular cursors\n\nUse circular cursors to mask regions of interest in the phasor space.\nDefine two cursors by specifying their real and imaginary coordinates\nand radii:\n\n"
       ]
     },
     {
@@ -83,7 +83,7 @@
       "cell_type": "markdown",
       "metadata": {},
       "source": [
-        "The cursor masks can be blended to produce a pseudo-colored image:\n\n"
+        "The cursor masks can be blended to produce a pseudo-colored image.\nEach cursor's region is assigned a different color:\n\n"
       ]
     },
     {
@@ -101,7 +101,14 @@
       "cell_type": "markdown",
       "metadata": {},
       "source": [
-        "## Elliptic cursors\n\nUse elliptic cursors to mask more defined regions of interest in the\nphasor space:\n\n"
+        "The pseudo-color image is numpy array with values between 0 and 1 (RGB)\nthat can be further processed or saved as needed.\n\n"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "## Elliptical cursors\n\nUse elliptical cursors to mask better-defined regions of interest in the\nphasor space. Elliptical cursors allow independent control of the radii,\nwhich can better match elongated clusters in phasor space:\n\n"
       ]
     },
     {
@@ -112,14 +119,14 @@
       },
       "outputs": [],
       "source": [
-        "radius = [0.1, 0.06]\nradius_minor = [0.3, 0.25]\n\nelliptic_mask = mask_from_elliptic_cursor(\n    real,\n    imag,\n    cursor_real,\n    cursor_imag,\n    radius=radius,\n    radius_minor=radius_minor,\n)"
+        "radius = [0.1, 0.06]  # major axis\nradius_minor = [0.3, 0.25]  # minor axis\n\nelliptic_mask = mask_from_elliptic_cursor(\n    real,\n    imag,\n    cursor_real,\n    cursor_imag,\n    radius=radius,\n    radius_minor=radius_minor,\n)"
       ]
     },
     {
       "cell_type": "markdown",
       "metadata": {},
       "source": [
-        "Show the elliptic cursors in a phasor plot:\n\n"
+        "Show the elliptical cursors in a phasor plot:\n\n"
       ]
     },
     {
@@ -130,14 +137,14 @@
       },
       "outputs": [],
       "source": [
-        "plot = PhasorPlot(allquadrants=True, title='Elliptic cursors')\nplot.hist2d(real, imag, cmap='Greys')\nplot.cursor(\n    cursor_real,\n    cursor_imag,\n    radius=radius,\n    radius_minor=radius_minor,\n    color=CATEGORICAL[:2],\n    label=['cursor 0', 'cursor 1'],\n)\nplot.show()"
+        "plot = PhasorPlot(allquadrants=True, title='Elliptical cursors')\nplot.hist2d(real, imag, cmap='Greys')\nplot.cursor(\n    cursor_real,\n    cursor_imag,\n    radius=radius,\n    radius_minor=radius_minor,\n    color=CATEGORICAL[:2],\n    label=['cursor 0', 'cursor 1'],\n)\nplot.show()"
       ]
     },
     {
       "cell_type": "markdown",
       "metadata": {},
       "source": [
-        "The mean intensity image can be used as a base layer to overlay\nthe masks from the elliptic cursors:\n\n"
+        "The mean intensity image can be used as a base layer to overlay\nthe masks from the elliptical cursors:\n\n"
       ]
     },
     {
@@ -148,14 +155,14 @@
       },
       "outputs": [],
       "source": [
-        "pseudo_color_image = pseudo_color(*elliptic_mask, intensity=mean)\n\nplot_image(\n    pseudo_color_image,\n    title='Pseudo-color image from elliptic cursors and intensity',\n)"
+        "pseudo_color_image = pseudo_color(*elliptic_mask, intensity=mean)\n\nplot_image(\n    pseudo_color_image,\n    title='Pseudo-color image from elliptical cursors and intensity',\n)"
       ]
     },
     {
       "cell_type": "markdown",
       "metadata": {},
       "source": [
-        "## Polar cursors\n\nCreate a mask with two ranges of phase and modulation values:\n\n"
+        "## Polar cursors\n\nUse polar cursors to select regions of interest in the phasor space based\non phase and modulation ranges:\n\n"
       ]
     },
     {
@@ -184,7 +191,7 @@
       },
       "outputs": [],
       "source": [
-        "plot = PhasorPlot(allquadrants=True, title='Polar cursors')\nplot.hist2d(real, imag, cmap='Greys')\nplot.polar_cursor(\n    phase=phase_min,\n    phase_limit=phase_max,\n    modulation=modulation_min,\n    modulation_limit=modulation_max,\n    color=CATEGORICAL[2:4],\n    label=['cursor 0', 'cursor 1'],\n)\nplot.show()"
+        "plot = PhasorPlot(allquadrants=True, title='Polar cursors')\nplot.hist2d(real, imag, cmap='Greys')\nplot.polar_cursor(\n    phase=phase_min,\n    phase_limit=phase_max,\n    modulation=modulation_min,\n    modulation_limit=modulation_max,\n    color=CATEGORICAL[2:4],  # use different colors\n    label=['cursor 0', 'cursor 1'],\n)\nplot.show()"
       ]
     },
     {
@@ -204,13 +211,6 @@
       "source": [
         "pseudo_color_image = pseudo_color(\n    *polar_mask, intensity=mean_thresholded, colors=CATEGORICAL[2:]\n)\n\nplot_image(\n    pseudo_color_image,\n    title='Pseudo-color image from\\npolar cursors and thresholded intensity',\n)"
       ]
-    },
-    {
-      "cell_type": "markdown",
-      "metadata": {},
-      "source": [
-        "sphinx_gallery_thumbnail_number = 1\nmypy: allow-untyped-defs, allow-untyped-calls\nmypy: disable-error-code=\"arg-type\"\n\n"
-      ]
     }
   ],
   "metadata": {

docs/main/_downloads/08c44fd02fe5378fc05e9aecf2e433ce/phasorpy_phasor_from_signal.ipynb

@@ -4,7 +4,7 @@
       "cell_type": "markdown",
       "metadata": {},
       "source": [
-        "\n# Benchmark phasor_from_signal\n\nBenchmark the ``phasor_from_signal`` function.\n\nThe :py:func:`phasorpy.phasor.phasor_from_signal` function to calculate phasor\ncoordinates from time-resolved or spectral signals can operate in two modes:\n\n- using an internal Cython function optimized for calculating a small number\n  of harmonics, optionally using multiple threads.\n\n- using a real forward Fast Fourier Transform (FFT), ``numpy.fft.rfft`` or\n  a drop-in replacement function like ``scipy.fft.rfft``\n  or ``mkl_fft.interfaces.numpy_fft.rfft``.\n\nThis tutorial compares the performance of the two modes.\n\nImport required modules and functions:\n"
+        "\n# Benchmark phasor_from_signal\n\nBenchmark the ``phasor_from_signal`` function.\n\nThe :py:func:`phasorpy.phasor.phasor_from_signal` function used to calculate\nphasor coordinates from time-resolved or spectral signals can operate in\ntwo modes:\n\n- using an internal Cython function optimized for calculating a small number\n  of harmonics, optionally using multiple threads.\n\n- using a real forward Fast Fourier Transform (FFT), ``numpy.fft.rfft`` or\n  a drop-in replacement function like ``scipy.fft.rfft``\n  or ``mkl_fft.interfaces.numpy_fft.rfft``.\n\nThis tutorial compares the performance of the two modes.\n\nImport required modules and functions:\n"
       ]
     },
     {
@@ -15,14 +15,14 @@
       },
       "outputs": [],
       "source": [
-        "from timeit import timeit\n\nimport numpy\nfrom numpy.fft import rfft as numpy_fft  # noqa\n\nfrom phasorpy.phasor import phasor_from_signal  # noqa\nfrom phasorpy.utils import number_threads\n\ntry:\n    from scipy.fft import rfft as scipy_fft\nexcept ImportError:\n    scipy_fft = None\n\ntry:\n    from mkl_fft.interfaces.numpy_fft import rfft as mkl_fft\nexcept ImportError:\n    mkl_fft = None"
+        "from timeit import timeit\n\nimport numpy\nfrom numpy.fft import rfft as numpy_fft  # noqa: F401\n\nfrom phasorpy.phasor import phasor_from_signal  # noqa: F401\nfrom phasorpy.utils import number_threads\n\ntry:\n    from scipy.fft import rfft as scipy_fft\nexcept ImportError:\n    scipy_fft = None\n\ntry:\n    from mkl_fft.interfaces.numpy_fft import rfft as mkl_fft\nexcept ImportError:\n    mkl_fft = None\n\nrng = numpy.random.default_rng(42)  # initialize random number generator"
       ]
     },
     {
       "cell_type": "markdown",
       "metadata": {},
       "source": [
-        "## Run benchmark\n\nCreate a random signal with a size and dtype similar to real world data:\n\n"
+        "## Run benchmark\n\nCreate a random signal with a size and dtype similar to real-world data:\n\n"
       ]
     },
     {
@@ -33,7 +33,7 @@
       },
       "outputs": [],
       "source": [
-        "signal = numpy.random.default_rng(1).random((384, 384, 384))\nsignal += 1.1\nsignal *= 3723  # ~12 bit\nsignal = signal.astype(numpy.uint16)  # 108 MB\nsignal[signal < 0.05] = 0.0  # 5% no signal"
+        "signal = rng.random((384, 384, 384))\nsignal += 1.1\nsignal *= 3723  # ~12 bit\nsignal = signal.astype(numpy.uint16)  # 108 MB\nsignal[signal < 0.05] = 0.0  # 5% no signal"
       ]
     },
     {
@@ -58,32 +58,21 @@
       "cell_type": "markdown",
       "metadata": {},
       "source": [
-        "For reference, the results on a Core i7-14700K CPU, Windows 11,\nPython 3.14.0, numpy 2.3.5, scipy 1.16.3, mkl-fft 2.1.1::\n\n    harmonics 1\n      axis -1\n        not_fft              0.034s   1.00\n        not_fft (6 threads)  0.006s   0.17\n        numpy_fft            0.274s   8.03\n        scipy_fft            0.240s   7.04\n        mkl_fft              0.141s   4.14\n      axis 0\n        not_fft              0.162s   4.75\n        not_fft (6 threads)  0.038s   1.13\n        numpy_fft            0.697s  20.44\n        scipy_fft            0.496s  14.54\n        mkl_fft              0.167s   4.90\n      axis 2\n        not_fft              0.038s   1.12\n        not_fft (6 threads)  0.006s   0.16\n        numpy_fft            0.272s   7.99\n        scipy_fft            0.240s   7.04\n        mkl_fft              0.130s   3.83\n    harmonics 8\n      axis -1\n        not_fft              0.287s   8.43\n        not_fft (6 threads)  0.040s   1.17\n        numpy_fft            0.288s   8.45\n        scipy_fft            0.253s   7.43\n        mkl_fft              0.161s   4.74\n      axis 0\n        not_fft              1.161s  34.04\n        not_fft (6 threads)  0.425s  12.47\n        numpy_fft            0.715s  20.97\n        scipy_fft            0.541s  15.88\n        mkl_fft              0.183s   5.38\n      axis 2\n        not_fft              0.282s   8.27\n        not_fft (6 threads)  0.038s   1.13\n        numpy_fft            0.288s   8.46\n        scipy_fft            0.255s   7.49\n        mkl_fft              0.155s   4.56\n\n"
+        "For reference, the results on a Core i7-14700K CPU, Windows 11,\nPython 3.14.0, numpy 2.3.5, scipy 1.16.3, mkl_fft 2.1.1::\n\n    harmonics 1\n      axis -1\n        not_fft              0.034s   1.00\n        not_fft (6 threads)  0.006s   0.17\n        numpy_fft            0.274s   8.03\n        scipy_fft            0.240s   7.04\n        mkl_fft              0.141s   4.14\n      axis 0\n        not_fft              0.162s   4.75\n        not_fft (6 threads)  0.038s   1.13\n        numpy_fft            0.697s  20.44\n        scipy_fft            0.496s  14.54\n        mkl_fft              0.167s   4.90\n      axis 2\n        not_fft              0.038s   1.12\n        not_fft (6 threads)  0.006s   0.16\n        numpy_fft            0.272s   7.99\n        scipy_fft            0.240s   7.04\n        mkl_fft              0.130s   3.83\n    harmonics 8\n      axis -1\n        not_fft              0.287s   8.43\n        not_fft (6 threads)  0.040s   1.17\n        numpy_fft            0.288s   8.45\n        scipy_fft            0.253s   7.43\n        mkl_fft              0.161s   4.74\n      axis 0\n        not_fft              1.161s  34.04\n        not_fft (6 threads)  0.425s  12.47\n        numpy_fft            0.715s  20.97\n        scipy_fft            0.541s  15.88\n        mkl_fft              0.183s   5.38\n      axis 2\n        not_fft              0.282s   8.27\n        not_fft (6 threads)  0.038s   1.13\n        numpy_fft            0.288s   8.46\n        scipy_fft            0.255s   7.49\n        mkl_fft              0.155s   4.56\n\n"
       ]
     },
     {
       "cell_type": "markdown",
       "metadata": {},
       "source": [
-        "## Results\n\n- Using the Cython implementation is significantly faster than using the\n  ``numpy.fft`` based implementation for single harmonics.\n- Using multiple threads can significantly speed up the Cython mode.\n- The FFT functions from ``scipy`` and ``mkl_fft`` outperform numpy.fft.\n  Specifically, ``mkl_fft`` is very performant.\n- Using FFT becomes more competitive when calculating larger number of\n  harmonics.\n- Computing over the last axis is significantly faster compared to the first\n  axis. That is because the samples in the last dimension are contiguous,\n  closer together in memory.\n\nNote that these results were obtained on a single dataset of random numbers.\n\n"
+        "## Results\n\n- Using the Cython implementation is significantly faster than using the\n  ``numpy.fft``-based implementation for single harmonics.\n- Using multiple threads can significantly speed up the Cython mode.\n- The FFT functions from ``scipy`` and ``mkl_fft`` outperform the\n  ``numpy.fft`` function. Specifically, ``mkl_fft`` is very performant.\n- Using FFT becomes more competitive when calculating a larger number of\n  harmonics.\n- Computing over the last axis is significantly faster compared to the first\n  axis. That is because the samples in the last dimension are contiguous in\n  memory.\n\nNote that these results were obtained on a single dataset of random numbers.\n\n"
       ]
     },
     {
       "cell_type": "markdown",
       "metadata": {},
       "source": [
-        "## Conclusions\n\nUsing the Cython implementation is a reasonable default when calculating\na few harmonics. Using FFT is a better choice when computing large number\nof harmonics, especially with an optimized FFT function.\n\n"
-      ]
-    },
-    {
-      "cell_type": "code",
-      "execution_count": null,
-      "metadata": {
-        "collapsed": false
-      },
-      "outputs": [],
-      "source": [
-        "# mypy: allow-untyped-defs, allow-untyped-calls\n# mypy: disable-error-code=\"arg-type\""
+        "## Conclusions\n\nUsing the Cython implementation is a reasonable default when calculating\na few harmonics. Using FFT is a better choice when computing a large number\nof harmonics, especially with an optimized FFT function.\n\n"
       ]
     }
   ],