nb: generic noise budget support

This patch provides a new nb sub-module that defines classes for managing and calculating noise budgets. It provides the following overridable classes:

nb.Calibration  A noise calibration
nb.Noise        A noise source
nb.Budget       A budget of noises

The Budget class includes a calc_trace() method that will return a traces dictionary that includes data and trace plot styling for every noise term in the budget recursively.

The existing included interferometers are updated to define their budgets using this new interface, and the plot_noises function is updated to accept the new traces dictionary.

An HDF5_SCHEMA describes how trace dictionaries are encoded into HDF5 files. The new io module includes functions for writing traces to HDF5 files, and for reading traces stored in this format.

The command line interface is updated to handle this new structure.

gwinc/nb.py

@@ -131,9 +131,13 @@ class Noise(BudgetItem):
     style = {}
     """Trace plot style dictionary"""
 
-    def calc_trace(self, calc=True):
+    def calc_trace(self, calibration=None, calc=True):
         """Returns noise (PSD, style) tuple.
 
+        If `calibration` is not None it is assumed to be a
+        len(self.freq) array that will be multiplied to the output
+        PSD.
+
         If calc=False, the noise will not be calculated and the PSD
         will be None.  This is useful for just getting style the
         style.
@@ -141,6 +145,8 @@ class Noise(BudgetItem):
         """
         if calc:
             data = self.calc()
+            if calibration is not None:
+                data *= calibration
         else:
             data = None
         return data, self.style
@@ -319,7 +325,7 @@ class Budget(Noise):
             item.update(**kwargs)
 
     def cal_for_noise(self, name):
-        """Get the calibration object for named noise."""
+        """Return the calibration object for named noise."""
         try:
             return self._cal_objs[self._noise_cal[name]]
         except KeyError:
@@ -348,7 +354,7 @@ class Budget(Noise):
         data = [self.calc_noise(name) for name in self._noise_objs.keys() if name in self._budget_noises]
         return quadsum(data)
 
-    def calc_trace(self, calc=True):
+    def calc_trace(self, calibration=None, calc=True):
         """Returns a dictionary of noises traces, keyed by noise names.
 
         Values are (data, style) trace tuples (see Noise.calc_trace).
@@ -356,9 +362,13 @@ class Budget(Noise):
         budgets are themselves dictionaries returned from
         calc_traces() of the sub budget.
 
-        If calc=False, the noises will not be calculated and the data
-        will be None.  This is useful for getting just the trace
-        styles.
+        If `calibration` is not None it is assumed to be a
+        len(self.freq) array that will be multiplied to the output
+        PSD of the budget and all sub noises.
+
+        If calc=False, the noise will not be calculated and the PSD
+        will be None.  This is useful for just getting style the
+        style.
 
         """
         # start by creating an empty OrderedDict used for outputing trace data
@@ -385,7 +395,16 @@ class Budget(Noise):
             return d
         # calc all noises
         for name, noise in self._noise_objs.items():
-            d[name] = noise.calc_trace(calc=True)
+            # extract/calc the budget-level calibration for this noise
+            cal_obj = self.cal_for_noise(name)
+            if cal_obj:
+                cal = cal_obj.calc()
+            else:
+                cal = np.ones_like(self.freq)
+            # then multiply by the supplied calibration
+            if calibration is not None:
+                cal *= calibration
+            d[name] = noise.calc_trace(calibration=cal, calc=True)
         # calc budget total
         constituent_data = []
         for name in self._budget_noises: