more docs - mostly for targets

.idea/grond.iml

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<module type="PYTHON_MODULE" version="4">
+  <component name="NewModuleRootManager">
+    <content url="file://$MODULE_DIR$" />
+    <orderEntry type="inheritedJdk" />
+    <orderEntry type="sourceFolder" forTests="false" />
+  </component>
+</module>

.idea/misc.xml

@@ -0,0 +1,14 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="ProjectLevelVcsManager" settingsEditedManually="false">
+    <OptionsSetting value="true" id="Add" />
+    <OptionsSetting value="true" id="Remove" />
+    <OptionsSetting value="true" id="Checkout" />
+    <OptionsSetting value="true" id="Update" />
+    <OptionsSetting value="true" id="Status" />
+    <OptionsSetting value="true" id="Edit" />
+    <ConfirmationsSetting value="0" id="Add" />
+    <ConfirmationsSetting value="0" id="Remove" />
+  </component>
+  <component name="ProjectRootManager" version="2" project-jdk-name="Python 2.7.9 (/usr/bin/python2.7)" project-jdk-type="Python SDK" />
+</project>

.idea/modules.xml

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="ProjectModuleManager">
+    <modules>
+      <module fileurl="file://$PROJECT_DIR$/.idea/grond.iml" filepath="$PROJECT_DIR$/.idea/grond.iml" />
+    </modules>
+  </component>
+</project>

.idea/workspace.xml

@@ -0,0 +1,42 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="ChangeListManager">
+    <option name="TRACKING_ENABLED" value="true" />
+    <option name="SHOW_DIALOG" value="false" />
+    <option name="HIGHLIGHT_CONFLICTS" value="true" />
+    <option name="HIGHLIGHT_NON_ACTIVE_CHANGELIST" value="false" />
+    <option name="LAST_RESOLUTION" value="IGNORE" />
+  </component>
+  <component name="CreatePatchCommitExecutor">
+    <option name="PATCH_PATH" value="" />
+  </component>
+  <component name="ProjectLevelVcsManager" settingsEditedManually="false">
+    <OptionsSetting value="true" id="Add" />
+    <OptionsSetting value="true" id="Remove" />
+    <OptionsSetting value="true" id="Checkout" />
+    <OptionsSetting value="true" id="Update" />
+    <OptionsSetting value="true" id="Status" />
+    <OptionsSetting value="true" id="Edit" />
+    <ConfirmationsSetting value="0" id="Add" />
+    <ConfirmationsSetting value="0" id="Remove" />
+  </component>
+  <component name="ShelveChangesManager" show_recycled="false">
+    <option name="remove_strategy" value="false" />
+  </component>
+  <component name="TaskManager">
+    <task active="true" id="Default" summary="Default task">
+      <created>1525437857462</created>
+      <option name="number" value="Default" />
+      <option name="presentableId" value="Default" />
+      <updated>1525437857462</updated>
+    </task>
+    <servers />
+  </component>
+  <component name="VcsContentAnnotationSettings">
+    <option name="myLimit" value="2678400000" />
+  </component>
+  <component name="XDebuggerManager">
+    <breakpoint-manager />
+    <watches-manager />
+  </component>
+</project>

docs/source/documentation/index.rst

@@ -74,27 +74,30 @@ Required input file is a simple ``YAML`` file containing GNSS station positions,
     name: northridge
     stations:
     - !pf.gnss.GNSSStation
-    lat: 18.30
-    lon: -74.22
-    elevation: 0.0
-    depth: 0.0
-    code: ANGL
-    style: static
-    north: !pf.gnss.GNSSComponent
+      lat: 18.30
+      lon: -74.22
+      elevation: 0.0
+      depth: 0.0
+      code: ANGL
+      style: static
+      north: !pf.gnss.GNSSComponent
         unit: m
         shift: 5.7e-06
         sigma: 5.7e-06
-    east: !pf.gnss.GNSSComponent
+      east: !pf.gnss.GNSSComponent
         unit: m
         shift: -7e-07
         sigma: 8.8e-06
-    up: !pf.gnss.GNSSComponent
+      up: !pf.gnss.GNSSComponent
         unit: m
         shift: 2.93e-05
         sigma: 1.11e-05
+      correlation_ne: 0.002
+      correlation_eu: 0.0
+      correlation_nu: 0.0
     - !pf.gnss.GNSSStation
-    lat: 18.28
-    ...
+      lat: 18.28
+      ...
 
 (add more station information in the same manner) 
 
@@ -111,6 +114,7 @@ A Green's functions (GF) database is needed that stores GF for many possible sou
 For a large global earthquakes point-source analysis a global GF store of Green's functions with a sampling frequency of 2 Hz may suffice. 
 
 ::
+
         fomosto download kinherd global_2s store 
 
 You can browse here for more available `GF stores`_.
@@ -150,8 +154,7 @@ The ``targets`` (data and misfit setups for seimsic waveforms, InSAR and or GNSS
 Commented snippets of ``grond`` configuration files explaining all options can be found here for 
     * point-source optimizations based on waveforms: :download:`config_example_waveforms.yaml </../../examples/config_example_waveforms.yaml>`
     * finite source optimizations based on InSAR data: :download:`config_example_static.yaml </../../examples/config_example_static.yaml>`
-    #* full configuration documentation 
-
+    
     
 .. literalinclude :: /../../examples/config_example_static.yaml
     :language: yaml
@@ -175,6 +178,9 @@ Now, you may start the optimization for a given event using:
 
 During the optimization, results are aggregated in an output directory, referred to `<rundir>`  in the configuration. 
 
+You find detailed information on the misfit configuration and model space 
+sampling in the Chapter `Optimisers`_.
+
 
 Results plots, exports and reports
 ----------------------------------
@@ -201,9 +207,12 @@ Finally, you may run:
 	grond report <rundir>
 	grond report-index reports 
 
-to aggregate all results to a browsable summary, (by default) under the directory `reports`.
+to aggregate all results to a browsable summary, (by default) under the directory `reports`. 
+Please find detailed information on the plots in the Chapter `Result Plots`_. 
 
 
+.. _Optimisers: ../library/optimisers.html
+.. _Result Plots: ./plots_docu.html
 .. _kite documentation: https://pyrocko.org/docs/kite/current/
 .. _downloadwave: https://pyrocko.org/docs/current/library/examples/fdsn_download.html
 .. _qseis: https://pyrocko.org/docs/current/apps/fomosto/tutorial.html#creating-a-new-green-s-function-store

docs/source/index.rst

@@ -8,7 +8,7 @@ Grond - The Earthquake Buster's Documentation!
 
 .. toctree::
    install/index
-   documentation/idex
+   documentation/index
    documentation/plots_docu
    library/index
    :maxdepth: 2

docs/source/library/optimisers.rst

@@ -0,0 +1,10 @@
+Optimisers enabled in `Grond`
+=============================
+
+The `optimiser` defines the objective functions and the sampling of the model space.
+In `grond` so far only a single `optimiser` is enabled. The setup can be used as axample 
+to derive any kind of optimisation or inversion scheme, however.
+
+The ``highscore`` optimiser
+'''''''''''''''''''''''''''
+

src/targets/gnss_campaign/target.py

@@ -11,16 +11,27 @@ logger = logging.getLogger('grond.target').getChild('gnss_campaign')
 
 
 class GNSSCampaignMisfitResult(MisfitResult):
+    '''Carries the observations for a target and corresponding synthetics. '''
     statics_syn = Dict.T(optional=True)
     statics_obs = Dict.T(optional=True)
 
 
 class GNSSCampaignMisfitConfig(MisfitConfig):
+
     pass
 
 
 class GNSSCampaignTargetGroup(TargetGroup):
-    gnss_campaigns = List.T(optional=True)
+    '''Handles static displacements from campaign GNSS observations, e.g GPS.
+
+    Station information, displacements and measurement errors are provided in
+    a `yaml`-file (please find an example in the documentation). The
+    measurement errors may consider correlations between components of a
+    station, but correlations between single stations is not considered.
+    '''
+    gnss_campaigns = List.T(
+        optional=True,
+        help='List of individual campaign names (`name` in `gnss.yaml` files).')
     misfit_config = GNSSCampaignMisfitConfig.T()
 
     def get_targets(self, ds, event, default_path):
@@ -64,6 +75,11 @@ class GNSSCampaignTargetGroup(TargetGroup):
 
 
 class GNSSCampaignMisfitTarget(gf.GNSSCampaignTarget, MisfitTarget):
+    '''Handles and carries out operations related to the objective functions.
+
+    The objective function is here the weighted misfit between observed
+    and predicted surface displacements.
+    '''
     campaign_name = String.T()
     misfit_config = GNSSCampaignMisfitConfig.T()
 

src/targets/satellite/target.py

@@ -12,18 +12,42 @@ logger = logging.getLogger('grond.targets.satellite.target')
 
 
 class SatelliteMisfitConfig(MisfitConfig):
-    optimise_orbital_ramp = Bool.T(default=True)
+    '''Carries the misfit configuration.'''
+    optimise_orbital_ramp = Bool.T(
+        default=True,
+        help='Switch to account for a linear orbital ramp or not')
     ranges = Dict.T(
         String.T(), gf.Range.T(),
         default={'offset': '-0.5 .. 0.5',
-                 'ramp_east': '-1e-4 .. 1e-4',
-                 'ramp_north': '-1e-4 .. 1e-4'
-                 })
+                 'ramp_east': '-1e-7 .. 1e-7',
+                 'ramp_north': '-1e-7 .. 1e-7'
+                 },
+        help='These parameters give bounds for an offset [m], a linear \
+             gradient in east direction [m/m] and a linear gradient in north \
+             direction [m/m]. Note, while the optimisation of these ramps \
+             is individual for each target, the ranges set here are common \
+             for all satellite targets.')
 
 
 class SatelliteTargetGroup(TargetGroup):
-    kite_scenes = List.T(optional=True)
-    misfit_config = SatelliteMisfitConfig.T()
+    '''Handles maps of static ground motion from satellite observations (InSAR)
+
+    The InSAR displacement maps post-processed by the `pyrocko` module `kite`
+    are usually `Quadtree` downsampled (Jonsson, 2002). Each data point has a
+    latitude, longitude, Line-of-sight displacement value [m] as well as an
+    orientation and elevation angle, which define the Line-of-Sight. The data
+    are associated with a weight matrix, which is the inverse of a full
+    variance-covariance matrix (Sudhaus \& Jonsson, 2009). In principle, these
+    data sets could stem from pixel offset maps. See also the documentation of
+    the `kite` module.
+    '''
+    kite_scenes = List.T(
+        optional=True,
+        help='List of InSAR data files prepared \
+              by the ``pyrocko`` module ``kite``')
+    misfit_config = SatelliteMisfitConfig.T(
+        help='Carries the settings of the objective function for these targets'
+        )
 
     def get_targets(self, ds, event, default_path):
         logger.debug('Selecting satellite targets...')
@@ -79,18 +103,32 @@ class SatelliteTargetGroup(TargetGroup):
 
 
 class SatelliteMisfitResult(gf.Result, MisfitResult):
-    statics_syn = Dict.T(optional=True)
-    statics_obs = Dict.T(optional=True)
+    '''Carries the observations for a target and corresponding synthetics.'''
+    statics_syn = Dict.T(
+        optional=True,
+        help='Predicted static displacements for a target (synthetics).')
+    statics_obs = Dict.T(
+        optional=True,
+        help='Observed static displacement for a target.')
 
 
 class SatelliteMisfitTarget(gf.SatelliteTarget, MisfitTarget):
-    scene_id = String.T()
+    '''Handles and carries out operations related to the objective functions.
+
+    Standard operations are the calculation of the weighted misfit between
+    observed and predicted (synthetic) data. If enabled in the misfit
+    configuration, orbital ramps are optimized for.
+    '''
+    scene_id = String.T(
+        help='Identification string that is individual for each single \ '
+             'satellite target. Can be set in the kite data `yaml`-files')
     available_parameters = [
         Parameter('offset', 'm'),
         Parameter('ramp_north', 'm/m'),
         Parameter('ramp_east', 'm/m')
         ]
-    misfit_config = SatelliteMisfitConfig.T()
+    misfit_config = SatelliteMisfitConfig.T(
+        help='Carries the settings of the objective function for these targets')
 
     def __init__(self, *args, **kwargs):
         gf.SatelliteTarget.__init__(self, *args, **kwargs)

src/targets/waveform/target.py

@@ -30,8 +30,8 @@ class Trace(Object):
 
 
 class WaveformMisfitConfig(MisfitConfig):
-    fmin = Float.T()
-    fmax = Float.T()
+    fmin = Float.T(help='minimum frequency of bandpass filter' )
+    fmax = Float.T(help='maximum frequency of bandpass filter' )
     ffactor = Float.T(default=1.5)
     tmin = gf.Timing.T(
         optional=True,
@@ -82,14 +82,31 @@ def log_exclude(target, reason):
 
 
 class WaveformTargetGroup(TargetGroup):
-    distance_min = Float.T(optional=True)
-    distance_max = Float.T(optional=True)
-    distance_3d_min = Float.T(optional=True)
-    distance_3d_max = Float.T(optional=True)
-    depth_min = Float.T(optional=True)
-    depth_max = Float.T(optional=True)
+    '''Handles seismogram targets or other targets of dynamic ground motion.
+    '''
+    distance_min = Float.T(
+        optional=True,
+        help='excludes targets nearer to source, along a great circle')
+    distance_max = Float.T(
+        optional=True,
+        help='excludes targets farther from source, along a great circle')
+    distance_3d_min = Float.T(
+        optional=True,
+        help='excludes targets nearer from source (direct distance)')
+    distance_3d_max = Float.T(
+        optional=True,
+        help='excludes targets farther from source (direct distance)')
+    depth_min = Float.T(
+        optional=True,
+        help='excludes targets with smaller depths')
+    depth_max = Float.T(
+        optional=True,
+        help='excludes targets with larger depths')
     limit = Int.T(optional=True)
-    channels = List.T(String.T(), optional=True)
+    channels = List.T(
+        String.T(),
+        optional=True,
+        help='set channels to include, e.g. \[\'Z\',\'T\'\]')
     misfit_config = WaveformMisfitConfig.T()
 
     def get_targets(self, ds, event, default_path):
@@ -186,6 +203,10 @@ class TraceSpectrum(Object):
 
 
 class WaveformMisfitResult(gf.Result, MisfitResult):
+    '''Carries the observations for a target and corresponding synthetics.
+
+    A number of different waveform  or phase representations are possible.
+    '''
     processed_obs = Trace.T(optional=True)
     processed_syn = Trace.T(optional=True)
     filtered_obs = Trace.T(optional=True)