home *** CD-ROM | disk | FTP | other *** search
/ QBasic & Borland Pascal & C / Delphi5.iso / C / Samples / CRNCHR22.ARJ / CRUNCH22.DOC < prev    next >
Encoding:
Text File  |  1993-04-14  |  16.5 KB  |  558 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.           __________________________________________________
  11.  
  12.                              CRUNCHER (v2.2)
  13.           __________________________________________________
  14.  
  15.               Copyright 1992, 1993 by Gene V. Wallenstein
  16.                           All rights reserved.
  17.  
  18.                         Last revision: 04/10/93
  19.  
  20.                                    -
  21.  
  22.  
  23.                   Software for Science and Engineering
  24.  
  25.                     Gene V. Wallenstein
  26.                     5990 Pine Cone Court #406d1
  27.                     Lake Worth, Florida 33463 USA
  28.  
  29.                     CompuServe 75110,77
  30.                     Telephone  (407) 750-3527
  31.                     Internet - Wallenstein@Walt.ccs.fau.edu
  32.  
  33.  
  34.  
  35.  
  36.  
  37.  
  38.  
  39.  
  40.  
  41.  
  42.  
  43.  
  44.  
  45.  
  46.  
  47.  
  48.  
  49.  
  50.  
  51.  
  52.  
  53.  
  54.  
  55.  
  56.  
  57.  
  58.  
  59.  
  60.  
  61.  
  62.  
  63.  
  64.  
  65. 1.  Introduction and System Requirements
  66.  
  67. The CRUNCHER is a series of signal processing routines written for C
  68. programmers. The libraries can be linked with both Borland and Microsoft
  69. code and come in a number of memory sizes. The following routines are
  70. included in the CRUNCHER:
  71.  
  72. 1)  Fast Fourier Transform (FFT)
  73. 2)  Wavelet Transform
  74. 3)  Coherence Analysis
  75. 4)  Autocovariance
  76. 5)  Crosscovariance
  77. 6)  Spectral Analysis
  78. 7)  Cross Spectral Analysis
  79. 8)  Linear Regression
  80. 9)  Moments Analysis
  81. 10) Digital Filtering of data
  82. 11) Wigner-Ville Transform
  83.  
  84.  
  85. 2.  Registration
  86.  
  87. The CRUNCHER is distributed through a unique marketing
  88. concept
  89. called "shareware". The idea behind shareware is that you
  90. get the software and try it for a short grace period and if
  91. you intend to use it beyond that you register your copy with
  92. the author. The entire concept is based on an honor system
  93. among programmers and users, which has led to an outstanding
  94. base of high quality software without the high price usually
  95. associated with it. Also, shareware users are in the unique
  96. position of being able to contact the authors of the
  97. software they are using and get direct support in the form
  98. of manuals, phone help, and possible further customization
  99. of the software. Please read the list of added features you
  100. will receive when you become a registered user of the
  101. CRUNCHER.
  102.  
  103. 2.1.1.  Source code
  104.  
  105. All registered users get complete source code for the
  106. CRUNCHER.
  107.  
  108. 2.1.2.  Free updates
  109.  
  110. Regstered users pay once and get all updates free. The only
  111. charge is
  112. for postage and handling. There are NO EXTRA COSTS.
  113.  
  114. 2.1.3.  User's Manual and Tutorial
  115.  
  116. A laser-printed user's manual and tutorial which is actually
  117. and expanded version of section 3 of this file will be given
  118. to all registered users. This manual includes various
  119. examples of data analysis and explains which techniques are
  120. best in certain circumstances and the type of information
  121. which can be obtained from such methods.
  122.  
  123. 2.1.4.  Direct Support
  124.  
  125. All registered users of the CRUNCHER will receive full
  126. support
  127. either over the telephone, internet, or via the regular
  128. mail, by using one of the contact points on the cover of
  129. this document. This information is also listed on the first
  130. information screen of the demo program as well.
  131.  
  132. 2.1.5.  Royalty free
  133.  
  134. Registered users of the CRUNCHER pay no additional
  135. royalties.
  136.  
  137.  
  138. 2.2.  Legal Stuff
  139.  
  140. 1)  License - The user is granted the right (and encouraged)
  141. to copy this unregistered version and distribute it with no
  142. charge assuming it is unaltered. The user is also granted a
  143. grace period of 30 days in which to decide to register the
  144. software or not. During this grace period the software may
  145. be used free of charge.
  146.  
  147. 2)  Copyright - The CRUNCHER is protected under United
  148. States
  149. copyright law and international treaty provisions. Copyright
  150. 1993 by Gene V. Wallenstein; All rights reserved.
  151.  
  152. 3)  Reverse Engineering - Any form of reverse engineering
  153. such as reverse compiling or disassembly is strictly
  154. prohibited.
  155.  
  156. 4)  Disclaimer of Warranty - This software and manual are
  157. distributed "as is" and without warranties as to performance
  158. of merchantability or any other warranties whether expressed
  159. or implied. Because of the various hardware and software
  160. environments into which this program may be placed, no
  161. warranty of fitness for a particular purpose is offered.
  162. Good data processing procedure dictates that any program be
  163. thoroughly tested with non-critical data before relying on
  164. it. The user must assume the entire risk of using the
  165. program. Any liability of the seller will be limited
  166. exclusively to product replacement or refund of purchase
  167. price.
  168.  
  169.  
  170. 3.  Here are SOME of the CRUNCHER's Tools
  171.  
  172. The following is a brief description of the tools used by
  173. the CRUNCHER. It is by no means exhaustive in its
  174. description
  175. but is merely intended to get the reader "up and running". A
  176. more detailed description of the techniques as well as a
  177. tutorial is provided to registered users (section 2.1.).
  178.  
  179. 3.1.  Fast Fourier Transform (FFT)
  180.  
  181. The Fast Fourier Transform (FFT) is a technique used to
  182. locate regularities in a data set. It is a way of
  183. representing a very complicated data pattern in terms of its
  184. linear projection onto sinusoids of various frequency. Thus
  185. the data can be seen as the sum of many simple periodic
  186. patterns each with a specific frequency.
  187.  
  188. A second quantity which can be derived from the FFT is the
  189. phase angle. Since the original signal can be represented as
  190. a sum of periodic patterns, it may be important to know the
  191. temporal relationship among each of the simpler patterns.
  192. That is, if they are time-shifted with respect to one
  193. another or not. The PHASE SPECTRUM tells the user the phase
  194. angle at each frequency. Generally, the user is only
  195. interested in those frequencies containing relatively large
  196. amounts of the total power in the spectrum. Therefore,
  197. one may compare for instance the phase angle for numerous
  198. data sets at a specific frequency and its higher harmonics.
  199.  
  200. In general, the FFT is a good method to decompose a data set
  201. which has multiple frequencies embedded in it.
  202.  
  203. 3.2.  Wavelet Analysis
  204.  
  205. Wavelet analysis is fairly new to mainstream signal
  206. processing. It is a projective technique similar to the FFT,
  207. however, rather than simply decomposing the signal into
  208. sinusoids of varying frequency, the data is represented as
  209. projections onto the affine group (translations and
  210. dilations). This means the data set can be represented as
  211. time translations of the mother wavelet (a basis function)
  212. and/or time dilations (i.e. shrinking or expanding the time
  213. scale of observation). The CRUNCHER uses what is called the
  214. Mexican Hat as the mother wavelet (the function looks like a
  215. slice through a sombrero).
  216.  
  217. Typically, wavelet analysis is an excellent method for
  218. locating short-lived, high frequency patterns. This is
  219. because it avoids the time vs. frequency resolution problem
  220. inherent in Fourier analysis.
  221.  
  222. 3.3.  Autocovariance
  223.  
  224. The autocovariance function of a signal is a time dependent
  225. plot of the correlation of the signal with itself at
  226. different time lags. If the signal is periodic, the
  227. autocovariance of the signal will also be. Following this, a
  228. time lag of
  229. one point is introduced each time a correlation is computed
  230. until the
  231. final lag of (n-1) time points.
  232.  
  233. Another use for the autocovariance is to see where the
  234. signal loses all correlation with itself (i.e. Markov
  235. processes). This can be seen as the first zero crossing of
  236. the autocovariance. Consequently, even a periodic signal
  237. will have a zero crossing in the autocovariance function.
  238. By examing the autocovariance function of a signal, one can
  239. tell when in time the signal is correlated with itself and
  240. to what degree.
  241.  
  242. 3.4.  Crosscovariance
  243.  
  244. The crosscovariance is similar to the autocovariance
  245. function except it describes the correlation between two
  246. signals shifted in time.
  247.  
  248. 3.5.  Coherence Analysis
  249.  
  250. Coherence is a frequency dependent measure which quantifies
  251. the magnitude of shared power between two signals. A high
  252. coherence
  253. value indicates the two signals have a high concentration of
  254. power at
  255. that specific frequency.
  256.  
  257. A second quantity of the coherence measure is the relative
  258. phase angle between the two signals at a given frequency.
  259. The measure of relative phase between two signals yields
  260. information about the synchrony of the signals at a specific
  261. frequency. The two signals may be in perfect synchrony (a
  262. relative phase of 0 degrees) or be exactly out of phase or
  263. perfect syncopation (180 degrees). This analysis provides a
  264. means of quantifying the relative degree of synchrony
  265. between any two signals at each of the frequencies of
  266. interest.
  267.  
  268.  
  269. 3.6.  Moments Analysis
  270.  
  271. This module returns the first four moments of the data set
  272. (the mean, variance, skew, and kurtosis). This information
  273. is of use
  274. when attempting to get a general feel for the data set and
  275. its characteristics. The information can also of course be
  276. used as a means to statistically quantify the data set in
  277. comparison with other data.
  278.  
  279. 3.7.  Wigner-Ville Analysis
  280.  
  281. The Wigner-Ville method of analysis is a technique which has
  282. similarities to both the FFT and Wavelet methods. It is a
  283. projection of a data signal onto a family of sinusoids as
  284. is the case of the FFT, however, it also depends on time
  285. translations of the signal. The Wigner-Ville method is
  286. particularly good at uncovering periodic patterns in data
  287. sets where the signal is not stationary (i.e. the data may
  288. have a strong trend). By using the Wigner-Ville analysis,
  289. the data signal can be decomposed into its frequency
  290. components which are of varying temporal duration.
  291.  
  292. 3.8.  Digital Filtering
  293.  
  294. The digital filtering routine in the CRUNCHER is a general
  295. purpose tool for filtering data sets at prescribed band
  296. widths. For example, if the user wishes to create a new data
  297. signal consisting of only the 8.0 to 12.0 Hz frequency
  298. components, one simply needs to specify the high-pass (8.0),
  299. the low-pass (12.0), and the sampling rate of the original
  300. data set. The resulting output can be viewed and sent to a
  301. file for further analysis. Digital filtering is often the
  302. best way to "clean up" a signal so that its true structure
  303. can be viewed more easily. This, for example, is often the
  304. case when the signal contains a large amount of higher
  305. frequency noise. The user wishing to get rid of this could
  306. simply use this module and set the high-pass to 0.0 Hz and
  307. the low-pass setting to whatever is sufficient to eliminate
  308. the "noise". However, caution must obviously be taken when
  309. deciding what does and does not constitute noise in a
  310. signal.
  311.  
  312. 3.9   Linear Regression
  313.  
  314. This routine finds a linear equation from a data set by
  315. minimizing the squared norm between the data and the fit. It
  316. returns the coefficients to y = ax + b.
  317.  
  318. 4.0   Linking the Libraries
  319.  
  320. Here are the procedures for doing command-line linking for a
  321. program entitled MYPROG using the small model library. You
  322. must of course use the correct path when calling these various libraries
  323. however. If you encounter any problems using these command-line linkers,
  324. please contact me and I will send you the object files you need so that
  325. you can add them to an already existing library.
  326.  
  327.     Borland:
  328.  
  329.       tlink /c c0s myprog,myprog,myprog,bortc_s emu maths cs
  330.  
  331.     Microsoft:
  332.  
  333.       link myprog,myprog,,msc7_s
  334.  
  335.  
  336. 5.0   Quick Reference and Structure of the Routines
  337. __________________________________________________
  338.  
  339.      C R U N C H E R   Version 2.2
  340.  
  341.      --- Quick Reference ---
  342.  
  343.      Copyright 1992,1993 by Gene V. Wallenstein
  344.      All rights reserved.
  345. __________________________________________________
  346.  
  347. Below is a brief listing and description of the routines
  348. supplied in the CRUNCHER v2.2
  349.  
  350.  
  351. (1) Fast Fourier Transform (FFT)
  352.  
  353.      --- fft.c ---
  354.  
  355. /* Returns the real and imaginary parts of the signal via a
  356. Fourier transform. */
  357.  
  358. float
  359. fft(float *data,float *real,float *imag,int ipts,float rate)
  360. {
  361. /*
  362.      *data -- is a pointer to the incoming file.
  363.      *real -- is a pointer to the real components.
  364.      *imag -- is a pointer to the imaginary components.
  365.      ipts  -- the number of points in the incoming file.
  366.      rate  -- is the sampling rate of the data.
  367. */
  368.  
  369. (2) Coherence Analysis
  370.  
  371.      --- cohere.c ---
  372.  
  373. /* Cohere (normalized cross spectrum) calculates the
  374. coherence or "normalized shared power" between two signals.
  375. The phase is the relative phase between the two signals. */
  376.  
  377. float
  378. cohere(float *data1,float *data2,float *out,int ipts,float
  379. rate,int iflag)
  380. {
  381. /*
  382.      *data1 -- pointer to the 1st data file.
  383.      *data2 -- pointer to the 2nd data file.
  384.      *out   -- pointer to the results file.
  385.      ipts   -- the number of points in each data file.
  386.      rate   -- the sampling rate.
  387.      iflag  -- 0 for the cross power
  388.                1 for the relative phase.
  389. */
  390.  
  391. (3) Spectral Analysis
  392.  
  393.      --- spectrum.c ---
  394.  
  395. /* Returns the power spectral density or phase depending on
  396. IFLAG. */
  397.  
  398. float
  399. spectrum(float *data,float *out,int ipts,float rate,int
  400. iflag,int win)
  401. {
  402. /*
  403.      *data -- is a pointer to the incoming file.
  404.      *out  -- is a pointer to the results file.
  405.      ipts  -- the number of points in the incoming file.
  406.      rate  -- is the sampling rate of the data.
  407.      iflag -- 0 for POWER
  408.               1 for PHASE.
  409.      win   -- 0 for no window
  410.               1 for Hanning window.
  411. */
  412.  
  413. (4) Cross Covariance Analysis
  414.  
  415.      --- crosscov.c ---
  416.  
  417. /* Returns the crosscovariance of two signals. */
  418.  
  419. float
  420. crosscov(float *data1,float *data2,float *out,int ipts)
  421. {
  422. /*
  423.      *data1 -- pointer to the 1st data file.
  424.      *data2 -- pointer to the 2nd data file.
  425.      *out   -- pointer to the results file.
  426.      ipts   -- number of points in each data file.
  427. */
  428.  
  429. (5) Auto Covariance Analysis
  430.  
  431.      --- autocov.c ---
  432.  
  433. /* Returns the autocovariance of a signal. */
  434.  
  435. float
  436. autocov(float *data,float *out,int ipts)
  437. {
  438. /*
  439.      *data -- pointer to the data file.
  440.      *out  -- pointer to the results file.
  441.      ipts  -- number of points in the data file.
  442. */
  443.  
  444. (6) Digital Filter
  445.  
  446.      --- filter.c ---
  447.  
  448. /* A digital filter routine. The user specifies a center
  449. band. */
  450.  
  451. float
  452. filter(float *data,float *out,int ipts,float rate,float
  453. freq)
  454. {
  455. /*
  456.      *data -- is a pointer to the data file.
  457.      *out  -- is a pointer to the results file.
  458.      ipts  -- is the number of points in the data file.
  459.      rate  -- is the sampling rate of the data file.
  460.      freq  -- is the center band of the filter.
  461. */
  462.  
  463. (7) Cross Spectral Analysis
  464.  
  465.      --- crossspc.c ---
  466.  
  467. /* Crossspc (cross spectrum) calculates the cross spectrum
  468. or "shared power" between two signals. The phase is the
  469. relative phase between the two signals. */
  470.  
  471. float
  472. crossspc(float *data1,float *data2,float *out,int ipts,float
  473. rate,int iflag)
  474. {
  475. /*
  476.      *data1 -- pointer to the 1st data file.
  477.      *data2 -- pointer to the 2nd data file.
  478.      *out   -- pointer to the results file.
  479.      ipts   -- the number of points in each data file.
  480.      rate   -- the sampling rate.
  481.      iflag  -- 0 for the cross power
  482.                1 for the relative phase.
  483. */
  484.  
  485. (8) Moments Analysis
  486.  
  487.      --- moments.c ---
  488.  
  489. /* Moments calculates the first four moments from a user-
  490. supplied data signal. */
  491.  
  492. float
  493. moments(float *data,float *out,int ipts)
  494. {
  495. /*
  496.      *data -- is a pointer to the data file.
  497.      *out  -- is a pointer to the results file.
  498.               *(out+1) = mean
  499.               *(out+2) = variance
  500.               *(out+3) = skew
  501.               *(out+4) = kurtosis
  502.      ipts  -- is the number of points in the data file.
  503. */
  504.  
  505. (9) Wavelet Analysis
  506.  
  507.      --- wavelet.c ---
  508.  
  509. /* Returns the wavelet transform of a data file.
  510.  
  511. NOTE: DATA length must be an integer power of two (i.e.
  512. 2^n). */
  513.  
  514. float
  515. wavelet(float *data,float *out,int ipts)
  516. {
  517. /*
  518.      *data -- is a pointer to the incoming file.
  519.      *out  -- pointer to the transform results.
  520.      ipts  -- the number of points in the incoming file.
  521. */
  522.  
  523. (10) Wigner-Ville Transform
  524.  
  525.      --- wigvil.c ---
  526.  
  527. /* Wigner-Ville transform as a function of frequency and a
  528. user supplied delay time, t. */
  529.  
  530. float
  531. wigvil(float *data,float *out,float t,int ipts)
  532. {
  533. /*
  534.      *data -- pointer to the data file.
  535.      *out  -- pointer to the results file.
  536.      t     -- delay time.
  537.      ipts  -- Number of points in the data file.
  538. */
  539.  
  540. (11) Linear Regression and Modeling
  541.  
  542.      --- linear.c ---
  543.  
  544. /* Linear regression - returns the a and b values from a
  545. linear least squares fit of the data to an equation of the
  546. form y = a + bx. */
  547.  
  548. float
  549. linear(float *data,float *out,int ipts)
  550. {
  551. /*
  552.      *data  -- is a pointer to the incoming file.
  553.      ipts   -- the number of points in the incoming file.
  554.      *out+1 -- pointer to the a coefficient.
  555.      *out+2 -- pointer to the b coefficient.
  556. */
  557. 
  558.