Add doctest

.github/workflows/ci.yml

@@ -21,15 +21,15 @@ jobs:
             torch: 2.3.1
             torchaudio: 2.3.1
           - python: "3.13"
-            torch: 2.8.0
-            torchaudio: 2.8.0
+            torch: 2.9.0
+            torchaudio: 2.9.0
 
     steps:
       - name: Clone
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
 
       - name: Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
           python-version: ${{ matrix.python }}
           architecture: x64
@@ -46,7 +46,7 @@ jobs:
         run: make check
 
       - name: Test
-        run: make test OPT="--dtype double"
+        run: make test-all OPT="--dtype double"
 
       - name: Coverage
         uses: codecov/codecov-action@v5

Makefile

@@ -61,11 +61,18 @@ format: tool
 	./tools/taplo/taplo fmt *.toml
 	./tools/yamlfmt/yamlfmt *.cff *.yml .github/workflows/*.yml
 
+test-all: test-example test
+
 test: tool
-	[ -n "$(MODULE)" ] && module=tests/test_$(MODULE).py || module=; \
+	[ -n "$(MODULE)" ] && module="--no-cov tests/test_$(MODULE).py" || module=; \
 	. .venv/bin/activate && export PATH=./tools/SPTK/bin:$$PATH NUMBA_CUDA_LOW_OCCUPANCY_WARNINGS=0 PYLSTRAIGHT_DEBUG=1 && \
 	python -m pytest $$module $(OPT)
 
+test-example: tool
+	[ -n "$(MODULE)" ] && module=modules/$(MODULE).py || module=; \
+	. .venv/bin/activate && export NUMBA_CUDA_LOW_OCCUPANCY_WARNINGS=0 && \
+	python -m pytest --doctest-modules --no-cov --ignore=diffsptk/third_party diffsptk/$$module
+
 test-clean:
 	rm -rf tests/__pycache__
 	rm -rf *.png *.wav

README.md

@@ -2,11 +2,12 @@
 
 *diffsptk* is a differentiable version of [SPTK](https://github.com/sp-nitech/SPTK) based on the PyTorch framework.
 
-[![Manual](https://img.shields.io/badge/docs-stable-blue.svg)](https://sp-nitech.github.io/diffsptk/3.3.1/)
+[![Manual](https://img.shields.io/badge/docs-stable-blue.svg)](https://sp-nitech.github.io/diffsptk/3.4.0/)
 [![Downloads](https://static.pepy.tech/badge/diffsptk)](https://pepy.tech/project/diffsptk)
 [![ClickPy](https://img.shields.io/badge/downloads-clickpy-yellow.svg)](https://clickpy.clickhouse.com/dashboard/diffsptk)
+[![Advisor](https://snyk.io/advisor/python/diffsptk/badge.svg)](https://snyk.io/advisor/python/diffsptk)
 [![Python Version](https://img.shields.io/pypi/pyversions/diffsptk.svg)](https://pypi.python.org/pypi/diffsptk)
-[![PyTorch Version](https://img.shields.io/badge/pytorch-2.3.1%20%7C%202.8.0-orange.svg)](https://pypi.python.org/pypi/diffsptk)
+[![PyTorch Version](https://img.shields.io/badge/pytorch-2.3.1%20%7C%202.9.0-orange.svg)](https://pypi.python.org/pypi/diffsptk)
 [![PyPI Version](https://img.shields.io/pypi/v/diffsptk.svg)](https://pypi.python.org/pypi/diffsptk)
 [![Codecov](https://codecov.io/gh/sp-nitech/diffsptk/branch/master/graph/badge.svg)](https://app.codecov.io/gh/sp-nitech/diffsptk)
 [![License](https://img.shields.io/github/license/sp-nitech/diffsptk.svg)](https://github.com/sp-nitech/diffsptk/blob/master/LICENSE)
@@ -20,7 +21,7 @@
 
 ## Documentation
 
-- Online [documentation](https://sp-nitech.github.io/diffsptk/3.3.1/) for the reference manual
+- Online [documentation](https://sp-nitech.github.io/diffsptk/3.4.0/) for the reference manual
 - Conference [paper](https://www.isca-archive.org/ssw_2023/yoshimura23_ssw.html) on the ISCA Archive
 - Hands-on [tutorial](https://colab.research.google.com/drive/1xAoUKqXadvJXJ7RzN0OceB6y7q5i7Sn6?usp=drive_link) on Google Colab
 

diffsptk/functional.py

@@ -444,11 +444,12 @@ def dht(x: Tensor, dht_type: int = 2) -> Tensor:
 
 def drc(
     x: Tensor,
+    *,
+    sample_rate: int,
     threshold: float,
     ratio: float,
     attack_time: float,
     release_time: float,
-    sample_rate: int,
     makeup_gain: float = 0,
     abs_max: float = 1,
 ) -> Tensor:
@@ -459,6 +460,9 @@ def drc(
     x : Tensor [shape=(..., T)]
         The input waveform.
 
+    sample_rate : int >= 1
+        The sample rate in Hz.
+
     threshold : float <= 0
         The threshold in dB.
 
@@ -471,9 +475,6 @@ def drc(
     release_time : float > 0
         The release time in msec.
 
-    sample_rate : int >= 1
-        The sample rate in Hz.
-
     makeup_gain : float >= 0
         The make-up gain in dB.
 
@@ -571,36 +572,27 @@ def dtw(
     )
 
 
-def dtw_merge(x: Tensor, y: Tensor, indices: Tensor) -> tuple[Tensor, Tensor]:
-    """Align two vector sequences according to the given path.
+def dtw_merge(x: Tensor, y: Tensor, indices: Tensor) -> Tensor:
+    """Merge two sequences according to the given indices.
 
     Parameters
     ----------
-    x : Tensor [shape=(T1, ...)]
+    x : Tensor [shape=(T1, D) or (T1,)]
         The query vector sequence.
 
-    y : Tensor [shape=(T2, ...)]
+    y : Tensor [shape=(T2, D) or (T2,)]
         The reference vector sequence.
 
     indices : Tensor [shape=(T, 2)]
-        The indices of the path.
+        The indices of the viterbi path.
 
     Returns
     -------
-    x_align : Tensor [shape=(T, ...)]
-        The aligned query vector sequence.
-
-    y_align : Tensor [shape=(T, ...)]
-        The aligned reference vector sequence.
+    z : Tensor [shape=(T, 2D) or (T, 2)]
+        The merged vector sequence.
 
     """
-    if x.dim() != y.dim():
-        raise ValueError("x and y must have the same number of dimensions.")
-    if indices.dim() != 2 or indices.size(-1) != 2:
-        raise ValueError("The shape of indices must be (T, 2).")
-    x_align = x[indices[:, 0]]
-    y_align = y[indices[:, 1]]
-    return x_align, y_align
+    return nn.DynamicTimeWarping.merge(x=x, y=y, indices=indices)
 
 
 def entropy(p: Tensor, out_format: str = "nat") -> Tensor:

diffsptk/modules/acorr.py

@@ -62,8 +62,9 @@ def forward(self, x: torch.Tensor) -> torch.Tensor:
 
         Examples
         --------
-        >>> x = diffsptk.ramp(4)
+        >>> import diffsptk
         >>> acorr = diffsptk.Autocorrelation(5, 3)
+        >>> x = diffsptk.ramp(4)
         >>> r = acorr(x)
         >>> r
         tensor([30.0000, 20.0000, 11.0000,  4.0000])

diffsptk/modules/acr2csm.py

@@ -73,14 +73,13 @@ def forward(self, r: torch.Tensor) -> torch.Tensor:
 
         Examples
         --------
-        >>> x = diffsptk.nrand(4)
-        >>> x
-        tensor([ 0.0165, -2.3693,  0.1375, -0.2262,  1.3307])
+        >>> import diffsptk
         >>> acorr = diffsptk.Autocorrelation(5, 3)
         >>> acr2csm = diffsptk.AutocorrelationToCompositeSinusoidalModelCoefficients(3)
+        >>> x = diffsptk.ramp(4)
         >>> c = acr2csm(acorr(x))
         >>> c
-        tensor([0.9028, 2.5877, 3.8392, 3.6153])
+        tensor([ 0.5261,  2.1403, 25.7668,  4.2332])
 
         """
         check_size(r.size(-1), self.in_dim, "dimension of autocorrelation")
@@ -137,12 +136,6 @@ def _precompute(
 
     @staticmethod
     def _forward(r: torch.Tensor, C: torch.Tensor) -> torch.Tensor:
-        if r.dtype != torch.double or C.dtype != torch.double:
-            raise ValueError(
-                "Only double precision is supported "
-                f"(input: {r.dtype}, module: {C.dtype})."
-            )
-
         u = torch.matmul(r, C)
         u1, u2 = torch.tensor_split(u, 2, dim=-1)
 

diffsptk/modules/alaw.py

@@ -57,8 +57,9 @@ def forward(self, x: torch.Tensor) -> torch.Tensor:
 
         Examples
         --------
-        >>> x = diffsptk.ramp(4)
+        >>> import diffsptk
         >>> alaw = diffsptk.ALawCompression(4)
+        >>> x = diffsptk.ramp(4)
         >>> y = alaw(x)
         >>> y
         tensor([0.0000, 2.9868, 3.4934, 3.7897, 4.0000])

diffsptk/modules/ap.py

@@ -138,15 +138,16 @@ def forward(self, x: torch.Tensor, f0: torch.Tensor) -> torch.Tensor:
 
         Examples
         --------
-        >>> x = diffsptk.sin(1000, 80)
-        >>> pitch = diffsptk.Pitch(160, 8000, out_format="f0")
+        >>> import diffsptk
+        >>> pitch = diffsptk.Pitch(160, 16000, out_format="f0")
+        >>> aperiodicity = diffsptk.Aperiodicity(160, 16000, 1024)
+        >>> x = diffsptk.sin(2000, 80)
         >>> f0 = pitch(x)
         >>> f0.shape
-        torch.Size([7])
-        >>> aperiodicity = diffsptk.Aperiodicity(160, 16000, 1024)
+        torch.Size([13])
         >>> ap = aperiodicity(x, f0)
         >>> ap.shape
-        torch.Size([7, 513])
+        torch.Size([13, 513])
 
         """
         d = x.dim()

diffsptk/modules/b2mc.py

@@ -77,12 +77,13 @@ def forward(self, b: torch.Tensor) -> torch.Tensor:
 
         Examples
         --------
-        >>> b = diffsptk.ramp(4)
+        >>> import diffsptk
         >>> mc2b = diffsptk.MelCepstrumToMLSADigitalFilterCoefficients(4, 0.3)
         >>> b2mc = diffsptk.MLSADigitalFilterCoefficientsToMelCepstrum(4, 0.3)
+        >>> b = diffsptk.ramp(1, 5)
         >>> b2 = mc2b(b2mc(b))
         >>> b2
-        tensor([0.0000, 1.0000, 2.0000, 3.0000, 4.0000])
+        tensor([1.0000, 2.0000, 3.0000, 4.0000, 5.0000])
 
         """
         check_size(b.size(-1), self.in_dim, "dimension of cepstrum")

diffsptk/modules/c2acr.py

@@ -61,13 +61,13 @@ def forward(self, c: torch.Tensor) -> torch.Tensor:
 
         Examples
         --------
-        >>> c = diffsptk.nrand(4)
-        >>> c
-        tensor([-0.1751,  0.1950, -0.3211,  0.3523, -0.5453])
-        >>> c2acr = diffsptk.CepstrumToAutocorrelation(4, 4, 16)
+        >>> import diffsptk
+        >>> import torch
+        >>> c2acr = diffsptk.CepstrumToAutocorrelation(4, 3)
+        >>> c = torch.tensor([0.5, -0.3, 0.2, -0.1, 0.05])
         >>> r = c2acr(c)
         >>> r
-        tensor([ 1.0672, -0.0485, -0.1564,  0.2666, -0.4551])
+        tensor([ 3.2404, -1.1920,  0.9037, -0.5838])
 
         """
         check_size(c.size(-1), self.in_dim, "dimension of cepstrum")

diffsptk/modules/c2mpir.py

@@ -61,11 +61,12 @@ def forward(self, c: torch.Tensor) -> torch.Tensor:
 
         Examples
         --------
-        >>> c = diffsptk.ramp(3)
-        >>> c2mpir = diffsptk.CepstrumToMinimumPhaseImpulseResponse(3, 5)
+        >>> import diffsptk
+        >>> c2mpir = diffsptk.CepstrumToMinimumPhaseImpulseResponse(4, 5)
+        >>> c = torch.tensor([0.5, -0.3, 0.2, -0.1, 0.05])
         >>> h = c2mpir(c)
         >>> h
-        tensor([1.0000, 1.0000, 2.5000, 5.1667, 6.0417])
+        tensor([ 1.6487, -0.4946,  0.4039, -0.2712,  0.1803])
 
         """
         check_size(c.size(-1), self.in_dim, "dimension of cepstrum")

diffsptk/modules/c2ndps.py

@@ -75,8 +75,9 @@ def forward(self, c: torch.Tensor) -> torch.Tensor:
 
         Examples
         --------
-        >>> c = diffsptk.ramp(4)
+        >>> import diffsptk
         >>> c2ndps = diffsptk.CepstrumToNegativeDerivativeOfPhaseSpectrum(4, 8)
+        >>> c = diffsptk.ramp(4)
         >>> n = c2ndps(c)
         >>> n
         tensor([ 30.0000, -21.6569,  12.0000, -10.3431,  10.0000])

diffsptk/modules/cdist.py

@@ -66,16 +66,14 @@ def forward(self, c1: torch.Tensor, c2: torch.Tensor) -> torch.Tensor:
 
         Examples
         --------
-        >>> c1 = diffsptk.nrand(2, 2)
-        tensor([[ 0.4296,  1.6517, -0.6022],
-                [-1.0464, -0.6088, -0.9274]])
-        >>> c2 = diffsptk.nrand(2, 2)
-        tensor([[ 1.6441, -0.6962, -0.2524],
-                [ 0.9344,  0.3965,  1.1494]])
-        >>> cdist = diffsptk.CepstralDistance()
+        >>> import diffsptk
+        >>> import torch
+        >>> cdist = diffsptk.CepstralDistance(reduction="none")
+        >>> c1 = torch.tensor([[ 0.4296,  1.6517], [-1.0464, -0.6088]])
+        >>> c2 = torch.tensor([[ 1.6441, -0.6962], [ 0.9344,  0.3965]])
         >>> distance = cdist(c1, c2)
         >>> distance
-        tensor(1.6551)
+        tensor([2.3479, 1.0053])
 
         """
         return self._forward(c1, c2, *self.values)

diffsptk/modules/chroma.py

@@ -85,14 +85,15 @@ def forward(self, x: torch.Tensor) -> torch.Tensor:
 
         Examples
         --------
-        >>> sr = 16000
-        >>> x = diffsptk.sin(500, period=sr/440)
+        >>> import diffsptk
+        >>> sample_rate = 16000
         >>> stft = diffsptk.STFT(
         ...     frame_length=512, frame_period=512, fft_length=512, window="hanning"
         ... )
         >>> chroma = diffsptk.ChromaFilterBankAnalysis(
-        ...     fft_length=512, n_channel=12, sample_rate=sr
+        ...     fft_length=512, n_channel=12, sample_rate=sample_rate
         ... )
+        >>> x = diffsptk.sin(500, period=sample_rate / 440)
         >>> y = chroma(stft(x))
         >>> y
         tensor([[0.1146, 0.0574, 0.0457, 0.0468, 0.0519, 0.0789, 0.1736, 0.4285, 0.7416,

diffsptk/modules/cqt.py

@@ -274,11 +274,12 @@ def forward(self, x: torch.Tensor) -> torch.Tensor:
 
         Examples
         --------
-        >>> x = diffsptk.sin(99)
-        >>> cqt = diffsptk.CQT(100, 8000, n_bin=4)
+        >>> import diffsptk
+        >>> cqt = diffsptk.CQT(100, 8000, n_bin=4, res_type=None)
+        >>> x = diffsptk.sin(100 - 1)
         >>> c = cqt(x).abs()
         >>> c
-        tensor([[1.1259, 1.2069, 1.3008, 1.3885]])
+        tensor([[1.1231, 1.2045, 1.2976, 1.3867]])
 
         """
         x = self.early_downsample(x)

diffsptk/modules/csm2acr.py

@@ -71,16 +71,17 @@ def forward(self, c: torch.Tensor) -> torch.Tensor:
 
         Examples
         --------
-        >>> x = diffsptk.nrand(4)
+        >>> import diffsptk
         >>> acorr = diffsptk.Autocorrelation(5, 3)
         >>> acr2csm = diffsptk.AutocorrelationToCompositeSinusoidalModelCoefficients(3)
         >>> csm2acr = diffsptk.CompositeSinusoidalModelCoefficientsToAutocorrelation(3)
+        >>> x = diffsptk.ramp(4)
         >>> r = acorr(x)
         >>> r
-        tensor([ 8.8894, -0.1102, -4.1748,  0.7501])
+        tensor([30.0000, 20.0000, 11.0000,  4.0000])
         >>> r2 = csm2acr(acr2csm(r))
         >>> r2
-        tensor([ 8.8894, -0.1102, -4.1748,  0.7501])
+        tensor([30.0000, 20.0000, 11.0000,  4.0000])
 
         """
         check_size(c.size(-1), self.in_dim, "dimension of autocorrelation")

diffsptk/modules/dct.py

@@ -70,8 +70,9 @@ def forward(self, x: torch.Tensor) -> torch.Tensor:
 
         Examples
         --------
-        >>> x = diffsptk.ramp(3)
+        >>> import diffsptk
         >>> dct = diffsptk.DCT(4)
+        >>> x = diffsptk.ramp(3)
         >>> y = dct(x)
         >>> y
         tensor([ 3.0000, -2.2304,  0.0000, -0.1585])

diffsptk/modules/decimate.py

@@ -58,8 +58,9 @@ def forward(self, x: torch.Tensor) -> torch.Tensor:
 
         Examples
         --------
-        >>> x = diffsptk.ramp(9)
+        >>> import diffsptk
         >>> decimate = diffsptk.Decimation(3, start=1)
+        >>> x = diffsptk.ramp(9)
         >>> y = decimate(x)
         >>> y
         tensor([1., 4., 7.])