4.40 sddsdigfilter

• description: sddsdigfilter performs time-domain digital filtering of columns of data. Filters can be combined in series and/or cascade to produce complex filter characteristics. In addition to allowing simple 1-pole lowpass and highpass filters, filter characteristics can be defined using either digital Z or analog S domain transfer functions.

  A digital filter has a Z transform given by

  

  while an analog filter has a Laplace transform given by

  

• examples: These examples assume the existence of a file data.wf containing a waveform stored as a column value that is a function of a column time with units of seconds.
      sddsdigfilter data.wf -col=time,value result.wf -low=1,0.01  
      sddsdigfilter data.wf -col=time,value result.wf -low=1,10 -high=1,100  
      sddsdigfilter data.wf -col=time,value result.wf -low=1,100 -cascade -high=1,10  
      sddsdigfilter data.wf -col=time,value result.wf -analog=D,1.0,0.01,C,0.1,0.3,1.6  
      sddsdigfilter data.wf -col=time,value result.wf -digital=B,0,0,0,0,0,1  
      

• synopsis:
      sddsdigfilter [inputFile] [outputFile] [-pipe=[input][,output]]  
        -columns=xName,yName  
        [-proportional=gain]  
        [-lowpass=gain,cutoffFrequency]  
        [-highpass=gain,cutoffFrequency]  
        [-digitalfilter=sddsfile,aCoeffName,bCoeffName]  
        [-digitalfilter=[A,a0,a1,..,am][,B,b0,b1,..,bn]]  
        [-analogfilter=sddsfile,cCoeffName,dCoeffName]  
        [-analogfilter=[C,c0,c1,..,cm][,D,d0,d1,..,dn]]  
        [-cascade]  
        [-verbose]  
      

• files: Two file names are required: the name of the existing input file and the name of the output file to be produced. The input file must contain at least two columns: one containing the data to be filtered (yName) and the other giving time information (xName). A linear time scale is assumed for xName. The output file is a copy of the input file with an additional column called DigFilteredyName where yName would be the name of the original y-column.
• switches:
  • -pipe[=input][,output] — The standard SDDS Toolkit pipe switch.
  • -columns=xName,yName — The names of the input file data columns.
  • -proportional=gain — Defines a gain stage, where gain is the multiplier applied to the data.
  • -lowpass=gain,cutoffFrequency — Defines a lowpass filter stage, where gain is the multiplier applied to the data and cutoffFrequency is the -3dB point of the filter in units appropriate to the supplied xName.
  • -highpass=gain,cutoffFrequency — Defines a highpass filter stage, where gain is the multiplier applied to the data and cutoffFrequency is the -3dB point of the filter in units appropriate to the supplied xName.
  • -digitalfilter=sddsfile,aCoeffName,bCoeffName — Defines a digital filter with coefficients in the supplied SDDS coefficient file. This file must contain two columns containing the A and B coefficients of a digital Z transfer function. Control theory convention assumes that the A0 coefficient is always 1.0. To ensure consistency with the SDDS file, the a0 coefficient is the first row in the A-column and must be implicitly supplied. Although there is little benefit to setting a0 to anything other than 1.0, it is allowed.
  • -digitalfilter=[A,a0,a1,...,am][,B,b0,b1,...,bn] — Defines a digital filter with the A and B coefficients of the digital Z transfer function supplied on the command line. Either A or B or both coefficients can be supplied. If no A coefficients are supplied, a0 is set to 1.0. Equally, if no B coefficients are supplied, b0 is set to 1.0. If different numbers of A and B coefficients are supplied, the filter order is determined from the largest order.
  • -analogfilter=sddsfile,cCoeffName,dCoeffName — Defines an analog filter with coefficients in the supplied SDDS coefficient file. This file must contain two columns containing the C and D coefficients of an analog S transfer function. Conversion to the digital domain is done using a bilinear transform. Note that the user must ensure adequate data sampling, since the general format does not allow frequency warping based on the filter cutoff frequency.
  • -analogfilter=[C,c0,c1,...,cm][,D,d0,d1,...,dn] — Defines an analog filter with the C and D coefficients of the analog S transfer function supplied on the command line. Either C or D or both coefficients can be supplied. If no C coefficients are supplied, then c0 is set to 1.0. Equally, if no D coefficients are supplied, then d0 is set to 1.0. Conversion to the digital domain is done using a bilinear transform. Note that the user must ensure adequate data sampling, since the general format does not allow frequency warping based on the filter cutoff frequency.
  • -cascade — Defines the start of a new filter stage. Any number of filter stages can be supplied for a single data set. If more than one filter is defined, then the outputs are summed unless the -cascade switch is supplied between the filter definitions, in which case the output of the first filter stage is fed into the input of the subsequent filter stage.
  • -verbose — Prints the filter coefficients for each filter stage.
• author: John Carwardine, ANL/APS.