Changeset d15a908 in sasmodels for sasmodels/compare_many.py

Timestamp:

Jan 27, 2016 3:35:15 PM (8 years ago)

Author:

Paul Kienzle <pkienzle@…>

Branches:

master, core_shell_microgels, costrafo411, magnetic_model, release_v0.94, release_v0.95, ticket-1257-vesicle-product, ticket_1156, ticket_1265_superball, ticket_822_more_unit_tests

Children:

fdc538a

Parents:

37a7252

Message:

doc and delint

File:

• sasmodels/compare_many.py (modified) (10 diffs)

sasmodels/compare_many.py

@@ -1 +1 @@
 #!/usr/bin/env python
+"""
+Program to compare results from many random parameter sets for a given model.
+
+The result is a comma separated value (CSV) table that can be redirected
+from standard output into a file and loaded into a spreadsheet.
+
+The models are compared for each parameter set and if the difference is
+greater than expected for that precision, the parameter set is labeled
+as bad and written to the output, along with the random seed used to
+generate that parameter value.  This seed can be used with :mod:`compare`
+to reload and display the details of the model.
+"""
 from __future__ import print_function
 
@@ -14 +26 @@
 
 def calc_stats(target, value, index):
+    """
+    Calculate statistics between the target value and the computed value.
+
+    *target* and *value* are the vectors being compared, with the
+    difference normalized by *target* to get relative error.  Only
+    the elements listed in *index* are used, though index may be
+    and empty slice defined by *slice(None, None)*.
+
+    Returns:
+
+        *maxrel* the maximum relative difference
+
+        *rel95* the relative difference with the 5% biggest differences ignored
+
+        *maxabs* the maximum absolute difference for the 5% biggest differences
+
+        *maxval* the maximum value for the 5% biggest differences
+    """
     resid = abs(value-target)[index]
     relerr = resid/target[index]
-    srel = np.argsort(relerr)
+    sorted_rel_index = np.argsort(relerr)
     #p90 = int(len(relerr)*0.90)
     p95 = int(len(relerr)*0.95)
     maxrel = np.max(relerr)
-    rel95 = relerr[srel[p95]]
-    maxabs = np.max(resid[srel[p95:]])
-    maxval = np.max(value[srel[p95:]])
-    return maxrel,rel95,maxabs,maxval
+    rel95 = relerr[sorted_rel_index[p95]]
+    maxabs = np.max(resid[sorted_rel_index[p95:]])
+    maxval = np.max(value[sorted_rel_index[p95:]])
+    return maxrel, rel95, maxabs, maxval
 
 def print_column_headers(pars, parts):
+    """
+    Generate column headers for the differences and for the parameters,
+    and print them to standard output.
+    """
     stats = list('Max rel err|95% rel err|Max abs err above 90% rel|Max value above 90% rel'.split('|'))
     groups = ['']
@@ -36 +70 @@
     print(','.join('"%s"'%c for c in columns))
 
+# Target 'good' value for various precision levels.
 PRECISION = {
     'fast': 1e-3,
@@ -48 +83 @@
 def compare_instance(name, data, index, N=1, mono=True, cutoff=1e-5,
                      base='sasview', comp='double'):
-    is2D = hasattr(data, 'qx_data')
+    r"""
+    Compare the model under different calculation engines.
+
+    *name* is the name of the model.
+
+    *data* is the data object giving $q, \Delta q$ calculation points.
+
+    *index* is the active set of points.
+
+    *N* is the number of comparisons to make.
+
+    *cutoff* is the polydispersity weight cutoff to make the calculation
+    a little bit faster.
+
+    *base* and *comp* are the names of the calculation engines to compare.
+    """
+
+    is_2d = hasattr(data, 'qx_data')
     model_definition = core.load_model_definition(name)
     pars = get_demo_pars(model_definition)
     header = ('\n"Model","%s","Count","%d","Dimension","%s"'
-              % (name, N, "2D" if is2D else "1D"))
+              % (name, N, "2D" if is_2d else "1D"))
     if not mono: header += ',"Cutoff",%g'%(cutoff,)
     print(header)
 
-    if is2D:
+    if is_2d:
         info = generate.make_info(model_definition)
         partype = info['partype']
@@ -69 +121 @@
     # declarations are not available in python 2.7.
     def try_model(fn, pars):
+        """
+        Return the model evaluated at *pars*.  If there is an exception,
+        print it and return NaN of the right shape.
+        """
         try:
             result = fn(**pars)
@@ -82 +138 @@
         return result
     def check_model(pars):
+        """
+        Run the two calculators against *pars*, returning statistics
+        on the differences.  See :func:`calc_stats` for the list of stats.
+        """
         base_value = try_model(calc_base, pars)
         comp_value = try_model(calc_comp, pars)
@@ -108 +168 @@
         good = [True]
         columns = check_model(pars_i)
-        columns += [v for _,v in sorted(pars_i.items())]
+        columns += [v for _, v in sorted(pars_i.items())]
         if first:
             labels = [" vs. ".join((calc_base.engine, calc_comp.engine))]
@@ -121 +181 @@
 
 def print_usage():
+    """
+    Print the command usage string.
+    """
     print("usage: compare_many.py MODEL COUNT (1dNQ|2dNQ) (CUTOFF|mono) (single|double|quad)")
 
 
 def print_models():
+    """
+    Print the list of available models in columns.
+    """
     print(columnize(MODELS, indent="  "))
 
 
 def print_help():
+    """
+    Print usage string, the option description and the list of available models.
+    """
     print_usage()
     print("""\
@@ -158 +227 @@
 
 def main():
-    if len(sys.argv) not in (6,7):
+    """
+    Main program.
+    """
+    if len(sys.argv) not in (6, 7):
         print_help()
         sys.exit(1)
@@ -182 +254 @@
 
     data, index = make_data({'qmax':1.0, 'is2d':is2D, 'nq':Nq, 'res':0.,
-                              'accuracy': 'Low', 'view':'log'})
+                             'accuracy': 'Low', 'view':'log'})
     model_list = [model] if model != "all" else MODELS
     for model in model_list: