Feat/log/clean up (#585)

* • System
  - show_graph():
    fixed bug producing empty image for graphs with just one Mechanism
    added auto-recurrent projections

* • Log
  - added numpy_array output method

* -

* -

* -

* -

* -

* -

* -

* -

* -

* -

* -

docs/source/Component.rst

@@ -11,4 +11,4 @@ Components
 
 .. automodule:: psyneulink.components.component
    :members:
-   :exclude-members: ParamsDict, ComponentLog, COMPONENT_BASE_CLASS
+   :exclude-members: ParamsDict, ComponentLog, COMPONENT_BASE_CLASS, LogLevel

psyneulink/components/component.py

@@ -137,8 +137,11 @@
 
 .. _Component_Log:
 
-* **log** - the `log <Component.log>` attribute contains the Component's `Log`, in which its `value <Component.value>`
-  can be recorded during initialization, validation and/or execution.
+* **log** - the `log <Component.log>` attribute contains the Component's `Log`, that can be used to record its
+  `value <Component.value>`, as well as that of Components that belong to it, during initialization, validation,
+  execution and learning.  It also has three convenience methods -- `loggable_items <Log.loggable_items>`, `log_items
+  <Log.log_items>`, and `logged_items <Log.logged_items>` -- that provide access to the corresponding methods of its
+  Log, used to identify, configure and track items for logging.
 ..
 
 .. _Component_Name:
@@ -2831,20 +2834,30 @@ def runtimeParamStickyAssignmentPref(self, setting):
 
     @property
     def loggable_items(self):
-        """List of names of all items that can be logged
-        This is a convenience method that calls self.log
+        """Diciontary of items that can be logged in the Component's `log <Component.log>` and their current `LogLevel`.
+        This is a convenience method that calls the `loggable_items <Log.loggable_items>` property of the Component's
+        `log <Component.log>`.
         """
         return self.log.loggable_items
 
     from psyneulink.globals.log import LogLevel
     def log_items(self, items, log_level=LogLevel.EXECUTION):
-        # Overriden by subclasses to add param_sets (see Mechanism_Base for an example)
+        """
+        log_items(               \
+            items                \
+            log_level=EXECUTION  \
+        )
+
+        Specifies items to be logged. This is a convenience method that calls the `log_items <Log.logged_items>` method
+        of the Component's `log <Component.log>`.
+        """
         self.log.log_items(items=items, log_level=log_level)
 
     @property
     def logged_items(self):
-        """List of names of all the items being logged
-        This is a convenience method that calls self.log.entries
+        """Dictionary of all items that have entries in the log, and their currently assigned `LogLevel`\\s
+        This is a convenience method that calls the `logged_items <Log.logged_items>` property of the Component's
+        `log <Component.log>`.
         """
         return self.log.logged_items
 

psyneulink/components/mechanisms/mechanism.py

@@ -788,10 +788,9 @@ class `UserList <https://docs.python.org/3.6/library/collections.html?highlight=
 from psyneulink.components.states.state import ADD_STATES, _parse_state_spec
 from psyneulink.globals.defaults import timeScaleSystemDefault
 from psyneulink.globals.keywords import CHANGED, COMMAND_LINE, EVC_SIMULATION, EXECUTING, FUNCTION_PARAMS, INITIALIZING, INIT_FUNCTION_METHOD_ONLY, INIT__EXECUTE__METHOD_ONLY, INPUT_STATES, INPUT_STATE_PARAMS, MECHANISM_TIME_SCALE, MONITOR_FOR_CONTROL, MONITOR_FOR_LEARNING, NO_CONTEXT, OUTPUT_STATES, OUTPUT_STATE_PARAMS, PARAMETER_STATES, PARAMETER_STATE_PARAMS, PROCESS_INIT, REFERENCE_VALUE, SEPARATOR_BAR, SET_ATTRIBUTE, SYSTEM_INIT, TIME_SCALE, UNCHANGED, VALIDATE, VALUE, VARIABLE, kwMechanismComponentCategory, kwMechanismExecuteFunction
-from psyneulink.globals.log import LogLevel
 from psyneulink.globals.preferences.preferenceset import PreferenceLevel
 from psyneulink.globals.registry import register_category
-from psyneulink.globals.utilities import AutoNumber, ContentAddressableList, append_type_to_name, convert_to_np_array, iscompatible, kwCompatibilityNumeric
+from psyneulink.globals.utilities import ContentAddressableList, append_type_to_name, convert_to_np_array, iscompatible, kwCompatibilityNumeric
 from psyneulink.scheduling.time import TimeScale
 
 __all__ = [

psyneulink/globals/log.py

@@ -184,26 +184,30 @@
 They can also be exported in numpy array and CSV formats.  The following shows the CSV-formatted output of the Logs
 for ``my_mech_A`` and  ``proj_A_to_B``, using different formatting options::
 
-    >>> print(my_mech_A.log.csv(entries=[pnl.NOISE, pnl.RESULTS], owner_name=False, quotes=None))
+    >> print(my_mech_A.log.csv(entries=[pnl.NOISE, pnl.RESULTS], owner_name=False, quotes=None))
     'Index', 'noise', 'RESULTS'
     0, 0.0, 0.0 0.0
     1, 0.0, 0.0 0.0
+    COMMENT:
     <BLANKLINE>
+    COMMENT
 
     # Display the csv formatted entry of Log for ``proj_A_to_B``
     #    with quotes around values and the Projection's name included in the header:
-    >>> print(proj_A_to_B.log.csv(entries=pnl.MATRIX, owner_name=False, quotes=True))
+    >> print(proj_A_to_B.log.csv(entries=pnl.MATRIX, owner_name=False, quotes=True))
     'Index', 'matrix'
     '0', '1.0 1.0 1.0' '1.0 1.0 1.0'
     '1', '1.0 1.0 1.0' '1.0 1.0 1.0'
+    COMMENT:
     <BLANKLINE>
+    COMMENT
 
 Note that since the `name <Projection.name>` attribute of the Projection was not assigned, its default name is
 reported.
 
 The following shows the Log of ``proj_A_to_B`` in numpy array format::
 
-    >>> proj_A_to_B.log.nparray(entries=[pnl.MATRIX], owner_name=False, header=False) # doctest: +SKIP
+    >> proj_A_to_B.log.nparray(entries=[pnl.MATRIX], owner_name=False, header=False)
     array([[[0], [1]],
            [[[1.0, 1.0, 1.0], [1.0, 1.0, 1.0]],
             [[1.0, 1.0, 1.0], [1.0, 1.0, 1.0]]]], dtype=object)
@@ -565,7 +569,7 @@ class Log:
         each item is a Component that is loggable for the Log's `owner <Log.owner>`
 
     loggable_items : Dict[Component.name: List[LogEntry]]
-        identifies Components that can be logged in the Log; the key of each entry is the name of a Component,
+        identifies Components that can be logged by the owner; the key of each entry is the name of a Component,
         and the value is its currently assigned `LogLevel`.
 
     entries : Dict[Component.name: List[LogEntry]]
@@ -574,7 +578,7 @@ class Log:
         for which information has been logged appear in the `entries <Log.entries>` dict.
 
     logged_items : Dict[Component.name: List[LogEntry]]
-        identifies Components for which information has been entered in the Log; the key for each entry is the name
+        identifies Components that currently have entries in the Log; the key for each entry is the name
         of a Component, and the value is its currently assigned `LogLevel`.
 
     """