Merge pull request #113 from ChihweiLHBird/dev

2____Updating Docstrings Tobe Comment For Attributes

docs/chapter1.ipynb

@@ -145,7 +145,7 @@
     "'''\n",
     "import sciunit\n",
     "from .tests import position_test, velocity_test, eccentricity_test\n",
-    "saturn_motion_suite = sciunit.TestSuite([position_test, velocity_test, eccentricity_test)]\n",
+    "saturn_motion_suite = sciunit.TestSuite([position_test, velocity_test, eccentricity_test])\n",
     "suites = (saturn_motion_suite,)\n",
     "```"
    ]

docs/source/conf.py

@@ -160,4 +160,16 @@
 
 
 # Example configuration for intersphinx: refer to the Python standard library.
-intersphinx_mapping = {'https://docs.python.org/': None}
+intersphinx_mapping = {'https://docs.python.org/': None}
+
+# Removing those three member from the documents to avoid mess. More members can be added in the future.
+def remove_variables(app, what, name, obj, skip, options):
+    if name == "_url":
+        print("-----------------------")
+        print(what)
+    excluded = ["normalization_rules", "rules", "validation_rules", "__dict__", "__doc__"]
+    return name in excluded
+
+# Connecting remove_variables and autodoc-skip-member to setup the event handler.
+def setup(app):
+    app.connect('autodoc-skip-member', remove_variables)

docs/source/index.rst

@@ -1,5 +1,5 @@
 .. sciunit documentation master file, created by
-   sphinx-quickstart on Fri Dec 13 02:42:53 2019.
+   sphinx-quickstart on Sat Dec 21 14:20:34 2019.
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 

sciunit/__main__.py

@@ -30,7 +30,7 @@
 import codecs
 try:
     import matplotlib
-    matplotlib.use('Agg')  # Anticipate possible headless environments
+    matplotlib.use('Agg')  #: Anticipate possible headless environments
 except ImportError:
     pass
 

sciunit/base.py

@@ -118,13 +118,13 @@ def __init__(self):
         """Instantiate a SciUnit object."""
         self.unpicklable = []
 
-    """A list of attributes that cannot or should not be pickled."""
+    #: A list of attributes that cannot or should not be pickled.
     unpicklable = []
 
-    """A URL where the code for this object can be found."""
+    #: A URL where the code for this object can be found.
     _url = None
 
-    """A verbosity level for printing information."""
+    #: A verbosity level for printing information.
     verbose = 1
 
     def __getstate__(self):

sciunit/models/backends.py

@@ -22,7 +22,8 @@ def register_backends(vars):
 
 
 class Backend(object):
-    """Base class for simulator backends.
+    """
+    Base class for simulator backends.
 
     Should only be used with model classes derived from `RunnableModel`.
     Supports caching of simulation results.
@@ -43,13 +44,13 @@ def init_backend(self, *args, **kwargs):
         self.load_model()
         self.model.unpicklable += ['_backend']
 
-    """Name of the backend"""
+    #: Name of the backend
     name = None
 
-    """The function that handles running the simulation"""
+    #: The function that handles running the simulation
     f = None
 
-    """Optional list of state variables for a backend to record."""
+    #: Optional list of state variables for a backend to record.
     recorded_variables = None
 
     def init_cache(self):

sciunit/scores/base.py

@@ -83,13 +83,31 @@ def _check_score(self, score):
     def compute(cls, observation, prediction):
         """Compute whether the observation equals the prediction."""
         return NotImplementedError("")
-
+    
     @property
     def norm_score(self):
         """A floating point version of the score used for sorting.
         If normalized = True, this must be in the range 0.0 to 1.0,
         where larger is better (used for sorting and coloring tables)."""
         return self.score
+
+    @property
+    def log_norm_score(self):
+        """The natural logarithm of the `norm_score`.
+        This is useful for guaranteeing convexity in an error surface"""
+        return np.log(self.norm_score)
+
+    @property
+    def log2_norm_score(self):
+        """The logarithm base 2 of the `norm_score`.
+        This is useful for guaranteeing convexity in an error surface"""
+        return np.log2(self.score)
+
+    @property
+    def log10_norm_score(self):
+        """The logarithm base 10 of the `norm_score`.
+        This is useful for guaranteeing convexity in an error surface"""
+        return np.log10(self.score)
 
     def color(self, value=None):
         """Turn the score intp an RGB color tuple of three 8-bit integers."""

sciunit/unit_test/__main__.py

@@ -6,7 +6,7 @@
 
 def main():
     buffer = 'buffer' in sys.argv
-    sys.argv = sys.argv[:1] # Args need to be removed for __main__ to work.  
+    sys.argv = sys.argv[:1] # :Args need to be removed for __main__ to work.  
     unittest.main(buffer=buffer)
 
 if __name__ == '__main__':