Experimenting with documentation formats

hed/tools/remodeling/operations/base_op.py

@@ -21,15 +21,17 @@ def __init__(self, op_spec, parameters):
             parameters (dict):  Actual values of the parameters for the operation.
 
         Raises:
-            KeyError:
-            - If a required parameter is missing.
-            - If an unexpected parameter is provided.
+            KeyError
 
-            TypeError:
-            - If a parameter has the wrong type.
+                > If a required parameter is missing.
+
+                > If an unexpected parameter is provided.
+
+            TypeError
+                - If a parameter has the wrong type.
 
             ValueError:
-            - If the specification is missing a valid operation.
+                - If the specification is missing a valid operation.
 
         """
         self.operation = op_spec.get("operation", "")
@@ -40,19 +42,19 @@ def __init__(self, op_spec, parameters):
         self.check_parameters(parameters)
 
     def check_parameters(self, parameters):
-        """ Verify that the parameters meet the specification of the operation.
+        """ Verify that the parameters meet the operation specification.
 
         Parameters:
             parameters (dict): Dictionary of parameters for this operation.
 
         Raises:
 
-           KeyError:
-           - If a required parameter is missing.
-           - If an unexpected parameter is provided.
+            KeyError
+                If a required parameter is missing.
+                If an unexpected parameter is provided.
 
             TypeError:
-            - If a parameter has the wrong type.
+                - If a parameter has the wrong type.
 
         """
 
@@ -78,7 +80,7 @@ def do_op(self, dispatcher, df, name, sidecar=None):
         """ Base class method to be overridden with by each operation.
 
         Parameters:
-            dispatcher (Dispatcher): The dispatcher object for managing the operations.
+            dispatcher (Dispatcher): Manages the operation I/O.
             df (DataFrame): The tabular file to be remodeled.
             name (str): Unique identifier for the data -- often the original file path.
             sidecar (Sidecar or file-like):  A JSON sidecar needed for HED operations.

hed/tools/remodeling/operations/factor_column_op.py

@@ -9,15 +9,15 @@
 class FactorColumnOp(BaseOp):
     """ Create tabular file factor columns from column values.
 
-    The required parameters are:
-        - column_name (str):  The name of a column in the DataFrame.
-        - factor_values (list):  Values in the column column_name to create factors for.
-        - factor_names (list):   Names to use as the factor columns.
+    Required parameters:
+        - column_name (*str*):  The name of a column in the DataFrame.
+        - factor_values (*list*):  Values in the column column_name to create factors for.
+        - factor_names (*list*):   Names to use as the factor columns.
 
     Raises:
-        ValueError:
-        - If lengths of factor_values and factor_names are not the same.
-        - If factor_name is already a column and overwrite_existing is False.
+        ValueError
+            If lengths of factor_values and factor_names are not the same.
+            If factor_name is already a column and overwrite_existing is False.
 
     """
 
@@ -62,7 +62,7 @@ def do_op(self, dispatcher, df, name, sidecar=None):
         """ Create factor columns for values in a specified column.
 
         Parameters:
-            dispatcher (Dispatcher): The dispatcher object for managing the operations.
+            dispatcher (Dispatcher): Manages the operation I/O.
             df (DataFrame): The DataFrame to be remodeled.
             name (str): Unique identifier for the dataframe -- often the original file path.
             sidecar (Sidecar or file-like):  Only needed for HED operations.

hed/tools/remodeling/operations/factor_hed_tags_op.py

@@ -13,17 +13,10 @@ class FactorHedTagsOp(BaseOp):
     """ Create tabular file factors from tag queries.
 
     Required parameters:
-    - queries (list):       Queries to be applied successively as filters.
-    - query_names (list):   Column names for the query factors.
-    - remove_types (list):  Structural HED tags to be removed .
-    - expand_context bool): Expand the context if True.
-
-    Raises:
-
-        ValueError:
-        - If the list of query_names is not empty or the same length as queries.
-        - If the query_names list contains duplicate names.
-        - If a query is invalid and cannot be parsed.
+        queries (list): Queries to be applied successively as filters.
+        query_names (list):  Column names for the query factors.
+        remove_types (list):  Structural HED tags to be removed .
+        expand_context bool): Expand the context if True.
 
     Notes:
         - If factor column names are not provided, *query1*, *query2*, ... are used.
@@ -51,17 +44,17 @@ def __init__(self, parameters):
 
         Raises:
 
-            KeyError:
-            - if a required parameter is missing.
-            - If an unexpected parameter is provided.
+            KeyError
+                - if a required parameter is missing.
+                - If an unexpected parameter is provided.
 
             TypeError:
-            - If a parameter has the wrong type.
+                - If a parameter has the wrong type.
 
             ValueError:
-            - If the specification is missing a valid operation.
-            - If the length of query names is not empty and not same length as queries.
-            - If there are duplicate query names.
+                - If the specification is missing a valid operation.
+                - If the length of query names is not empty and not same length as queries.
+                - If there are duplicate query names.
 
         """
         super().__init__(self.PARAMS, parameters)
@@ -88,15 +81,15 @@ def do_op(self, dispatcher, df, name, sidecar=None):
         """ Factor the column using HED tag queries.
 
         Parameters:
-            dispatcher (Dispatcher) - dispatcher object for managing the operations.
-            df (DataFrame) - The DataFrame to be remodeled.
-            name (str) - Unique identifier for the dataframe -- often the original file path.
-            sidecar (Sidecar or file-like)   Only needed for HED operations.
+            dispatcher (Dispatcher): Manages the operation I/O.
+            df (DataFrame): The DataFrame to be remodeled.
+            name (str): Unique identifier for the dataframe -- often the original file path.
+            sidecar (Sidecar or file-like):  Only needed for HED operations.
 
         Raises:
 
             ValueError:
-            - If a name for a new query factor column is already a column.
+                - If a name for a new query factor column is already a column.
 
         Returns:
             Dataframe: A new dataframe after processing.

hed/tools/remodeling/operations/factor_hed_type_op.py

@@ -11,11 +11,11 @@
 
 
 class FactorHedTypeOp(BaseOp):
-    """ Create tabular file factors from type variables.
+    """ Create tabular file factors from type variables and append to tabular data.
 
-   Required parameters:
-   - type_tag (str): HED tag used to find the factors (most commonly `condition-variable`).
-   - type_values (list): Factor values to include. If empty all values of that type_tag are used.
+    Required parameters:
+        - type_tag ( *str* ): HED tag used to find the factors (most commonly `condition-variable`).
+        - type_values ( *list* ): Factor values to include. If empty all values of that type_tag are used.
 
     """
 
@@ -36,27 +36,26 @@ def __init__(self, parameters):
             parameters (dict):  Actual values of the parameters for the operation.
 
         Raises:
-
-            KeyError:
-            - If a required parameter is missing.
-            - If an unexpected parameter is provided.
+            KeyError
+                If a required parameter is missing.
+                If an unexpected parameter is provided.
 
             TypeError:
-            - If a parameter has the wrong type.
+                - If a parameter has the wrong type.
 
-            - ValueError:
-            - If the specification is missing a valid operation.
+            ValueError:
+                - If the specification is missing a valid operation.
 
         """
         super().__init__(self.PARAMS, parameters)
         self.type_tag = parameters["type_tag"]
         self.type_values = parameters["type_values"]
 
     def do_op(self, dispatcher, df, name, sidecar=None):
-        """ Factor columns based on HED type.
+        """ Factor columns based on HED type and append to tabular data.
 
         Parameters:
-            dispatcher (Dispatcher): The dispatcher for managing the operations.
+            dispatcher (Dispatcher): Manages the operation I/O.
             df (DataFrame): The DataFrame to be remodeled.
             name (str): Unique identifier for the dataframe -- often the original file path.
             sidecar (Sidecar or file-like): Only needed for HED operations.

hed/tools/remodeling/operations/merge_consecutive_op.py

@@ -8,11 +8,11 @@ class MergeConsecutiveOp(BaseOp):
     """ Merge consecutive rows with same column value.
 
     Required parameters:
-        - column_name (str): the name of the column whose consecutive values are to be compared (the merge column).
-        - event_code (str or int or float): the particular value in the match column to be merged.
-        - match_columns (list):  A list of columns whose values have to be matched for two events to be the same.
-        - set_durations (bool): If true, set the duration of the merged event to the extent of the merged events.
-        - ignore_missing (bool):  If true, missing match_columns are ignored.
+        - column_name (*str*): the name of the column whose consecutive values are to be compared (the merge column).
+        - event_code (*str* or *int* or *float*): the particular value in the match column to be merged.
+        - match_columns (*list*):  A list of columns whose values have to be matched for two events to be the same.
+        - set_durations (*bool*): If true, set the duration of the merged event to the extent of the merged events.
+        - ignore_missing (*bool*):  If true, missing match_columns are ignored.
 
     """
     PARAMS = {
@@ -32,7 +32,7 @@ def __init__(self, parameters):
 
         Parameters:
             op_spec (dict): Specification for required and optional parameters.
-            parameters (dict):  Actual values of the parameters for the operation.
+            parameters (dict): Actual values of the parameters for the operation.
 
         Raises:
 
@@ -59,10 +59,10 @@ def __init__(self, parameters):
         self.ignore_missing = parameters["ignore_missing"]
 
     def do_op(self, dispatcher, df, name, sidecar=None):
-        """ Merge consecutive events of the same type
+        """ Merge consecutive rows with the same column value.
 
         Parameters:
-            dispatcher (Dispatcher): The dispatcher object for managing the operations.
+            dispatcher (Dispatcher): Manages the operation I/O.
             df (DataFrame): The DataFrame to be remodeled.
             name (str): Unique identifier for the dataframe -- often the original file path.
             sidecar (Sidecar or file-like): Only needed for HED operations.

hed/tools/remodeling/operations/number_groups_op.py

@@ -1,3 +1,4 @@
+""" Implementation in progress. """
 import numpy as np
 from hed.tools.remodeling.operations.base_op import BaseOp
 from hed.tools.util.data_util import get_indices, tuple_to_range
@@ -7,6 +8,8 @@
 
 
 class NumberGroupsOp(BaseOp):
+    """ Implementation in progress. """
+
     PARAMS = {
         "operation": "number_groups",
         "required_parameters": {
@@ -52,10 +55,10 @@ def do_op(self, dispatcher, df, name, sidecar=None):
         """ Add numbers to groups of events in dataframe.
 
         Parameters:
-            dispatcher (Dispatcher) - dispatcher object for context.
-            df (DataFrame) - The DataFrame to be remodeled.
-            name (str) - Unique identifier for the dataframe -- often the original file path.
-            sidecar (Sidecar or file-like)   Only needed for HED operations.
+            dispatcher (Dispatcher): Manages the operation I/O.
+            df (DataFrame):  The DataFrame to be remodeled.
+            name (str):  Unique identifier for the dataframe -- often the original file path.
+            sidecar (Sidecar or file-like):  Only needed for HED operations.
 
         Returns:
             Dataframe - a new dataframe after processing.

hed/tools/remodeling/operations/number_rows_op.py

@@ -1,11 +1,12 @@
+""" Implementation in progress. """
 import numpy as np
 from hed.tools.remodeling.operations.base_op import BaseOp
 
 #TODO: This class is under development
 
 
 class NumberRowsOp(BaseOp):
-
+    """ Implementation in progress. """
     PARAMS = {
         "operation": "number_rows",
         "required_parameters": {
@@ -40,10 +41,10 @@ def do_op(self, dispatcher, df, name, sidecar=None):
         """ Add numbers events dataframe.
 
         Parameters:
-            dispatcher (Dispatcher) - dispatcher object for context
-            df (DataFrame) - The DataFrame to be remodeled.
-            name (str) - Unique identifier for the dataframe -- often the original file path.
-            sidecar (Sidecar or file-like)   Only needed for HED operations.
+            dispatcher (Dispatcher): Manages operation I/O.
+            df (DataFrame): - The DataFrame to be remodeled.
+            name (str): - Unique identifier for the dataframe -- often the original file path.
+            sidecar (Sidecar or file-like):   Only needed for HED operations.
 
         Returns:
             Dataframe - a new dataframe after processing.

hed/tools/remodeling/operations/remap_columns_op.py

@@ -1,4 +1,4 @@
-""" Map combinations of values in m columns into a new combinations in n columns. """
+""" Map values in m columns into a new combinations in n columns. """
 
 import pandas as pd
 import numpy as np
@@ -7,25 +7,19 @@
 
 
 class RemapColumnsOp(BaseOp):
-    """ Map combinations of values in m columns into a new combinations in n columns.
+    """ Map values in m columns into a new combinations in n columns.
 
     Required parameters:
-        source_columns (list):  The key columns to map (m key columns).
-        destination_columns (list):  The destination columns to have the mapped values (n destination columns).
-        map_list (list):  A list of lists with the mapping.
+        source_columns (list): The key columns to map (m key columns).
+        destination_columns (list): The destination columns to have the mapped values (n destination columns).
+        map_list (list): A list of lists with the mapping.
                           Each list element list is of length m + n with the key columns followed by mapped columns.
         ignore_missing (bool): If True, entries whose key column values are not in map_list are ignored.
 
     Optional_parameters:
-        integer_sources (list): A list of the source_columns that should be treated as integers rather than strings.
+        integer_sources (list): Sour columns that should be treated as integers rather than strings.
 
-    Raises:
-        ValueError:
-            - If an integer column is not a key column.
-            - If the length of an entry list in the map_list is not m + n.
-              (Both m and n must be greater than 0.)
-
-        TODO: Allow wildcards
+    TODO: Allow wildcards
 
     """
 
@@ -46,20 +40,26 @@ def __init__(self, parameters):
         """ Constructor for the remap columns operation.
 
             Parameters:
-                parameters (dict): Dictionary with the parameter values for required and optional parameters
+                parameters (dict): Parameter values for required and optional parameters.
 
             Raises:
                 - KeyError:
                     - If a required parameter is missing.
                     - If an unexpected parameter is provided.
 
-                - TypeError:
-                    - If a parameter has the wrong type.
+                TypeError:
+                    If a parameter has the wrong type.
+
+                ValueError
+                    If an integer column is not a key column.
+
+                    If a column designated as an integer source does not have valid integers.
+
+                    If no source columns are specified.
+
+                    If no destination columns are specified.
 
-                - ValueError:
-                    - If a column designated as an integer source does not have valid integers.
-                    - If no source columns are specified.
-                    - If a map_list entry has the wrong number of items (source columns + destination columns).
+                    If a map_list entry has the wrong number of items (source columns + destination columns).
 
           """
         super().__init__(self.PARAMS, parameters)
@@ -100,10 +100,10 @@ def do_op(self, dispatcher, df, name, sidecar=None):
         """ Remap new columns from combinations of others.
 
         Parameters:
-            dispatcher (Dispatcher):  The dispatcher object for managing the operations.
-            df (DataFrame):  The DataFrame to be remodeled.
+            dispatcher (Dispatcher): Manages the operation I/O.
+            df (DataFrame): The DataFrame to be remodeled.
             name (str): Unique identifier for the dataframe -- often the original file path.
-            sidecar (Sidecar or file-like):   Only needed for HED operations.
+            sidecar (Sidecar or file-like): Only needed for HED operations.
 
         Returns:
             Dataframe: A new dataframe after processing.