renaming trace to instance

Author: rafaelfsilva

docs/source/analyzing_instances.rst

@@ -30,18 +30,18 @@ WfCommons project, an instance is represented in a JSON file following the
 schema described in :ref:`json-format-label`. This Python package
 provides an *instance loader* tool for importing workflow execution instances
 for analysis. For instance, the code snippet below shows how an instance can
-be loaded using the :class:`~wfcommons.trace.trace.Trace` class: ::
+be loaded using the :class:`~wfcommons.wfinstances.instance.Instance` class: ::
 
-    from wfcommons import Trace
-    trace = Trace(input_trace='/path/to/instance/file.json')
+    from wfcommons import Instance
+    instance = Instance(input_instance='/path/to/instance/file.json')
 
-The :class:`~wfcommons.trace.trace.Trace` class provides a number of
+The :class:`~wfcommons.wfinstances.instance.Instance` class provides a number of
 methods for interacting with the workflow instance, including:
 
-- :meth:`~wfcommons.trace.trace.Trace.draw`: produces an image or a pdf file representing the instance.
-- :meth:`~wfcommons.trace.trace.Trace.leaves`: gets the leaves of the workflow (i.e., the tasks without any successors).
-- :meth:`~wfcommons.trace.trace.Trace.roots`: gets the roots of the workflow (i.e., the tasks without any predecessors).
-- :meth:`~wfcommons.trace.trace.Trace.write_dot`: writes a dot file of the instance.
+- :meth:`~wfcommons.wfinstances.instance.Instance.draw`: produces an image or a pdf file representing the instance.
+- :meth:`~wfcommons.wfinstances.instance.Instance.leaves`: gets the leaves of the workflow (i.e., the tasks without any successors).
+- :meth:`~wfcommons.wfinstances.instance.Instance.roots`: gets the roots of the workflow (i.e., the tasks without any predecessors).
+- :meth:`~wfcommons.wfinstances.instance.Instance.write_dot`: writes a dot file of the instance.
 
 .. note::
     Although the analysis methods are inherently used by WfCommons (specifically
@@ -51,25 +51,25 @@ methods for interacting with the workflow instance, including:
 The Instance Analyzer
 ---------------------
 
-The :class:`~wfcommons.trace.trace_analyzer.TraceAnalyzer` class provides
+The :class:`~wfcommons.wfinstances.instance_analyzer.InstanceAnalyzer` class provides
 a number of tools for analyzing collection of workflow execution instances. The
-goal of the :class:`~wfcommons.trace.trace_analyzer.TraceAnalyzer` is to
+goal of the :class:`~wfcommons.wfinstances.instance_analyzer.InstanceAnalyzer` is to
 perform analyzes of one or multiple workflow execution instances, and build
 summaries of the analyzes per workflow' task type prefix.
 
 .. warning::
 
     Although any workflow execution instance represented as a
-    :class:`~wfcommons.trace.trace.Trace` object (i.e., compatible with
+    :class:`~wfcommons.wfinstances.instance.Instance` object (i.e., compatible with
     :ref:`json-format-label`) can be appended to the
-    :class:`~wfcommons.trace.trace_analyzer.TraceAnalyzer`, we strongly
+    :class:`~wfcommons.wfinstances.instance_analyzer.InstanceAnalyzer`, we strongly
     recommend that only instances of a single workflow application type be
     appended to an analyzer object. You may though create several analyzer
     objects per workflow application.
 
-The :meth:`~wfcommons.trace.trace_analyzer.TraceAnalyzer.append_trace` method
+The :meth:`~wfcommons.wfinstances.instance_analyzer.InstanceAnalyzer.append_instance` method
 allows you to include instances for analysis. The
-:meth:`~wfcommons.trace.trace_analyzer.TraceAnalyzer.build_summary` method
+:meth:`~wfcommons.wfinstances.instance_analyzer.InstanceAnalyzer.build_summary` method
 processes all appended instances. The method applies probability distributions fitting
 to a series of data to find the *best* (i.e., minimizes the mean square error)
 probability distribution that represents the analyzed data. The method returns
@@ -101,8 +101,8 @@ in which themselves are used to :ref:`generate realistic synthetic workflow inst
 <generating-workflows-label>`.
 
 Probability distribution fits can also be plotted by using the
-:meth:`~wfcommons.trace.trace_analyzer.TraceAnalyzer.generate_fit_plots` or
-:meth:`~wfcommons.trace.trace_analyzer.TraceAnalyzer.generate_all_fit_plots`
+:meth:`~wfcommons.wfinstances.instance_analyzer.InstanceAnalyzer.generate_fit_plots` or
+:meth:`~wfcommons.wfinstances.instance_analyzer.InstanceAnalyzer.generate_all_fit_plots`
 methods -- plots will be saved as :code:`png` files.
 
 Examples
@@ -115,7 +115,7 @@ distribution fitting for task *prefixes* of the Seismology workflow
 plots (runtime, and input and output files) into the :code:`fits` folder using
 :code:`seismology` as a prefix for each generated plot: ::
 
-    from wfcommons import Trace, TraceAnalyzer
+    from wfcommons import Instance, InstanceAnalyzer
     from os import listdir
     from os.path import isfile, join
 
@@ -124,12 +124,12 @@ plots (runtime, and input and output files) into the :code:`fits` folder using
     instance_files = [f for f in listdir(INSTANCES_PATH) if isfile(join(INSTANCES_PATH, f))]
 
     # creating the instance analyzer object
-    analyzer = TraceAnalyzer()
+    analyzer = InstanceAnalyzer()
 
     # appending instance files to the instance analyzer
     for instance_file in instance_files:
-        instance = Trace(input_trace=INSTANCES_PATH + instance_file)
-        analyzer.append_trace(instance)
+        instance = Instance(input_instance=INSTANCES_PATH + instance_file)
+        analyzer.append_instance(instance)
 
     # list of workflow task name prefixes to be analyzed in each instance
     workflow_tasks = ['sG1IterDecon', 'wrapper_siftSTFByMisfit']

docs/source/dev_api_reference.rst

@@ -3,7 +3,7 @@ Developer API Reference
 
 The developer API reference targets developers and researchers who
 want to contribute to the WfCommons project by, for example,
-developing novel techniques for trace analysis, developing new
+developing novel techniques for instance analysis, developing new
 :ref:`workflow recipes <workflow-recipe-label>`, etc.
 The developer API reference documentation includes detailed information
 for interacting with all classes and methods that compose this
@@ -14,6 +14,6 @@ Python package.
     :maxdepth: 1
 
     dev_api_wfcommons.rst
-    dev_api_trace.rst
     dev_api_wfchef.rst
     dev_api_wfgen.rst
+    dev_api_wfinstances.rst

docs/source/dev_api_trace.rst

@@ -0,0 +1,61 @@
+wfcommons.wfinstances
+=====================
+
+wfcommons.wfinstances.schema
+----------------------------
+
+.. automodule:: wfcommons.wfinstances.schema
+   :members:
+   :undoc-members:
+   :show-inheritance:
+   :private-members:
+
+wfcommons.wfinstances.instance
+------------------------------
+
+.. automodule:: wfcommons.wfinstances.instance
+   :members:
+   :undoc-members:
+   :show-inheritance:
+   :private-members:
+   :noindex:
+
+wfcommons.wfinstances.instance\_analyzer
+----------------------------------------
+
+.. automodule:: wfcommons.wfinstances.instance_analyzer
+   :members:
+   :undoc-members:
+   :show-inheritance:
+   :private-members:
+   :noindex:
+
+wfcommons.wfinstances.logs.abstract\_logs\_parser
+-------------------------------------------------
+
+.. automodule:: wfcommons.wfinstances.logs.abstract_logs_parser
+   :members:
+   :undoc-members:
+   :show-inheritance:
+   :private-members:
+   :noindex:
+
+wfcommons.wfinstances.logs.makeflow
+-----------------------------------
+
+.. automodule:: wfcommons.wfinstances.logs.makeflow
+   :members:
+   :undoc-members:
+   :show-inheritance:
+   :private-members:
+   :noindex:
+
+wfcommons.wfinstances.logs.pegasus
+----------------------------------
+
+.. automodule:: wfcommons.wfinstances.logs.pegasus
+   :members:
+   :undoc-members:
+   :show-inheritance:
+   :private-members:
+   :noindex:

docs/source/dev_api_wfinstances.rst

@@ -10,9 +10,9 @@ The parsers provided in this Python package automatically scans execution logs
 to produce instances using :ref:`json-format-label`.
 
 Each parser class is derived from the abstract
-:class:`~wfcommons.trace.logs.abstract_logs_parser.LogsParser` class. Thus, each
+:class:`~wfcommons.wfinstances.logs.abstract_logs_parser.LogsParser` class. Thus, each
 parser provides a
-:meth:`~wfcommons.trace.logs.abstract_logs_parser.LogsParser.build_workflow`
+:meth:`~wfcommons.wfinstances.logs.abstract_logs_parser.LogsParser.build_workflow`
 method.
 
 Makeflow
@@ -30,9 +30,9 @@ campus clusters, the Open Science Grid, NSF XSEDE machines, NCSA Blue Waters, an
 Amazon Web Services. Makeflow logs provide time-stamped event instances from these
 executions. The following example shows the analysis of Makeflow execution logs,
 stored in a local folder (execution dir), for a workflow execution using the
-:class:`~wfcommons.trace.logs.makeflow.MakeflowLogsParser` class: ::
+:class:`~wfcommons.wfinstances.logs.makeflow.MakeflowLogsParser` class: ::
 
-    from wfcommons.trace import MakeflowLogsParser
+    from wfcommons.wfinstances import MakeflowLogsParser
 
     # creating the parser for the Makeflow workflow
     parser = MakeflowLogsParser(execution_dir='/path/to/makeflow/execution/dir/blast/chameleon-small-001/'
@@ -45,7 +45,7 @@ stored in a local folder (execution dir), for a workflow execution using the
     workflow.write_json('workflow.json')
 
 .. note::
-    The :class:`~wfcommons.trace.logs.makeflow.MakeflowLogsParser` class requires
+    The :class:`~wfcommons.wfinstances.logs.makeflow.MakeflowLogsParser` class requires
     that Makeflow workflows to run with the
     `Resource Monitor <https://cctools.readthedocs.io/en/latest/resource_monitor/>`_
     tool (e.g., execute the workflow using the :code:`--monitor=logs`).
@@ -63,10 +63,10 @@ DAGMan. Individual workflow tasks are managed by a workload management framework
 HTCondor, which supervises task executions on local and remote resources. Pegasus
 logs provide time-stamped event instances from these executions. The following example shows
 the analysis of Pegasus execution logs, stored in a local folder (submit dir), for a
-workflow execution using the :class:`~wfcommons.trace.logs.pegasus.PegasusLogsParser`
+workflow execution using the :class:`~wfcommons.wfinstances.logs.pegasus.PegasusLogsParser`
 class: ::
 
-    from wfcommons.trace import PegasusLogsParser
+    from wfcommons.wfinstances import PegasusLogsParser
 
     # creating the parser for the Pegasus workflow
     parser = PegasusLogsParser(submit_dir='/path/to/pegasus/submit/dir/seismology/chameleon-100p-001/')
@@ -78,7 +78,7 @@ class: ::
     workflow.write_json('workflow.json')
 
 .. warning::
-    By default, the :class:`~wfcommons.trace.logs.pegasus.PegasusLogsParser`
+    By default, the :class:`~wfcommons.wfinstances.logs.pegasus.PegasusLogsParser`
     class assumes that the submit dir is from a Pegasus execution with **version 5.0**
     or later. To enable parsing of Pegasus execution logs from version 4.9 or earlier,
     the option :code:`legacy=True` should be used.

docs/source/parsing_logs.rst

@@ -2,8 +2,8 @@ User API Reference
 ******************
 
 The user API reference targets users who want to use WfCommons Python
-package for analyzing traces or generating realistic synthetic workflow
-traces, using existing workflow recipes already implemented in this
+package for analyzing instances or generating realistic synthetic workflow
+instances, using existing workflow recipes already implemented in this
 Python package. Users are NOT expected to develop new
 :ref:`workflow recipes <workflow-recipe-label>`.
 
@@ -12,6 +12,6 @@ Python package. Users are NOT expected to develop new
     :maxdepth: 1
 
     user_api_common.rst
-    user_api_trace.rst
     user_api_wfchef.rst
     user_api_wfgen.rst
+    user_api_wfinstances.rst

docs/source/user_api_reference.rst

@@ -0,0 +1,34 @@
+wfcommons.wfinstances
+=====================
+
+wfcommons.wfinstances.instance
+------------------------------
+
+.. automodule:: wfcommons.wfinstances.instance
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+wfcommons.wfinstances.instance\_analyzer
+----------------------------------------
+
+.. automodule:: wfcommons.wfinstances.instance_analyzer
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+wfcommons.wfinstances.logs.makeflow
+-----------------------------------
+
+.. automodule:: wfcommons.wfinstances.logs.makeflow
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+wfcommons.wfinstances.logs.pegasus
+----------------------------------
+
+.. automodule:: wfcommons.wfinstances.logs.pegasus
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/user_api_trace.rst

@@ -18,6 +18,6 @@
 from .wfchef.recipes import BlastRecipe, BwaRecipe, CyclesRecipe, EpigenomicsRecipe, GenomeRecipe, MontageRecipe, \
     SeismologyRecipe, SoykbRecipe, SrasearchRecipe
 from .wfgen import WorkflowGenerator
-from .trace import Trace, TraceAnalyzer, TraceElement
+from .wfinstances import Instance, InstanceAnalyzer, InstanceElement
 
 logging.getLogger('wfcommons').addHandler(logging.NullHandler())