annotate scripts/signal/arma_rnd.m @ 30875:5d3faba0342e

doc: Ensure documentation lists output argument when it exists for all m-files. For new users of Octave it is best to show explicit calling forms in the documentation and to show a return argument when it exists. * bp-table.cc, shift.m, accumarray.m, accumdim.m, bincoeff.m, bitcmp.m, bitget.m, bitset.m, blkdiag.m, celldisp.m, cplxpair.m, dblquad.m, flip.m, fliplr.m, flipud.m, idivide.m, int2str.m, interpft.m, logspace.m, num2str.m, polyarea.m, postpad.m, prepad.m, randi.m, repmat.m, rng.m, rot90.m, rotdim.m, structfun.m, triplequad.m, uibuttongroup.m, uicontrol.m, uipanel.m, uipushtool.m, uitoggletool.m, uitoolbar.m, waitforbuttonpress.m, help.m, __additional_help_message__.m, hsv.m, im2double.m, im2frame.m, javachk.m, usejava.m, argnames.m, char.m, formula.m, inline.m, __vectorize__.m, findstr.m, flipdim.m, strmatch.m, vectorize.m, commutation_matrix.m, cond.m, cross.m, duplication_matrix.m, expm.m, orth.m, rank.m, rref.m, trace.m, vech.m, cast.m, compare_versions.m, delete.m, dir.m, fileattrib.m, grabcode.m, gunzip.m, inputname.m, license.m, list_primes.m, ls.m, mexext.m, movefile.m, namelengthmax.m, nargoutchk.m, nthargout.m, substruct.m, swapbytes.m, ver.m, verLessThan.m, what.m, fminunc.m, fsolve.m, fzero.m, optimget.m, __fdjac__.m, matlabroot.m, savepath.m, campos.m, camroll.m, camtarget.m, camup.m, camva.m, camzoom.m, clabel.m, diffuse.m, legend.m, orient.m, rticks.m, specular.m, thetaticks.m, xlim.m, xtickangle.m, xticklabels.m, xticks.m, ylim.m, ytickangle.m, yticklabels.m, yticks.m, zlim.m, ztickangle.m, zticklabels.m, zticks.m, ellipsoid.m, isocolors.m, isonormals.m, stairs.m, surfnorm.m, __actual_axis_position__.m, __pltopt__.m, close.m, graphics_toolkit.m, pan.m, print.m, printd.m, __ghostscript__.m, __gnuplot_print__.m, __opengl_print__.m, rotate3d.m, subplot.m, zoom.m, compan.m, conv.m, poly.m, polyaffine.m, polyder.m, polyint.m, polyout.m, polyreduce.m, polyvalm.m, roots.m, prefdir.m, prefsfile.m, profexplore.m, profexport.m, profshow.m, powerset.m, unique.m, arch_rnd.m, arma_rnd.m, autoreg_matrix.m, bartlett.m, blackman.m, detrend.m, durbinlevinson.m, fftconv.m, fftfilt.m, fftshift.m, fractdiff.m, hamming.m, hanning.m, hurst.m, ifftshift.m, rectangle_lw.m, rectangle_sw.m, triangle_lw.m, sinc.m, sinetone.m, sinewave.m, spectral_adf.m, spectral_xdf.m, spencer.m, ilu.m, __sprand__.m, sprand.m, sprandn.m, sprandsym.m, treelayout.m, beta.m, betainc.m, betaincinv.m, betaln.m, cosint.m, expint.m, factorial.m, gammainc.m, gammaincinv.m, lcm.m, nthroot.m, perms.m, reallog.m, realpow.m, realsqrt.m, sinint.m, hadamard.m, hankel.m, hilb.m, invhilb.m, magic.m, pascal.m, rosser.m, toeplitz.m, vander.m, wilkinson.m, center.m, corr.m, cov.m, discrete_cdf.m, discrete_inv.m, discrete_pdf.m, discrete_rnd.m, empirical_cdf.m, empirical_inv.m, empirical_pdf.m, empirical_rnd.m, kendall.m, kurtosis.m, mad.m, mean.m, meansq.m, median.m, mode.m, moment.m, range.m, ranks.m, run_count.m, skewness.m, spearman.m, statistics.m, std.m, base2dec.m, bin2dec.m, blanks.m, cstrcat.m, deblank.m, dec2base.m, dec2bin.m, dec2hex.m, hex2dec.m, index.m, regexptranslate.m, rindex.m, strcat.m, strjust.m, strtrim.m, strtrunc.m, substr.m, untabify.m, __have_feature__.m, __prog_output_assert__.m, __run_test_suite__.m, example.m, fail.m, asctime.m, calendar.m, ctime.m, date.m, etime.m: Add return arguments to @deftypefn macros where they were missing. Rename variables in functions (particularly generic "retval") to match documentation. Rename some return variables for (hopefully) better clarity (e.g., 'ax' to 'hax' to indicate it is a graphics handle to an axes object).
author Rik <rik@octave.org>
date Wed, 30 Mar 2022 20:40:27 -0700
parents 796f54d4ddbf
children 597f3ee61a48
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
27923
bd51beb6205e update formatting of copyright notices
John W. Eaton <jwe@octave.org>
parents: 27919
diff changeset
1 ########################################################################
bd51beb6205e update formatting of copyright notices
John W. Eaton <jwe@octave.org>
parents: 27919
diff changeset
2 ##
30564
796f54d4ddbf update Octave Project Developers copyright for the new year
John W. Eaton <jwe@octave.org>
parents: 29359
diff changeset
3 ## Copyright (C) 1995-2022 The Octave Project Developers
27918
b442ec6dda5c use centralized file for copyright info for individual contributors
John W. Eaton <jwe@octave.org>
parents: 26376
diff changeset
4 ##
27923
bd51beb6205e update formatting of copyright notices
John W. Eaton <jwe@octave.org>
parents: 27919
diff changeset
5 ## See the file COPYRIGHT.md in the top-level directory of this
bd51beb6205e update formatting of copyright notices
John W. Eaton <jwe@octave.org>
parents: 27919
diff changeset
6 ## distribution or <https://octave.org/copyright/>.
3426
f8dde1807dee [project @ 2000-01-13 08:40:00 by jwe]
jwe
parents: 3191
diff changeset
7 ##
3922
38c61cbf086c [project @ 2002-05-01 06:48:35 by jwe]
jwe
parents: 3457
diff changeset
8 ## This file is part of Octave.
38c61cbf086c [project @ 2002-05-01 06:48:35 by jwe]
jwe
parents: 3457
diff changeset
9 ##
24534
194eb4bd202b maint: Update punctuation for GPL v3 license text.
Rik <rik@octave.org>
parents: 23220
diff changeset
10 ## Octave is free software: you can redistribute it and/or modify it
3922
38c61cbf086c [project @ 2002-05-01 06:48:35 by jwe]
jwe
parents: 3457
diff changeset
11 ## under the terms of the GNU General Public License as published by
24534
194eb4bd202b maint: Update punctuation for GPL v3 license text.
Rik <rik@octave.org>
parents: 23220
diff changeset
12 ## the Free Software Foundation, either version 3 of the License, or
22755
3a2b891d0b33 maint: Standardize Copyright formatting.
Rik <rik@octave.org>
parents: 22323
diff changeset
13 ## (at your option) any later version.
3426
f8dde1807dee [project @ 2000-01-13 08:40:00 by jwe]
jwe
parents: 3191
diff changeset
14 ##
3922
38c61cbf086c [project @ 2002-05-01 06:48:35 by jwe]
jwe
parents: 3457
diff changeset
15 ## Octave is distributed in the hope that it will be useful, but
3191
e4f4b2d26ee9 [project @ 1998-10-23 05:43:59 by jwe]
jwe
parents:
diff changeset
16 ## WITHOUT ANY WARRANTY; without even the implied warranty of
22755
3a2b891d0b33 maint: Standardize Copyright formatting.
Rik <rik@octave.org>
parents: 22323
diff changeset
17 ## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
3a2b891d0b33 maint: Standardize Copyright formatting.
Rik <rik@octave.org>
parents: 22323
diff changeset
18 ## GNU General Public License for more details.
3426
f8dde1807dee [project @ 2000-01-13 08:40:00 by jwe]
jwe
parents: 3191
diff changeset
19 ##
3191
e4f4b2d26ee9 [project @ 1998-10-23 05:43:59 by jwe]
jwe
parents:
diff changeset
20 ## You should have received a copy of the GNU General Public License
7016
93c65f2a5668 [project @ 2007-10-12 06:40:56 by jwe]
jwe
parents: 6046
diff changeset
21 ## along with Octave; see the file COPYING. If not, see
24534
194eb4bd202b maint: Update punctuation for GPL v3 license text.
Rik <rik@octave.org>
parents: 23220
diff changeset
22 ## <https://www.gnu.org/licenses/>.
27923
bd51beb6205e update formatting of copyright notices
John W. Eaton <jwe@octave.org>
parents: 27919
diff changeset
23 ##
bd51beb6205e update formatting of copyright notices
John W. Eaton <jwe@octave.org>
parents: 27919
diff changeset
24 ########################################################################
3191
e4f4b2d26ee9 [project @ 1998-10-23 05:43:59 by jwe]
jwe
parents:
diff changeset
25
3449
858695b3ed62 [project @ 2000-01-18 04:08:59 by jwe]
jwe
parents: 3426
diff changeset
26 ## -*- texinfo -*-
30875
5d3faba0342e doc: Ensure documentation lists output argument when it exists for all m-files.
Rik <rik@octave.org>
parents: 30564
diff changeset
27 ## @deftypefn {} {@var{x} =} arma_rnd (@var{a}, @var{b}, @var{v}, @var{t}, @var{n})
20165
f1d0f506ee78 doc: Update more docstrings to have one sentence summary as first line.
Rik <rik@octave.org>
parents: 19833
diff changeset
28 ## Return a simulation of the ARMA model.
f1d0f506ee78 doc: Update more docstrings to have one sentence summary as first line.
Rik <rik@octave.org>
parents: 19833
diff changeset
29 ##
f1d0f506ee78 doc: Update more docstrings to have one sentence summary as first line.
Rik <rik@octave.org>
parents: 19833
diff changeset
30 ## The ARMA model is defined by
3449
858695b3ed62 [project @ 2000-01-18 04:08:59 by jwe]
jwe
parents: 3426
diff changeset
31 ##
858695b3ed62 [project @ 2000-01-18 04:08:59 by jwe]
jwe
parents: 3426
diff changeset
32 ## @example
9051
1bf0ce0930be Grammar check TexInfo in all .m files
Rik <rdrider0-list@yahoo.com>
parents: 8920
diff changeset
33 ## @group
1bf0ce0930be Grammar check TexInfo in all .m files
Rik <rdrider0-list@yahoo.com>
parents: 8920
diff changeset
34 ## x(n) = a(1) * x(n-1) + @dots{} + a(k) * x(n-k)
1bf0ce0930be Grammar check TexInfo in all .m files
Rik <rdrider0-list@yahoo.com>
parents: 8920
diff changeset
35 ## + e(n) + b(1) * e(n-1) + @dots{} + b(l) * e(n-l)
1bf0ce0930be Grammar check TexInfo in all .m files
Rik <rdrider0-list@yahoo.com>
parents: 8920
diff changeset
36 ## @end group
3449
858695b3ed62 [project @ 2000-01-18 04:08:59 by jwe]
jwe
parents: 3426
diff changeset
37 ## @end example
3191
e4f4b2d26ee9 [project @ 1998-10-23 05:43:59 by jwe]
jwe
parents:
diff changeset
38 ##
3449
858695b3ed62 [project @ 2000-01-18 04:08:59 by jwe]
jwe
parents: 3426
diff changeset
39 ## @noindent
20165
f1d0f506ee78 doc: Update more docstrings to have one sentence summary as first line.
Rik <rik@octave.org>
parents: 19833
diff changeset
40 ## in which @var{k} is the length of vector @var{a}, @var{l} is the length of
20181
aa36fb998a4d maint: Remove unnecessary whitespace at end of lines.
Rik <rik@octave.org>
parents: 20165
diff changeset
41 ## vector @var{b} and @var{e} is Gaussian white noise with variance @var{v}.
20165
f1d0f506ee78 doc: Update more docstrings to have one sentence summary as first line.
Rik <rik@octave.org>
parents: 19833
diff changeset
42 ## The function returns a vector of length @var{t}.
3191
e4f4b2d26ee9 [project @ 1998-10-23 05:43:59 by jwe]
jwe
parents:
diff changeset
43 ##
20165
f1d0f506ee78 doc: Update more docstrings to have one sentence summary as first line.
Rik <rik@octave.org>
parents: 19833
diff changeset
44 ## The optional parameter @var{n} gives the number of dummy @var{x}(@var{i})
f1d0f506ee78 doc: Update more docstrings to have one sentence summary as first line.
Rik <rik@octave.org>
parents: 19833
diff changeset
45 ## used for initialization, i.e., a sequence of length @var{t}+@var{n} is
f1d0f506ee78 doc: Update more docstrings to have one sentence summary as first line.
Rik <rik@octave.org>
parents: 19833
diff changeset
46 ## generated and @var{x}(@var{n}+1:@var{t}+@var{n}) is returned. If @var{n}
f1d0f506ee78 doc: Update more docstrings to have one sentence summary as first line.
Rik <rik@octave.org>
parents: 19833
diff changeset
47 ## is omitted, @var{n} = 100 is used.
3449
858695b3ed62 [project @ 2000-01-18 04:08:59 by jwe]
jwe
parents: 3426
diff changeset
48 ## @end deftypefn
3426
f8dde1807dee [project @ 2000-01-13 08:40:00 by jwe]
jwe
parents: 3191
diff changeset
49
28789
28de41192f3c Eliminate unneeded verification of nargin, nargout in m-files.
Rik <rik@octave.org>
parents: 27984
diff changeset
50 function x = arma_rnd (a, b, v, t, n = 100)
3191
e4f4b2d26ee9 [project @ 1998-10-23 05:43:59 by jwe]
jwe
parents:
diff changeset
51
28789
28de41192f3c Eliminate unneeded verification of nargin, nargout in m-files.
Rik <rik@octave.org>
parents: 27984
diff changeset
52 if (nargin < 4)
6046
34f96dd5441b [project @ 2006-10-10 16:10:25 by jwe]
jwe
parents: 5568
diff changeset
53 print_usage ();
5568
e9cde940b271 [project @ 2005-12-08 02:28:22 by jwe]
jwe
parents: 5307
diff changeset
54 endif
3191
e4f4b2d26ee9 [project @ 1998-10-23 05:43:59 by jwe]
jwe
parents:
diff changeset
55
5568
e9cde940b271 [project @ 2005-12-08 02:28:22 by jwe]
jwe
parents: 5307
diff changeset
56 if ((min (size (a)) > 1) || (min (size (b)) > 1))
11472
1740012184f9 Use uppercase for variable names in error() strings to match Info documentation. Only m-files done.
Rik <octave@nomad.inbox5.com>
parents: 10483
diff changeset
57 error ("arma_rnd: A and B must not be matrices");
5568
e9cde940b271 [project @ 2005-12-08 02:28:22 by jwe]
jwe
parents: 5307
diff changeset
58 endif
3426
f8dde1807dee [project @ 2000-01-13 08:40:00 by jwe]
jwe
parents: 3191
diff changeset
59
19833
9fc020886ae9 maint: Clean up m-files to follow Octave coding conventions.
Rik <rik@octave.org>
parents: 19697
diff changeset
60 if (! isscalar (t))
11472
1740012184f9 Use uppercase for variable names in error() strings to match Info documentation. Only m-files done.
Rik <octave@nomad.inbox5.com>
parents: 10483
diff changeset
61 error ("arma_rnd: T must be a scalar");
5568
e9cde940b271 [project @ 2005-12-08 02:28:22 by jwe]
jwe
parents: 5307
diff changeset
62 endif
3426
f8dde1807dee [project @ 2000-01-13 08:40:00 by jwe]
jwe
parents: 3191
diff changeset
63
28789
28de41192f3c Eliminate unneeded verification of nargin, nargout in m-files.
Rik <rik@octave.org>
parents: 27984
diff changeset
64 if (! isscalar (n))
28de41192f3c Eliminate unneeded verification of nargin, nargout in m-files.
Rik <rik@octave.org>
parents: 27984
diff changeset
65 error ("arma_rnd: N must be a scalar");
28de41192f3c Eliminate unneeded verification of nargin, nargout in m-files.
Rik <rik@octave.org>
parents: 27984
diff changeset
66 endif
28de41192f3c Eliminate unneeded verification of nargin, nargout in m-files.
Rik <rik@octave.org>
parents: 27984
diff changeset
67
5568
e9cde940b271 [project @ 2005-12-08 02:28:22 by jwe]
jwe
parents: 5307
diff changeset
68 ar = length (a);
e9cde940b271 [project @ 2005-12-08 02:28:22 by jwe]
jwe
parents: 5307
diff changeset
69 br = length (b);
3426
f8dde1807dee [project @ 2000-01-13 08:40:00 by jwe]
jwe
parents: 3191
diff changeset
70
5568
e9cde940b271 [project @ 2005-12-08 02:28:22 by jwe]
jwe
parents: 5307
diff changeset
71 a = reshape (a, ar, 1);
e9cde940b271 [project @ 2005-12-08 02:28:22 by jwe]
jwe
parents: 5307
diff changeset
72 b = reshape (b, br, 1);
3426
f8dde1807dee [project @ 2000-01-13 08:40:00 by jwe]
jwe
parents: 3191
diff changeset
73
8506
bc982528de11 comment style fixes
John W. Eaton <jwe@octave.org>
parents: 7017
diff changeset
74 ## Apply our notational convention.
bc982528de11 comment style fixes
John W. Eaton <jwe@octave.org>
parents: 7017
diff changeset
75 a = [1; -a];
5568
e9cde940b271 [project @ 2005-12-08 02:28:22 by jwe]
jwe
parents: 5307
diff changeset
76 b = [1; b];
e9cde940b271 [project @ 2005-12-08 02:28:22 by jwe]
jwe
parents: 5307
diff changeset
77
e9cde940b271 [project @ 2005-12-08 02:28:22 by jwe]
jwe
parents: 5307
diff changeset
78 n = min (n, ar + br);
3191
e4f4b2d26ee9 [project @ 1998-10-23 05:43:59 by jwe]
jwe
parents:
diff changeset
79
5568
e9cde940b271 [project @ 2005-12-08 02:28:22 by jwe]
jwe
parents: 5307
diff changeset
80 e = sqrt (v) * randn (t + n, 1);
e9cde940b271 [project @ 2005-12-08 02:28:22 by jwe]
jwe
parents: 5307
diff changeset
81
e9cde940b271 [project @ 2005-12-08 02:28:22 by jwe]
jwe
parents: 5307
diff changeset
82 x = filter (b, a, e);
e9cde940b271 [project @ 2005-12-08 02:28:22 by jwe]
jwe
parents: 5307
diff changeset
83 x = x(n + 1 : t + n);
3191
e4f4b2d26ee9 [project @ 1998-10-23 05:43:59 by jwe]
jwe
parents:
diff changeset
84
e4f4b2d26ee9 [project @ 1998-10-23 05:43:59 by jwe]
jwe
parents:
diff changeset
85 endfunction