Symmetric FIR filter types confusingly refer to even/odd order along with even/odd symmetry

[chad-earthscope]

Regarding: http://docs.fdsn.org/projects/stationxml/en/latest/response.html#classification-of-fir-filters

Current docs describe the classification of FIR filters including a definition of symmetry Types I, II, III and IV, where the evenness or oddness of a filter is primarily defined according to a filter's order. While the filter length, and opposite notion of even/odd, is mentioned in words, the header of the sub-section is more weighty for the reader.

In the SEED standard (via Blockette 61) and, therefore, StationXML's the FIR->Symmetry element, the evenness or oddness of symmetric filter coefficients is specified according to the number of coefficients, the opposite meaning of the headers in the documentation. The top of these sections with header read, for example Type I, like:

# Type I: M even
M even + even symmetry about the midpoint M/2

Note that in this case, there will be M+1 (odd) points in the filter and M/2 will fall on an index right in the middle:

This is the description of a filter that would be described with a value of ODD in FIR->Symmetry of StationXML, if the symmetric representation were used.

Further, the symmetry is characterized as "even", which, while technically correct, confuses the description further, as "even" and "odd" are being used to describe two different things. Later, for types III and IV, the concept of the matching "odd" symmetry is avoided and instead referred to as anti-symmetric, an so inconsistent.

Note that the SEED manual does not refer to filter by order, but consistently uses number of coefficients; in fact it does not define symmetry Types either. Personally I think including the Types is fine, but they should not use an opposite description from what is required in the format.

As an example, this paragraph in the same section is a good illustration of unnecessary obfuscation of these terms:

FIR filters with generalized linear phase are often divided into 4 types depending on whether the order M is even or odd, so that the number of points is either odd or even, and whether the impulse response (=FIR coefficients) exhibits even or odd symmetry about the middle point.

I suggest adopting something along the lines of this terminology:

Type I: symmetric sequence (of points) of odd length Type II: symmetric sequence (of points) of even length Type III: anti-symmetric sequence (of points) of odd length Type IV: anti-symmetric sequence (of points) of even length

[mikehagerty]

Hey Chad, just saw this. I think the issue I just posted (#100) goes some way to rectify this. Glad to know I'm not the only one who found the EVEN/ODD totally confusing in this context.

I tried to clarify that ODD refers to the total number of coefficients being odd, not necessarily the reduced number that get passed in with the Symmetry=ODD label.

To explain a bit more (beyond issue #100), evalresp.c translates ODD (e.g., obspy Symmetry ODD) to FIR_SYM_1, or Type I and translates EVEN (which is almost never used in my experience) to FIR_SYM_2 of Type II. I think evalresp.c also has an asymmetric enum (FIR_ASYM) but I don't think there is anyway to pass this in from obspy, so you would just pass all the coefficients with Symmetry = None.

[PetrColinSky]

See my comment to issue #71. I like the explanation in issue #100 by @mikehagerty.

[crotwell]

The PR is good, but I think a simpler example might go a long way to making it easier to understand. Especially as compared to a filter with 173 total coefficients!

I almost think a filter of total length 5 might be best, and with simple numbers. Maybe:

<FIR>
        <Symmetry>ODD</Symmetry>
        <NumeratorCoefficient i="1">0.1</NumeratorCoefficient>
        <NumeratorCoefficient i="2">0.4</NumeratorCoefficient>
        <NumeratorCoefficient i="3">0.5</NumeratorCoefficient>
</FIR>

which expands to be equivalent to:

<FIR>
        <Symmetry>NONE</Symmetry>
        <NumeratorCoefficient i="1">0.1</NumeratorCoefficient>
        <NumeratorCoefficient i="2">0.4</NumeratorCoefficient>
        <NumeratorCoefficient i="3">0.5</NumeratorCoefficient>
        <NumeratorCoefficient i="4">0.4</NumeratorCoefficient>
        <NumeratorCoefficient i="5">0.1</NumeratorCoefficient>
</FIR>

and also

<FIR>
        <Symmetry>EVEN</Symmetry>
        <NumeratorCoefficient i="1">0.1</NumeratorCoefficient>
        <NumeratorCoefficient i="2">0.4</NumeratorCoefficient>
        <NumeratorCoefficient i="3">0.5</NumeratorCoefficient>
</FIR>

which expands to be equivalent to:

<FIR>
        <Symmetry>NONE</Symmetry>
        <NumeratorCoefficient i="1">0.1</NumeratorCoefficient>
        <NumeratorCoefficient i="2">0.4</NumeratorCoefficient>
        <NumeratorCoefficient i="3">0.5</NumeratorCoefficient>
        <NumeratorCoefficient i="4">0.5</NumeratorCoefficient>
        <NumeratorCoefficient i="5">0.4</NumeratorCoefficient>
        <NumeratorCoefficient i="6">0.1</NumeratorCoefficient>
</FIR>

This is probably a pretty crappy low pass filter, but understanding the EVEN, ODD, NONE is a lot easier with just a few simple coefficients.

Actually, might be good if someone checked to make sure I didn't do it backwards! :)

If we think it is useful to use a "real" FIR filter, I found this one with only 7 (13 total) coefficients, which is probably about as small as is used in the real world.

<FIR name="130_1_100_5">
        <Description>IRIS-NRL</Description>
        <InputUnits>
          <Name>counts</Name>
          <Description>Digital Count in Digital counts</Description>
        </InputUnits>
        <OutputUnits>
          <Name>counts</Name>
          <Description>Digital Count in Digital counts</Description>
        </OutputUnits>
        <Symmetry>ODD</Symmetry>
        <NumeratorCoefficient i="1">2.44141E-4</NumeratorCoefficient>
        <NumeratorCoefficient i="2">0.00292969</NumeratorCoefficient>
        <NumeratorCoefficient i="3">0.0161133</NumeratorCoefficient>
        <NumeratorCoefficient i="4">0.0537109</NumeratorCoefficient>
        <NumeratorCoefficient i="5">0.12085</NumeratorCoefficient>
        <NumeratorCoefficient i="6">0.193359</NumeratorCoefficient>
        <NumeratorCoefficient i="7">0.225586</NumeratorCoefficient>
      </FIR>

[rcasey-earthscope]

All sounds good to me. I don't like that the word order is being used in this manner, either. An example, such as Philip just showed makes the concept clear.

[crotwell]

@jschaeff do you want to update the PR with the simple examples? If so, I think we have agreement and I can merge and close this issue.

[jschaeff]

I'll update my PR with your examples.

[jschaeff]

How's about that ?

[crotwell]

Looks good to me, merging...thanks.