Merge branch 'default_freq' into 'master'

default frequency array for load_budget()

See merge request !106

README.md

@@ -113,13 +113,22 @@ For custom plotting, parameter optimization, etc. all functionality can be
 accessed directly through the `gwinc` library interface:
 ```python
 >>> import gwinc
->>> import numpy as np
->>> freq = np.logspace(1, 3, 1000)
->>> budget = gwinc.load_budget('aLIGO', freq)
+>>> budget = gwinc.load_budget('aLIGO')
 >>> trace = budget.run()
 >>> fig = gwinc.plot_budget(trace)
 >>> fig.show()
 ```
+A default frequency array is used, but alternative frequencies can be
+provided to `load_budget()` either in the form of a numpy array:
+```python
+>>> import numpy as np
+>>> freq = np.logspace(1, 3, 1000)
+>>> budget = gwinc.load_budget('aLIGO', freq=freq)
+```
+or frequency specification string ('FLO:[NPOINTS:]FHI'):
+```
+>>> budget = gwinc.load_budget('aLIGO', freq='10:1000:1000')
+```
 
 The `load_budget()` function takes most of the same inputs as the
 command line interface (e.g. IFO names, budget module paths, YAML
@@ -134,6 +143,15 @@ properties.  The budget sub-traces are available through a dictionary
 (`trace['QuantumVacuum']`) interface and via attributes
 (`trace.QuantumVacumm`).
 
+The budget `freq` and `ifo` attributes can be updated at run time by
+passing them as keyword arguments to the `run()` method:
+```python
+>>> budget = load_budget('aLIGO')
+>>> freq = np.logspace(1, 3, 1000)
+>>> ifo = Struct.from_file('/path/to/ifo_alt.yaml')
+>>> trace = budget.run(freq=freq, ifo=ifo)
+```
+
 
 ## noise functions
 
@@ -340,12 +358,6 @@ If a budget module defined as a package includes an `ifo.yaml`
 [parameter file](#parameter-files) in the package directory, the
 `load_budget()` function will automatically load the YAML data into an
 `ifo` `gwinc.Struct` and assign it to the `budget.ifo` attribute.
-Alternate ifos can be specified at run time:
-```python
-budget = load_budget('/path/to/MyBudget', freq)
-ifo = Struct.from_file('/path/to/MyBudget.ifo')
-trace = budget.run(ifo=ifo)
-```
 
 The IFOs included in `gwinc.ifo` provide examples of the use of the
 budget interface (e.g. [gwinc.ifo.aLIGO](gwinc/ifo/aLIGO)).

gwinc/__init__.py

@@ -14,6 +14,31 @@ from .plot import plot_noise
 logger = logging.getLogger('gwinc')
 
 
+DEFAULT_FREQ = '5:3000:6000'
+
+
+def freq_from_spec(spec=None):
+    """logarithmicly spaced frequency array, based on specification string
+
+    Specification string should be of form 'START:[NPOINTS:]STOP'.  If
+    `spec` is an array, then the array is returned as-is, and if it's
+    None the DEFAULT_FREQ specification is used.
+
+    """
+    if isinstance(spec, np.ndarray):
+        return spec
+    elif spec is None:
+        spec = DEFAULT_FREQ
+    fspec = spec.split(':')
+    if len(fspec) == 2:
+        fspec = fspec[0], DEFAULT_FREQ.split(':')[1], fspec[1]
+    return np.logspace(
+        np.log10(float(fspec[0])),
+        np.log10(float(fspec[2])),
+        int(fspec[1]),
+    )
+
+
 def load_module(name_or_path):
     """Load module from name or path.
 
@@ -43,19 +68,24 @@ def load_budget(name_or_path, freq=None):
 
     Accepts either the name of a built-in canonical budget (see
     gwinc.IFOS), the path to a budget package (directory) or module
-    (ending in .py), or the path to an IFO struct definition file (see
+    (ending in .py), or the path to an IFO Struct definition file (see
     gwinc.Struct).
 
     If the budget is a package directory which includes an 'ifo.yaml'
     file the ifo Struct will be loaded from that file and assigned to
-    the budget.ifo attribute.  If a struct definition file is provided
-    the base aLIGO budget definition and ifo will be assumed.
+    the budget.ifo attribute.  If a Struct definition file is provided
+    the base aLIGO budget definition will be assumed.
+
+    Returns an instantiated Budget object.  If a frequency array or
+    frequency specification string (see `freq_from_spec()`) is
+    provided, the budget will be instantiated with the provided array.
+    If a frequency array is not provided and the Budget class
+    definition includes a `freq` attribute defining either an array or
+    specification string, then that array will be used.  Otherwise a
+    default array will be provided (see DEFAULT_FREQ).
 
-    Returns a Budget object instantiated with the provided frequency
-    array (if specified), and with any included ifo assigned as an
-    object attribute.  If a frequency array is not provided and the
-    budget class does not define it's own, the frequency array must be
-    provided at budget update() or run() time.
+    Any included ifo will be assigned as an attribute to the returned
+    Budget object.
 
     """
     ifo = None
@@ -85,6 +115,9 @@ def load_budget(name_or_path, freq=None):
     logger.info("loading module {}...".format(modname))
     mod, modpath = load_module(modname)
     Budget = getattr(mod, bname)
+    if freq is None:
+        freq = getattr(Budget, 'freq', None)
+    freq = freq_from_spec(freq)
     ifopath = os.path.join(modpath, 'ifo.yaml')
     if not ifo and os.path.exists(ifopath):
         ifo = Struct.from_file(ifopath)

gwinc/__main__.py

@@ -3,9 +3,15 @@ import os
 import signal
 import logging
 import argparse
-import numpy as np
 
-from . import IFOS, load_budget, plot_budget, logger
+from . import (
+    IFOS,
+    DEFAULT_FREQ,
+    freq_from_spec,
+    load_budget,
+    plot_budget,
+    logger,
+)
 from . import io
 
 logger.setLevel(os.getenv('LOG_LEVEL', 'WARNING').upper())
@@ -49,10 +55,11 @@ e.g.:
   gwinc --fom range:m1=20,m2=20 ...
 
 See the inspiral_range package documentation for details.
+NOTE: The range will be calculated with the supplied frequency array,
+and may therefore be inaccurate if a restricted array is specified.
 """
 
 IFO = 'aLIGO'
-FREQ = '5:3000:6000'
 FOM = 'range:m1=1.4,m2=1.4'
 
 parser = argparse.ArgumentParser(
@@ -61,7 +68,7 @@ parser = argparse.ArgumentParser(
     formatter_class=argparse.RawDescriptionHelpFormatter)
 parser.add_argument(
     '--freq', '-f', metavar='FLO:[NPOINTS:]FHI',
-    help="logarithmic frequency array specification in Hz [{}]".format(FREQ))
+    help="logarithmic frequency array specification in Hz [{}]".format(DEFAULT_FREQ))
 parser.add_argument(
     '--ifo', '-o', metavar='PARAM=VAL',
     #nargs='+', action='extend',
@@ -97,17 +104,6 @@ parser.add_argument(
     help="IFO name or path")
 
 
-def freq_from_spec(spec):
-    fspec = spec.split(':')
-    if len(fspec) == 2:
-        fspec = fspec[0], FREQ.split(':')[1], fspec[1]
-    return np.logspace(
-        np.log10(float(fspec[0])),
-        np.log10(float(fspec[2])),
-        int(fspec[1]),
-    )
-
-
 def main():
     signal.signal(signal.SIGINT, signal.SIG_DFL)
 
@@ -129,15 +125,12 @@ def main():
         plot_style = trace.plot_style
 
     else:
-        budget = load_budget(args.IFO)
+        try:
+            freq = freq_from_spec(args.freq)
+        except IndexError:
+            parser.exit(2, "Improper frequency specification: {}\n".format(args.freq))
+        budget = load_budget(args.IFO, freq=freq)
         ifo = budget.ifo
-        if args.freq:
-            try:
-                freq = freq_from_spec(args.freq)
-            except IndexError:
-                parser.exit(2, "Improper frequency specification: {}\n".format(args.freq))
-        else:
-            freq = getattr(budget, 'freq', freq_from_spec(FREQ))
         plot_style = getattr(budget, 'plot_style', {})
         trace = None