deploy: phasorpy/phasorpy@8e9b123

main/_modules/phasorpy/phasor.html

@@ -509,6 +509,10 @@ <h1>Source code for phasorpy.phasor</h1><div class="highlight"><pre>
 <span class="sd">  - :py:func:`fraction_from_amplitude`</span>
 <span class="sd">  - :py:func:`fraction_to_amplitude`</span>
 
+<span class="sd">- calculate phasor coordinates on semicircle at other harmonics:</span>
+
+<span class="sd">  - :py:func:`phasor_at_harmonic`</span>
+
 <span class="sd">&quot;&quot;&quot;</span>
 
 <span class="kn">from</span> <span class="nn">__future__</span> <span class="kn">import</span> <span class="n">annotations</span>
@@ -518,6 +522,7 @@ <h1>Source code for phasorpy.phasor</h1><div class="highlight"><pre>
     <span class="s1">&#39;fraction_to_amplitude&#39;</span><span class="p">,</span>
     <span class="s1">&#39;frequency_from_lifetime&#39;</span><span class="p">,</span>
     <span class="s1">&#39;frequency_to_lifetime&#39;</span><span class="p">,</span>
+    <span class="s1">&#39;phasor_at_harmonic&#39;</span><span class="p">,</span>
     <span class="s1">&#39;phasor_calibrate&#39;</span><span class="p">,</span>
     <span class="s1">&#39;phasor_center&#39;</span><span class="p">,</span>
     <span class="s1">&#39;phasor_from_apparent_lifetime&#39;</span><span class="p">,</span>
@@ -555,6 +560,7 @@ <h1>Source code for phasorpy.phasor</h1><div class="highlight"><pre>
 <span class="kn">import</span> <span class="nn">numpy</span>
 
 <span class="kn">from</span> <span class="nn">._phasorpy</span> <span class="kn">import</span> <span class="p">(</span>
+    <span class="n">_phasor_at_harmonic</span><span class="p">,</span>
     <span class="n">_phasor_from_apparent_lifetime</span><span class="p">,</span>
     <span class="n">_phasor_from_fret_acceptor</span><span class="p">,</span>
     <span class="n">_phasor_from_fret_donor</span><span class="p">,</span>
@@ -1767,6 +1773,87 @@ <h1>Source code for phasorpy.phasor</h1><div class="highlight"><pre>
 
 
 
+<div class="viewcode-block" id="phasor_at_harmonic">
+<a class="viewcode-back" href="../../api/phasor.html#phasorpy.phasor.phasor_at_harmonic">[docs]</a>
+<span class="k">def</span> <span class="nf">phasor_at_harmonic</span><span class="p">(</span>
+    <span class="n">real</span><span class="p">:</span> <span class="n">ArrayLike</span><span class="p">,</span>
+    <span class="n">harmonic</span><span class="p">:</span> <span class="n">ArrayLike</span><span class="p">,</span>
+    <span class="n">other_harmonic</span><span class="p">:</span> <span class="n">ArrayLike</span><span class="p">,</span>
+    <span class="o">/</span><span class="p">,</span>
+    <span class="o">**</span><span class="n">kwargs</span><span class="p">:</span> <span class="n">Any</span><span class="p">,</span>
+<span class="p">)</span> <span class="o">-&gt;</span> <span class="nb">tuple</span><span class="p">[</span><span class="n">NDArray</span><span class="p">[</span><span class="n">numpy</span><span class="o">.</span><span class="n">float64</span><span class="p">],</span> <span class="n">NDArray</span><span class="p">[</span><span class="n">numpy</span><span class="o">.</span><span class="n">float64</span><span class="p">]]:</span>
+<span class="w">    </span><span class="sa">r</span><span class="sd">&quot;&quot;&quot;Return phasor coordinates on universal semicircle at other harmonics.</span>
+
+<span class="sd">    Return phasor coordinates at any harmonic, given the real component of</span>
+<span class="sd">    phasor coordinates of a single exponential lifetime at a certain harmonic.</span>
+<span class="sd">    The input and output phasor coordinates lie on the universal semicircle.</span>
+
+<span class="sd">    Parameters</span>
+<span class="sd">    ----------</span>
+<span class="sd">    real : array_like</span>
+<span class="sd">        Real component of phasor coordinates of single exponential lifetime</span>
+<span class="sd">        at `harmonic`.</span>
+<span class="sd">    harmonic : array_like</span>
+<span class="sd">        Harmonic of `real` coordinate. Must be integer &gt;= 1.</span>
+<span class="sd">    other_harmonic : array_like</span>
+<span class="sd">        Harmonic for which to return phasor coordinates. Must be integer &gt;= 1.</span>
+<span class="sd">    **kwargs</span>
+<span class="sd">        Optional `arguments passed to numpy universal functions</span>
+<span class="sd">        &lt;https://numpy.org/doc/stable/reference/ufuncs.html#ufuncs-kwargs&gt;`_.</span>
+
+<span class="sd">    Returns</span>
+<span class="sd">    -------</span>
+<span class="sd">    real_other : ndarray</span>
+<span class="sd">        Real component of phasor coordinates at `other_harmonic`.</span>
+<span class="sd">    imag_other : ndarray</span>
+<span class="sd">        Imaginary component of phasor coordinates at `other_harmonic`.</span>
+
+<span class="sd">    Notes</span>
+<span class="sd">    -----</span>
+<span class="sd">    The phasor coordinates</span>
+<span class="sd">    :math:`g_{n}` (`real_other`) and :math:`s_{n}` (`imag_other`)</span>
+<span class="sd">    of a single exponential lifetime at harmonic :math:`n` (`other_harmonic`)</span>
+<span class="sd">    is calculated from the real part of the phasor coordinates</span>
+<span class="sd">    :math:`g_{m}` (`real`) at harmonic :math:`m` (`harmonic`) according to</span>
+<span class="sd">    (:ref:`Torrado, Malacrida, &amp; Ranjit. 2022 &lt;torrado-2022&gt;`. Eq. 25):</span>
+
+<span class="sd">    .. math::</span>
+
+<span class="sd">        g_{n} &amp;= \frac{m^2 \cdot g_{m}}{n^2 + (m^2-n^2) \cdot g_{m}}</span>
+
+<span class="sd">        s_{n} &amp;= \sqrt{G_{n} - g_{n}^2}</span>
+
+<span class="sd">    This function is equivalent to the following operations:</span>
+
+<span class="sd">    .. code-block:: python</span>
+
+<span class="sd">        phasor_from_lifetime(</span>
+<span class="sd">            frequency=other_harmonic,</span>
+<span class="sd">            lifetime=phasor_to_apparent_lifetime(</span>
+<span class="sd">                real, sqrt(real - real * real), frequency=harmonic</span>
+<span class="sd">            )[0],</span>
+<span class="sd">        )</span>
+
+<span class="sd">    Examples</span>
+<span class="sd">    --------</span>
+<span class="sd">    The phasor coordinates at higher harmonics are approaching the origin:</span>
+
+<span class="sd">    &gt;&gt;&gt; phasor_at_harmonic(0.5, 1, [1, 2, 4, 8])  # doctest: +NUMBER</span>
+<span class="sd">    (array([0.5, 0.2, 0.05882, 0.01538]), array([0.5, 0.4, 0.2353, 0.1231]))</span>
+
+<span class="sd">    &quot;&quot;&quot;</span>
+    <span class="n">harmonic</span> <span class="o">=</span> <span class="n">numpy</span><span class="o">.</span><span class="n">asarray</span><span class="p">(</span><span class="n">harmonic</span><span class="p">,</span> <span class="n">dtype</span><span class="o">=</span><span class="n">numpy</span><span class="o">.</span><span class="n">int32</span><span class="p">)</span>
+    <span class="k">if</span> <span class="n">numpy</span><span class="o">.</span><span class="n">any</span><span class="p">(</span><span class="n">harmonic</span> <span class="o">&lt;</span> <span class="mi">1</span><span class="p">):</span>
+        <span class="k">raise</span> <span class="ne">ValueError</span><span class="p">(</span><span class="s1">&#39;invalid harmonic&#39;</span><span class="p">)</span>
+
+    <span class="n">other_harmonic</span> <span class="o">=</span> <span class="n">numpy</span><span class="o">.</span><span class="n">asarray</span><span class="p">(</span><span class="n">other_harmonic</span><span class="p">,</span> <span class="n">dtype</span><span class="o">=</span><span class="n">numpy</span><span class="o">.</span><span class="n">int32</span><span class="p">)</span>
+    <span class="k">if</span> <span class="n">numpy</span><span class="o">.</span><span class="n">any</span><span class="p">(</span><span class="n">other_harmonic</span> <span class="o">&lt;</span> <span class="mi">1</span><span class="p">):</span>
+        <span class="k">raise</span> <span class="ne">ValueError</span><span class="p">(</span><span class="s1">&#39;invalid other_harmonic&#39;</span><span class="p">)</span>
+
+    <span class="k">return</span> <span class="n">_phasor_at_harmonic</span><span class="p">(</span><span class="n">real</span><span class="p">,</span> <span class="n">harmonic</span><span class="p">,</span> <span class="n">other_harmonic</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">)</span></div>
+
+
+
 <div class="viewcode-block" id="phasor_from_lifetime">
 <a class="viewcode-back" href="../../api/phasor.html#phasorpy.phasor.phasor_from_lifetime">[docs]</a>
 <span class="k">def</span> <span class="nf">phasor_from_lifetime</span><span class="p">(</span>

main/_sources/sg_execution_times.rst.txt

@@ -6,7 +6,7 @@
 
 Computation times
 =================
-**00:30.777** total execution time for 7 files **from all galleries**:
+**00:26.613** total execution time for 7 files **from all galleries**:
 
 .. container::
 
@@ -33,23 +33,23 @@ Computation times
      - Time
      - Mem (MB)
    * - :ref:`sphx_glr_tutorials_benchmarks_phasorpy_phasor_from_signal.py` (``../tutorials/benchmarks/phasorpy_phasor_from_signal.py``)
-     - 00:14.354
+     - 00:13.381
      - 0.0
    * - :ref:`sphx_glr_tutorials_phasorpy_introduction.py` (``../tutorials/phasorpy_introduction.py``)
-     - 00:12.355
+     - 00:09.981
      - 0.0
    * - :ref:`sphx_glr_tutorials_phasorpy_fret.py` (``../tutorials/phasorpy_fret.py``)
-     - 00:02.104
+     - 00:01.701
      - 0.0
    * - :ref:`sphx_glr_tutorials_phasorpy_phasorplot.py` (``../tutorials/phasorpy_phasorplot.py``)
-     - 00:00.868
+     - 00:00.676
      - 0.0
    * - :ref:`sphx_glr_tutorials_phasorpy_phasor_from_lifetime.py` (``../tutorials/phasorpy_phasor_from_lifetime.py``)
-     - 00:00.584
+     - 00:00.452
      - 0.0
    * - :ref:`sphx_glr_tutorials_phasorpy_components.py` (``../tutorials/phasorpy_components.py``)
-     - 00:00.450
+     - 00:00.361
      - 0.0
    * - :ref:`sphx_glr_tutorials_misc_phasorpy_logo.py` (``../tutorials/misc/phasorpy_logo.py``)
-     - 00:00.062
+     - 00:00.061
      - 0.0

main/_sources/tutorials/benchmarks/phasorpy_phasor_from_signal.rst.txt

@@ -148,35 +148,35 @@ and number of threads:
     harmonics 1
       axis -1
         phasor_from_signal       0.056s   1.00
-          threads 2              0.032s   0.57
-        phasor_from_signal_fft   0.410s   7.32
-          scipy_fft              0.438s   7.82
+          threads 2              0.030s   0.54
+        phasor_from_signal_fft   0.397s   7.11
+          scipy_fft              0.401s   7.19
       axis 0
-        phasor_from_signal       0.165s   2.94
-          threads 2              0.081s   1.44
-        phasor_from_signal_fft   3.002s  53.63
-          scipy_fft              0.515s   9.20
+        phasor_from_signal       0.164s   2.94
+          threads 2              0.081s   1.45
+        phasor_from_signal_fft   2.565s  45.97
+          scipy_fft              0.481s   8.62
       axis 2
         phasor_from_signal       0.056s   1.00
-          threads 2              0.032s   0.57
-        phasor_from_signal_fft   0.416s   7.43
-          scipy_fft              0.433s   7.73
+          threads 2              0.030s   0.54
+        phasor_from_signal_fft   0.394s   7.06
+          scipy_fft              0.397s   7.11
     harmonics 8
       axis -1
-        phasor_from_signal       0.454s   8.11
-          threads 2              0.245s   4.38
-        phasor_from_signal_fft   0.443s   7.91
-          scipy_fft              0.425s   7.59
+        phasor_from_signal       0.456s   8.17
+          threads 2              0.234s   4.20
+        phasor_from_signal_fft   0.409s   7.34
+          scipy_fft              0.408s   7.32
       axis 0
-        phasor_from_signal       1.341s  23.96
-          threads 2              0.656s  11.73
-        phasor_from_signal_fft   2.745s  49.04
-          scipy_fft              0.522s   9.32
+        phasor_from_signal       1.315s  23.57
+          threads 2              0.661s  11.85
+        phasor_from_signal_fft   2.537s  45.47
+          scipy_fft              0.485s   8.70
       axis 2
-        phasor_from_signal       0.444s   7.94
-          threads 2              0.248s   4.42
-        phasor_from_signal_fft   0.417s   7.45
-          scipy_fft              0.433s   7.73
+        phasor_from_signal       0.444s   7.96
+          threads 2              0.235s   4.20
+        phasor_from_signal_fft   0.405s   7.27
+          scipy_fft              0.407s   7.30
 
 
 
@@ -255,7 +255,7 @@ when computing large number of harmonics with an optimized FFT function.
 
 .. rst-class:: sphx-glr-timing
 
-   **Total running time of the script:** (0 minutes 14.354 seconds)
+   **Total running time of the script:** (0 minutes 13.381 seconds)
 
 
 .. _sphx_glr_download_tutorials_benchmarks_phasorpy_phasor_from_signal.py:

main/_sources/tutorials/benchmarks/sg_execution_times.rst.txt

@@ -6,7 +6,7 @@
 
 Computation times
 =================
-**00:14.354** total execution time for 1 file **from tutorials/benchmarks**:
+**00:13.381** total execution time for 1 file **from tutorials/benchmarks**:
 
 .. container::
 
@@ -33,5 +33,5 @@ Computation times
      - Time
      - Mem (MB)
    * - :ref:`sphx_glr_tutorials_benchmarks_phasorpy_phasor_from_signal.py` (``phasorpy_phasor_from_signal.py``)
-     - 00:14.354
+     - 00:13.381
      - 0.0

main/_sources/tutorials/misc/phasorpy_logo.rst.txt

@@ -60,7 +60,7 @@ Create the PhasorPy logo using the PhasorPy library.
 
 .. rst-class:: sphx-glr-timing
 
-   **Total running time of the script:** (0 minutes 0.062 seconds)
+   **Total running time of the script:** (0 minutes 0.061 seconds)
 
 
 .. _sphx_glr_download_tutorials_misc_phasorpy_logo.py:

main/_sources/tutorials/misc/sg_execution_times.rst.txt

@@ -6,7 +6,7 @@
 
 Computation times
 =================
-**00:00.062** total execution time for 1 file **from tutorials/misc**:
+**00:00.061** total execution time for 1 file **from tutorials/misc**:
 
 .. container::
 
@@ -33,5 +33,5 @@ Computation times
      - Time
      - Mem (MB)
    * - :ref:`sphx_glr_tutorials_misc_phasorpy_logo.py` (``phasorpy_logo.py``)
-     - 00:00.062
+     - 00:00.061
      - 0.0

main/_sources/tutorials/phasorpy_components.rst.txt

@@ -211,7 +211,7 @@ sphinx_gallery_thumbnail_number = 2
 
 .. rst-class:: sphx-glr-timing
 
-   **Total running time of the script:** (0 minutes 0.450 seconds)
+   **Total running time of the script:** (0 minutes 0.361 seconds)
 
 
 .. _sphx_glr_download_tutorials_phasorpy_components.py:

main/_sources/tutorials/phasorpy_fret.rst.txt

@@ -407,7 +407,7 @@ mypy: disable-error-code="arg-type"
 
 .. rst-class:: sphx-glr-timing
 
-   **Total running time of the script:** (0 minutes 2.104 seconds)
+   **Total running time of the script:** (0 minutes 1.701 seconds)
 
 
 .. _sphx_glr_download_tutorials_phasorpy_fret.py:

main/_sources/tutorials/phasorpy_introduction.rst.txt

@@ -448,7 +448,7 @@ sphinx_gallery_thumbnail_number = 3
 
 .. rst-class:: sphx-glr-timing
 
-   **Total running time of the script:** (0 minutes 12.355 seconds)
+   **Total running time of the script:** (0 minutes 9.981 seconds)
 
 
 .. _sphx_glr_download_tutorials_phasorpy_introduction.py:

main/_sources/tutorials/phasorpy_phasor_from_lifetime.rst.txt

@@ -358,7 +358,7 @@ sphinx_gallery_thumbnail_number = -2
 
 .. rst-class:: sphx-glr-timing
 
-   **Total running time of the script:** (0 minutes 0.584 seconds)
+   **Total running time of the script:** (0 minutes 0.452 seconds)
 
 
 .. _sphx_glr_download_tutorials_phasorpy_phasor_from_lifetime.py:

main/_sources/tutorials/phasorpy_phasorplot.rst.txt

@@ -461,7 +461,7 @@ sphinx_gallery_thumbnail_number = 10
 
 .. rst-class:: sphx-glr-timing
 
-   **Total running time of the script:** (0 minutes 0.868 seconds)
+   **Total running time of the script:** (0 minutes 0.676 seconds)
 
 
 .. _sphx_glr_download_tutorials_phasorpy_phasorplot.py:

main/_sources/tutorials/sg_execution_times.rst.txt

@@ -6,7 +6,7 @@
 
 Computation times
 =================
-**00:16.360** total execution time for 5 files **from tutorials**:
+**00:13.172** total execution time for 5 files **from tutorials**:
 
 .. container::
 
@@ -33,17 +33,17 @@ Computation times
      - Time
      - Mem (MB)
    * - :ref:`sphx_glr_tutorials_phasorpy_introduction.py` (``phasorpy_introduction.py``)
-     - 00:12.355
+     - 00:09.981
      - 0.0
    * - :ref:`sphx_glr_tutorials_phasorpy_fret.py` (``phasorpy_fret.py``)
-     - 00:02.104
+     - 00:01.701
      - 0.0
    * - :ref:`sphx_glr_tutorials_phasorpy_phasorplot.py` (``phasorpy_phasorplot.py``)
-     - 00:00.868
+     - 00:00.676
      - 0.0
    * - :ref:`sphx_glr_tutorials_phasorpy_phasor_from_lifetime.py` (``phasorpy_phasor_from_lifetime.py``)
-     - 00:00.584
+     - 00:00.452
      - 0.0
    * - :ref:`sphx_glr_tutorials_phasorpy_components.py` (``phasorpy_components.py``)
-     - 00:00.450
+     - 00:00.361
      - 0.0

main/api/index.html

@@ -499,6 +499,7 @@ <h1>API reference<a class="headerlink" href="#api-reference" title="Link to this
 <li class="toctree-l2"><a class="reference internal" href="phasor.html#phasorpy.phasor.fraction_to_amplitude"><code class="docutils literal notranslate"><span class="pre">fraction_to_amplitude()</span></code></a></li>
 <li class="toctree-l2"><a class="reference internal" href="phasor.html#phasorpy.phasor.frequency_from_lifetime"><code class="docutils literal notranslate"><span class="pre">frequency_from_lifetime()</span></code></a></li>
 <li class="toctree-l2"><a class="reference internal" href="phasor.html#phasorpy.phasor.frequency_to_lifetime"><code class="docutils literal notranslate"><span class="pre">frequency_to_lifetime()</span></code></a></li>
+<li class="toctree-l2"><a class="reference internal" href="phasor.html#phasorpy.phasor.phasor_at_harmonic"><code class="docutils literal notranslate"><span class="pre">phasor_at_harmonic()</span></code></a></li>
 <li class="toctree-l2"><a class="reference internal" href="phasor.html#phasorpy.phasor.phasor_calibrate"><code class="docutils literal notranslate"><span class="pre">phasor_calibrate()</span></code></a></li>
 <li class="toctree-l2"><a class="reference internal" href="phasor.html#phasorpy.phasor.phasor_center"><code class="docutils literal notranslate"><span class="pre">phasor_center()</span></code></a></li>
 <li class="toctree-l2"><a class="reference internal" href="phasor.html#phasorpy.phasor.phasor_from_apparent_lifetime"><code class="docutils literal notranslate"><span class="pre">phasor_from_apparent_lifetime()</span></code></a></li>