Editing Guide to madagascar programs (section)

==sfattr==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Display dataset attributes.
|-
! colspan="4" | sfattr < in.rsf lval=2 want=
|-
|  colspan="4" | <br>Sample output from "sfspike n1=100 | sfbandpass fhi=60 | sfattr"<br>*******************************************<br>rms =      0.992354<br>mean =      0.987576<br>2-norm =       9.92354<br>variance =    0.00955481<br>std dev =     0.0977487<br>max =       1.12735 at 97<br>min =      0.151392 at 100<br>nonzero samples = 100<br>total samples = 100<br>*******************************************<br><br>rms                = sqrt[ sum(data^2) / n ]<br>mean               = sum(data) / n<br>norm               = sum(abs(data)^lval)^(1/lval)<br>variance           = [ sum(data^2) - n*mean^2 ] / [ n-1 ]<br>standard deviation = sqrt [ variance ]
|-
| ''int    '' || '''lval=2''' ||   || 	norm option, lval is a non-negative integer, computes the vector lval-norm
|-
| ''string '' || '''want=''' ||   || 	'all'(default), 'rms', 'mean', 'norm', 'var', <br>       'std', 'max', 'min', 'nonzero', 'samples', 'short' 
:want=   'rms' displays the root mean square
:want=   'norm' displays the square norm, otherwise specified by lval.
:want=   'var' displays the variance
:want=   'std' displays the standard deviation
:want=   'nonzero' displays number of nonzero samples
:want=   'samples' displays total number of samples
:want=   'short' displays a short one-line version
|}


<tt>sfattr</tt> is a useful diagnostic program. It reports certain
statistical values for an RSF dataset: RMS (root-mean-square)
amplitude, mean value, vector norm value, variance, standard deviation,
maximum and minimum values, number of nonzero samples, and the total
number of samples.
If we denote data values as <math>d_i</math> for <math>i=0,1,2,\ldots,n</math>, then the RMS
value is <math>\sqrt{\frac{1}{n}\,\sum\limits_{i=0}^n d_i^2}</math>, the mean
value is <math>\frac{1}{n}\,\sum\limits_{i=0}^n d_i</math>, the <math>L_2</math>-norm value
is <math>\sqrt{\sum\limits_{i=0}^n d_i^2}</math>, the variance is
<math>\frac{1}{n-1}\,\left[\sum\limits_{i=0}^n d_i^2 - \frac{1}{n}\left(\sum\limits_{i=0}^n d_i\right)^2\right]</math>, and the standard
deviation is the square root of the variance. Using <tt>sfattr</tt> is a quick way to see the distribution of data values and check it for anomalies.

The output can be parsed using utilities such as <tt>awk</tt>, to extract only a numeric value for feeding it as a parameter value into a command line interface. Notice the backticks in the example below:
<syntaxhighlight lang="bash">
sfgrey <vel.rsf allpos=y bias=`sfattr <vel.rsf want=min | awk '{print $4}'` | sfpen
</syntaxhighlight>

====Implementation: [https://github.com/ahay/src/blob/master/system/main/attr.c system/main/attr.c]====

Computations start by finding the input data (<tt>in</tt>) size
(<tt>nsiz</tt>) and dimensions (<tt>dim</tt>).
<syntaxhighlight lang="c">
    dim = (size_t) sf_largefiledims (in,n);
    for (nsiz=1, i=0; i < dim; i++) {
	nsiz *= n[i];
    }
</syntaxhighlight>


In the main loop, we read the input data buffer by buffer.
<syntaxhighlight lang="c">
    for (nleft=nsiz; nleft > 0; nleft -= nbuf) {
	nbuf = (bufsiz < nleft)? bufsiz: nleft;
	switch (type) {
	    case SF_FLOAT: 
		sf_floatread((float*) buf,nbuf,in);
		break;
	    case SF_INT:
		sf_intread((int*) buf,nbuf,in);
		break;
            case SF_SHORT:
                sf_shortread((short*) buf,nbuf,in);
		break;
	    case SF_COMPLEX:
		sf_complexread((sf_complex*) buf,nbuf,in);
		break;
	    case SF_UCHAR:
		sf_ucharread((unsigned char*) buf,nbuf,in);
		break;
	    case SF_CHAR:
	    default:
		sf_charread(buf,nbuf,in);
		break;
	}
</syntaxhighlight>


The data attributes are accumulated in corresponding double-precision variables. 
<syntaxhighlight lang="c">
	    fsum += f;
	    fsqr += (double) f*f;
</syntaxhighlight>


Finally, the attributes are reduced and printed out.
<syntaxhighlight lang="c">
    fmean = fsum/nsiz;
    if (lval==2)      fnorm = sqrt(fsqr);
    else if (lval==0) fnorm = nsiz-nzero;
    else              fnorm = pow(flval,1./lval);
    frms = sqrt(fsqr/nsiz);
    if (nsiz > 1) fvar = fabs(fsqr-nsiz*fmean*fmean)/(nsiz-1);
    else          fvar = 0.0;
    fstd = sqrt(fvar);
</syntaxhighlight>

<syntaxhighlight lang="c">
    if(NULL==want || 0==strcmp(want,"rms"))
	printf("rms = %13.6g \n",(float) frms);
    if(NULL==want || 0==strcmp(want,"mean"))
	printf("mean = %13.6g \n",(float) fmean);
    if(NULL==want || 0==strcmp(want,"norm"))
	printf("%d-norm value = %13.6g \n",lval,(float) fnorm);
    if(NULL==want || 0==strcmp(want,"var"))
	printf("variance = %13.6g \n",(float) fvar);
    if(NULL==want || 0==strcmp(want,"std"))
	printf("standard deviation = %13.6g \n",(float) fstd);
</syntaxhighlight>