Update examples

.vscode/settings.json

@@ -5,10 +5,15 @@
     ],
     "python.testing.unittestEnabled": false,
     "notebook.formatOnSave.enabled": true,
+    "notebook.codeActionsOnSave": {
+        // "source.fixAll": true,
+        "source.organizeImports": true
+    },
     "[python]": {
         "editor.formatOnSave": true,
         "editor.defaultFormatter": "charliermarsh.ruff",
         "editor.codeActionsOnSave": {
+            // "source.fixAll": true,
             "source.organizeImports": true
         },
     },

pyproject.toml

@@ -77,10 +77,11 @@ universal = false
 [tool.ruff]
 src = ["src"]
 extend-include = ["*.ipynb"]
-extend-exclude = ["build", "dist", "docs", "src/sdr/_version.py"]
+extend-exclude = ["build", "dist", "src/sdr/_version.py"]
 line-length = 120
 
 [tool.ruff.lint]
+exclude = ["docs/*"]
 select = [
     "E",  # pycodestyle
     "F",  # Pyflakes

src/sdr/_synchronization/_nco.py

@@ -3,8 +3,11 @@
 """
 from __future__ import annotations
 
+from typing import Any, overload
+
 import numpy as np
 import numpy.typing as npt
+from typing_extensions import Literal
 
 from .._helper import export
 
@@ -120,11 +123,30 @@ def reset(self):
         """
         self._z_prev = -self.increment
 
+    @overload
+    def __call__(
+        self,
+        freq: npt.NDArray[np.float_] | None = None,
+        phase: npt.NDArray[np.float_] | None = None,
+        output: Literal["phase", "sine", "cosine"] = "complex-exp",
+    ) -> npt.NDArray[np.float_]:
+        ...
+
+    @overload
     def __call__(
         self,
         freq: npt.NDArray[np.float_] | None = None,
         phase: npt.NDArray[np.float_] | None = None,
+        output: Literal["complex-exp"] = "complex-exp",
     ) -> npt.NDArray[np.complex_]:
+        ...
+
+    def __call__(
+        self,
+        freq: Any = None,
+        phase: Any = None,
+        output: Any = "complex-exp",
+    ) -> Any:
         """
         Steps the NCO with variable frequency and/or phase signals.
 
@@ -133,9 +155,11 @@ def __call__(
                 phase increment of the NCO. If `None`, the signal is all zeros.
             phase: The variable phase signal $p[n]$ in radians. This input signal varies the per-sample phase offset
                 of the NCO. If `None`, the signal is all zeros.
+            output: The format of the output signal $y[n]$. Options are the accumulated phase, sine, cosine, or
+                complex exponential.
 
         Returns:
-            The output complex signal $y[n]$.
+            The output signal $y[n]$.
 
         Examples:
             See the :ref:`phase-locked-loop` example.
@@ -163,7 +187,18 @@ def __call__(
         # Add the absolute offset to every sample
         y = z + self.offset + phase
 
-        y = np.exp(1j * y)
+        if output == "phase":
+            pass
+        elif output == "complex-exp":
+            y = np.exp(1j * y)
+        elif output == "sine":
+            y = np.sin(y)
+        elif output == "cosine":
+            y = np.cos(y)
+        else:
+            raise ValueError(
+                f"Argument 'output' must be one of 'phase', 'sine', 'cosine', or 'complex-exp', not {output!r}."
+            )
 
         if y.size == 1:
             y = y[0]

src/sdr/plot/_filter.py

@@ -278,9 +278,6 @@ def magnitude_response(
         decades: The number of decades to plot when `x_axis="log"`.
         kwargs: Additional keyword arguments to pass to :func:`matplotlib.pyplot.plot()`.
 
-    Note:
-        The default y-axis lower limit is set to the 10th percentile. This is to crop any deep nulls.
-
     Examples:
         See the :ref:`fir-filters` example.
 
@@ -361,11 +358,6 @@ def magnitude_response(
         else:
             plt.plot(f, H, **kwargs)
 
-        # Avoid deep nulls
-        y_max = plt.gca().get_ylim()[1]
-        y_min = np.percentile(H, 10)
-        plt.ylim(y_min, y_max)
-
         plt.grid(True, which="both")
         if "label" in kwargs:
             plt.legend()

src/sdr/plot/_helper.py

@@ -37,9 +37,9 @@ def real_or_complex_plot(
 
 def min_ylim(y: npt.NDArray, separation: float, sample_rate: float):
     ymin, ymax = plt.gca().get_ylim()
-    if ymax - ymin < separation:
+    if ymax - ymin < separation / 4:
         # Find the mean of the signal rounded to the nearest sample
-        mean = int(round(np.mean(y) / sample_rate))
+        mean = int(round(np.nanmean(y) / sample_rate))
         ymin = mean - separation / 2
         ymax = mean + separation / 2
         plt.gca().set_ylim(ymin, ymax)

src/sdr/plot/_spectral_estimation.py

@@ -50,9 +50,6 @@ def periodogram(
         y_axis: The y-axis scaling. Options are to display a linear or logarithmic power spectral density.
         kwargs: Additional keyword arguments to pass to :func:`matplotlib.pyplot.plot()`.
 
-    Note:
-        The default y-axis lower limit is set to the 10th percentile. This is to crop any deep nulls.
-
     Group:
         plot-spectral-estimation
     """
@@ -103,11 +100,6 @@ def periodogram(
         if "label" in kwargs:
             plt.legend()
 
-        # Avoid deep nulls
-        y_max = plt.gca().get_ylim()[1]
-        y_min = np.percentile(Pxx, 10)
-        plt.ylim(y_min, y_max)
-
         if sample_rate_provided:
             plt.xlabel(f"Frequency ({units}), $f$")
         else:

tests/synchronization/test_nco.py

@@ -4,10 +4,12 @@
 import sdr
 
 
-def test_call_no_args():
+def test_call_exceptions():
     nco = sdr.NCO()
     with pytest.raises(ValueError):
         nco()
+    with pytest.raises(ValueError):
+        nco(np.array([1, 2, 3]), output="invalid")
 
 
 def test_initial_phase_is_offset():