changeset 614:27289d5ac615

maint: complete addition of db2pow and pow2db * db2pow.m: Overhaul doc string, rewrite for consistency. Add whitespace to conform to Octave coding style. Add another input validation test. * pow2db.m: Likewise. Rewrite input validation error message. * INDEX (Power Spectrum Analysis): Include them in the list. * NEWS: Mention them.
author Mike Miller <mtmiller@octave.org>
date Tue, 10 Apr 2018 10:27:00 -0700
parents 0cd7ec2d2509
children 92b5e43c8ff4 4ee231e1b4f5
files INDEX NEWS inst/db2pow.m inst/pow2db.m
diffstat 4 files changed, 44 insertions(+), 20 deletions(-) [+]
line wrap: on
line diff
--- a/INDEX	Tue Apr 10 09:24:00 2018 -0700
+++ b/INDEX	Tue Apr 10 10:27:00 2018 -0700
@@ -120,8 +120,10 @@
   cohere
   cpsd
   csd
+  db2pow
   mscohere
   pburg
+  pow2db
   pwelch
   pyulear
   tfe
--- a/NEWS	Tue Apr 10 09:24:00 2018 -0700
+++ b/NEWS	Tue Apr 10 10:27:00 2018 -0700
@@ -4,8 +4,10 @@
  ** The following new functions have been added to the signal package:
 
       cconv
+      db2pow
       peak2peak
       peak2rms
+      pow2db
       rms
       rssq
       shiftdata
--- a/inst/db2pow.m	Tue Apr 10 09:24:00 2018 -0700
+++ b/inst/db2pow.m	Tue Apr 10 10:27:00 2018 -0700
@@ -15,29 +15,38 @@
 ## <https://www.gnu.org/licenses/>.
 
 ## -*- texinfo -*-
-## @deftypefn {Function File} {@var{pow} =} db2pow (@var{db})
-## Convert dB value to its corresponding power value
+## @deftypefn {Function File} {} db2pow (@var{x})
+## Convert decibels (dB) to power.
 ##
-## @var{db} is the decibel value and @var{pow} is the corosponding power value
+## The power of @var{x} is defined as
+## @tex
+## $p = 10^{x/10}$.
+## @end tex
+## @ifnottex
+## @var{p} = @code{10 ^ (x/10)}.
+## @end ifnottex
+##
+## If @var{x} is a vector, matrix, or N-dimensional array, the power is
+## computed over the elements of @var{x}.
 ##
 ## Example:
 ##
 ## @example
 ## @group
-## db2pow([-10, 0, 10])
+## db2pow ([-10, 0, 10])
 ## @result{} 0.10000 1.00000 10.00000
 ## @end group
 ## @end example
 ## @seealso{pow2db}
 ## @end deftypefn
 
-function pow = db2pow (db)
+function y = db2pow (x)
 
   if (nargin != 1)
     print_usage ();
   endif
 
-  pow = 10.^(db/10);
+  y = 10 .^ (x ./ 10);
 
 endfunction
 
@@ -45,8 +54,9 @@
 %!shared db
 %! db = [-10, 0, 10, 20, 25];
 
-%!assert (db2pow(db), [0.10000, 1.00000, 10.00000, 100.00000, 316.22777], 0.00001)
-%!assert (db2pow(db'), [0.10000; 1.00000; 10.00000; 100.00000; 316.22777], 0.00001)
+%!assert (db2pow (db), [0.10000, 1.00000, 10.00000, 100.00000, 316.22777], 0.00001)
+%!assert (db2pow (db'), [0.10000; 1.00000; 10.00000; 100.00000; 316.22777], 0.00001)
 
 ## Test input validation
 %!error db2pow ()
+%!error db2pow (1, 2)
--- a/inst/pow2db.m	Tue Apr 10 09:24:00 2018 -0700
+++ b/inst/pow2db.m	Tue Apr 10 10:27:00 2018 -0700
@@ -15,43 +15,53 @@
 ## <https://www.gnu.org/licenses/>.
 
 ## -*- texinfo -*-
-## @deftypefn {Function File} {@var{db} =} pow2db (@var{pow})
-## Convert power value to its corresponding dB value
+## @deftypefn {Function File} {} pow2db (@var{x})
+## Convert power to decibels (dB).
 ##
-## @var{pow} is the power value and @var{db} is the corosponding decibel value
+## The decibel value of @var{x} is defined as
+## @tex
+## $d = 10 * \log_{10} (x)$.
+## @end tex
+## @ifnottex
+## @var{d} = @code{10 * log10 (x)}.
+## @end ifnottex
+##
+## If @var{x} is a vector, matrix, or N-dimensional array, the decibel value
+## is computed over the elements of @var{x}.
 ##
 ## Examples:
 ##
 ## @example
 ## @group
-## pow2db([0, 10, 100])
+## pow2db ([0, 10, 100])
 ## @result{} -Inf 10 20
 ## @end group
 ## @end example
 ## @seealso{db2pow}
 ## @end deftypefn
 
-function db = pow2db (pow)
+function y = pow2db (x)
 
   if (nargin != 1)
     print_usage ();
   endif
 
-  if (sum (pow < 0) != 0)
-    error("pow2db: power values must be non-negative real values");
+  if (any (x < 0))
+    error ("pow2db: X must be non-negative");
   endif
 
-  db = 10 .* log10 (pow);
+  y = 10 .* log10 (x);
 
 endfunction
 
 %!shared pow
 %! pow = [0, 10, 20, 60, 100];
 
-%!assert (pow2db(pow), [-Inf, 10.000, 13.010, 17.782, 20.000], 0.01)
-%!assert (pow2db(pow'), [-Inf; 10.000; 13.010; 17.782; 20.000], 0.01)
+%!assert (pow2db (pow), [-Inf, 10.000, 13.010, 17.782, 20.000], 0.01)
+%!assert (pow2db (pow'), [-Inf; 10.000; 13.010; 17.782; 20.000], 0.01)
 
 ## Test input validation
 %!error pow2db ()
-%!error <pow2db: power values must be non-negative real values> pow2db(-5)
-%!error <pow2db: power values must be non-negative real values> pow2db([-5 7])
+%!error pow2db (1, 2)
+%!error <pow2db: X must be non-negative> pow2db (-5)
+%!error <pow2db: X must be non-negative> pow2db ([-5 7])