dsp/transform: new package and initial Hilbert transform

dsp/transform/hilbert_example_test.go

@@ -0,0 +1,56 @@
+// Copyright ©2024 The Gonum Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+package transform
+
+import (
+	"fmt"
+	"math/cmplx"
+)
+
+func ExampleHilbert_AnalyticSignal() {
+	// Samples is a set of real amplitudes that make up a signal.
+	samples := []float64{1, 0, 2, 0, 4, 0, 2, 0}
+
+	// Initialize a Hilbert transform and 'demodulate' to get the
+	// analytic signal.
+	// The result is the complex I/Q (In-Phase / Quadrature) demodulation
+	// of the input signal.
+	h := NewHilbert(len(samples))
+	iqSamples := h.AnalyticSignal(nil, samples)
+
+	// We can compute the instantaneous amplitude of the signal
+	// (or 'envelope') using absolute value. Analyzing the envelope
+	// is an easy way to measure changes in amplitude over time in a
+	// signal.
+	envelope := make([]float64, len(samples))
+	for ind, iq := range iqSamples {
+		envelope[ind] = cmplx.Abs(iq)
+	}
+
+	// We can also compute the instantaneous phase of each part of the
+	// signal using the 4-quadrant arc-tangent. With multiple samples,
+	// the instantaneous phase can be used to estimate instantaneous
+	// frequency of a signal.
+	phase := make([]float64, len(samples))
+	for ind, iq := range iqSamples {
+		phase[ind] = cmplx.Phase(iq)
+	}
+
+	for i, iq := range iqSamples {
+		fmt.Printf("ind=%d -> I=%.4f, Q=%.4f, envelope=%.4f, phase=%.4f\n",
+			i, real(iq), imag(iq), envelope[i], phase[i])
+	}
+
+	// Output:
+	//
+	// ind=0 -> I=1.0000, Q=0.0000, envelope=1.0000, phase=0.0000
+	// ind=1 -> I=-0.0000, Q=-0.8107, envelope=0.8107, phase=-1.5708
+	// ind=2 -> I=2.0000, Q=0.0000, envelope=2.0000, phase=0.0000
+	// ind=3 -> I=-0.0000, Q=-1.3107, envelope=1.3107, phase=-1.5708
+	// ind=4 -> I=4.0000, Q=0.0000, envelope=4.0000, phase=0.0000
+	// ind=5 -> I=0.0000, Q=1.3107, envelope=1.3107, phase=1.5708
+	// ind=6 -> I=2.0000, Q=0.0000, envelope=2.0000, phase=0.0000
+	// ind=7 -> I=0.0000, Q=0.8107, envelope=0.8107, phase=1.5708
+}