Reconcile StageGain and NormalizationFactor in PoleZeroFilter

[kkappler]

1. Stage gain in PoleZeroFilter getting lost after reading in from StationXML. Track down where stage gain is going. We will want to merge this in with the normalization_factor in a PoleZeroFilter() instance so that all gain is in one place.

2. Be careful of the "multiplicative sense" of the stage gain when incorporating into the complex response. i.e. backing out a 10x gain means divide by 10 from the raw data. Ditto with the normalization_factor

3. Put together a test that confirms correct units. With a FluxGate this should be easy because we can compare against IGRF for example.

[kkappler]

It looks like the stage gain is not being added to the kwargs dictionary in filter.py in the method from_obspy_stage().

Here is the kwargs dict that we are getting {'input_units': 'units_in', 'name': 'name', 'output_units': 'units_out', '_zeros': '_zeros', '_poles': '_poles', 'normalization_factor': 'normalization_factor'}

One solution maybe to add stage_gain to /timeseries/filters/standards/pole_zero_filter.json, but it maybe better in the generic obspy_mapping since obspy always populates this field. I'll runs some tests on this

[kkappler]

adding stage_gain to the global OBSPY_MAPPING is not enough, will try adding it to filter.json

This brings up a question -- shall we put gain as an attr for any filter? We are doing this now to accommodate populating via obspy, but if we add it in general then we need to define it ... and as mentioned in the initial ticket, how this related to normalization_factor ... it maybe best to make an @property called total_gain that returns the gain*normalization_factor for pole_zero, but returns gain for most other filters. ...

[kkappler]

Added total_gain() methods to both filter base class and pole-zero filter.

Also added a placeholder test called test_correct_sense_of_normalization_factor() to test_filters.py

Hopefully we can leverage: mth5/examples/make_mth5_from_nims.py to do this

[kujaku11]

@kkappler What about a normalization frequency, is that something the user should input, or is that something we can estimate from the filters, like finding the pass band of the combined filters?

could do this by finding the minimum slope in the amplitude of the combined filters? Or could have a function that estimates the normalization frequency for each filter. Or just take it from the ZPK or FAP filters?

[kujaku11]

@kkappler I added a simple function in PoleZerosFilter to estimate the normalization frequency of the pass band. This is then used in ChannelResponseFilter to estimate the instrument sensitivity. Its simple for now, might want to check my work.

[kujaku11]

By multiplying the stage gain and the normalization factor we get the correct sensitivity estimate. We are setting the normalization frequency in the pass band, which is estimated from the filter. Appears to be correct.