Minor tweaks to docs

docs/source/api2.rst

@@ -1,5 +1,5 @@
 HED API reference (Auto style)
-========================
+==============================
 
 .. currentmodule:: hed
 

hed/models/column_mapper.py

@@ -26,19 +26,23 @@ def __init__(self, sidecar=None, tag_columns=None, column_prefix_dictionary=None
                 Sidecar column definitions will take precedent if there is a conflict with tag_columns.
             column_prefix_dictionary (dict): Dictionary with keys that are column numbers/names and values are HED tag
                 prefixes to prepend to the tags in that column before processing.
-                May be deprecated/renamed.  These are no longer prefixes, but rather converted to value columns.
-                eg. {"key": "Description", 1: "Label/"} will turn into value columns as
-                    {"key": "Description/#", 1: "Label/#"}
-                    Note: It will be a validation issue if column 1 is called "key" in the above example.
-                This means it no longer accepts anything but the value portion only in the columns.
+
             optional_tag_columns (list): A list of ints or strings containing the columns that contain
                 the HED tags. If the column is otherwise unspecified, convert this column type to HEDTags.
             warn_on_missing_column (bool): If True, issue mapping warnings on column names that are missing from
                                             the sidecar.
 
         Notes:
-            - All column numbers are 0 based.
+            - All column numbers are 0 based.  
+            - The column_prefix_dictionary may be deprecated/renamed in the future.
+                - These are no longer prefixes, but rather converted to value columns:  
+                  {"key": "Description", 1: "Label/"} will turn into value columns as
+                  {"key": "Description/#", 1: "Label/#"}
+                  It will be a validation issue if column 1 is called "key" in the above example.
+                  This means it no longer accepts anything but the value portion only in the columns.
+
         """
+
         # Maps column number to column_entry.  This is what's actually used by most code.
         self._final_column_map = {}
         self._no_mapping_info = True
@@ -384,7 +388,9 @@ def get_def_dict(self, hed_schema=None, extra_def_dicts=None):
     def get_column_mapping_issues(self):
         """ Get all the issues with finalizing column mapping(duplicate columns, missing required, etc)
 
-            Note: this is deprecated and now a wrapper for "check_for_mapping_issues()"
+        Notes:
+            - This is deprecated and now a wrapper for "check_for_mapping_issues()"
+
         Returns:
             list: A list dictionaries of all issues found from mapping column names to numbers.
 

hed/models/df_util.py

@@ -56,14 +56,14 @@ def get_assembled(tabular_file, sidecar, hed_schema, extra_def_dicts=None, join_
 
 
 def convert_to_form(df, hed_schema, tag_form, columns=None):
-    """ Convert all tags in underlying dataframe to the specified form.
+    """ Convert all tags in underlying dataframe to the specified form (in place).
 
-        Converts in place
     Parameters:
         df (pd.Dataframe): The dataframe to modify
         hed_schema (HedSchema): The schema to use to convert tags.
         tag_form(str): HedTag property to convert tags to.
-        columns (list): The columns to modify on the dataframe
+        columns (list): The columns to modify on the dataframe.
+
     """
     if isinstance(df, pd.Series):
         df = df.apply(partial(_convert_to_form, hed_schema=hed_schema, tag_form=tag_form))
@@ -78,13 +78,13 @@ def convert_to_form(df, hed_schema, tag_form, columns=None):
 
 
 def shrink_defs(df, hed_schema, columns=None):
-    """ Shrinks any def-expand tags found in the specified columns in the dataframe.
+    """ Shrink (in place) any def-expand tags found in the specified columns in the dataframe.
 
-        Converts in place
     Parameters:
         df (pd.Dataframe or pd.Series): The dataframe or series to modify
         hed_schema (HedSchema or None): The schema to use to identify defs.
         columns (list or None): The columns to modify on the dataframe.
+
     """
     if isinstance(df, pd.Series):
         mask = df.str.contains('Def-expand/', case=False)

hed/models/hed_tag.py

@@ -135,6 +135,7 @@ def short_base_tag(self, new_tag_val):
 
         Note:
             - Generally this is used to swap def to def-expand.
+
         """
         if self._schema_entry:
             tag_entry = None
@@ -156,8 +157,7 @@ def org_base_tag(self):
 
         Notes:
             - Warning: This could be empty if the original tag had a name_prefix prepended.
-            e.g. a column where "Label/" is prepended, thus the column value has zero base portion.
-
+              e.g. a column where "Label/" is prepended, thus the column value has zero base portion.
             - Only valid after calling convert_to_canonical_forms.
 
         """

hed/models/spreadsheet_input.py

@@ -21,11 +21,15 @@ def __init__(self, file=None, file_type=None, worksheet_name=None, tag_columns=N
                 first line of the file if the spreadsheet as column names.
             column_prefix_dictionary (dict): Dictionary with keys that are column numbers/names and values are HED tag
                 prefixes to prepend to the tags in that column before processing.
-                May be deprecated/renamed.  These are no longer prefixes, but rather converted to value columns.
-                eg. {"key": "Description", 1: "Label/"} will turn into value columns as
-                    {"key": "Description/#", 1: "Label/#"}
-                    Note: It will be a validation issue if column 1 is called "key" in the above example.
-                This means it no longer accepts anything but the value portion only in the columns.
+
+        Notes:
+            - column_prefix_dictionary may be deprecated/renamed.  These are no longer prefixes,
+              but rather converted to value columns.
+              eg. {"key": "Description", 1: "Label/"} will turn into value columns as
+              {"key": "Description/#", 1: "Label/#"}
+              It will be a validation issue if column 1 is called "key" in the above example.
+              This means it no longer accepts anything but the value portion only in the columns.
+
         """
         if tag_columns is None:
             tag_columns = [1]

hed/schema/hed_schema.py

@@ -12,6 +12,7 @@
 from hed.errors import ErrorHandler
 from hed.errors.error_types import ValidationErrors
 
+
 class HedSchema:
     """ A HED schema suitable for processing. """
 
@@ -93,15 +94,16 @@ def get_save_header_attributes(self, save_merged=False):
 
         """
         sort_to_start = "!!!!!!!!!!!!!!"
-        header_attributes = dict(sorted(self.header_attributes.items(), key=lambda x: sort_to_start if x[0] == constants.VERSION_ATTRIBUTE else x[0], reverse=False))
+        header_attributes = dict(sorted(self.header_attributes.items(),
+                                        key=lambda x: sort_to_start if x[0] == constants.VERSION_ATTRIBUTE else x[0],
+                                        reverse=False))
         if save_merged:
             header_attributes.pop(constants.UNMERGED_ATTRIBUTE, None)
         else:
             # make sure it's the last attribute(just to make sure it's in an order)
             header_attributes.pop(constants.UNMERGED_ATTRIBUTE, None)
             header_attributes[constants.UNMERGED_ATTRIBUTE] = "True"
 
-
         return header_attributes
 
     def schema_for_namespace(self, namespace):
@@ -139,9 +141,10 @@ def valid_prefixes(self):
     def get_as_mediawiki_string(self, save_merged=False):
         """ Return the schema to a mediawiki string.
 
-        save_merged: bool
-            If true, this will save the schema as a merged schema if it is a "withStandard" schema.
-            If it is not a "withStandard" schema, this setting has no effect.
+        Parameters:
+            save_merged (bool): If true, this will save the schema as a merged schema if it is a "withStandard" schema.
+                                If it is not a "withStandard" schema, this setting has no effect.
+
         Returns:
             str:  The schema as a string in mediawiki format.
 
@@ -153,7 +156,8 @@ def get_as_mediawiki_string(self, save_merged=False):
     def get_as_xml_string(self, save_merged=True):
         """ Return the schema to an XML string.
 
-        save_merged: bool
+        Parameters:
+            save_merged (bool):
             If true, this will save the schema as a merged schema if it is a "withStandard" schema.
             If it is not a "withStandard" schema, this setting has no effect.
         Returns:
@@ -250,7 +254,7 @@ def find_duplicate_tags(self):
 
         Notes:
             - The returned dictionary has the short-form tags as keys and lists
-            of long tags sharing the short form as the values.
+              of long tags sharing the short form as the values.
 
         """
         return self.all_tags.duplicate_names
@@ -651,9 +655,8 @@ def get_unknown_attributes(self):
             dict: The keys are attribute names and the values are lists of tags with this attribute.
 
         Notes:
-            This includes attributes found in the wrong section for example
-                unitClass attribute found on a Tag.
-            The return tag list is in long form.
+            - This includes attributes found in the wrong section for example unitClass attribute found on a Tag.
+            - The return tag list is in long form.
 
         """
         unknown_attributes = {}
@@ -762,7 +765,7 @@ def _get_attributes_for_section(self, key_class):
         if key_class == HedSectionKey.AllTags:
             return self.get_tag_attribute_names()
         elif key_class == HedSectionKey.Attributes:
-            prop_added_dict = {key:value for key, value in self._sections[HedSectionKey.Properties].items()}
+            prop_added_dict = {key: value for key, value in self._sections[HedSectionKey.Properties].items()}
             self._add_element_property_attributes(prop_added_dict)
             return prop_added_dict
         elif key_class == HedSectionKey.Properties:
@@ -797,4 +800,4 @@ def _add_tag_to_dict(self, long_tag_name, new_entry, key_class):
 
     def _create_tag_entry(self, long_tag_name, key_class):
         section = self._sections[key_class]
-        return section._create_tag_entry(long_tag_name)
+        return section._create_tag_entry(long_tag_name)

hed/schema/schema_io/schema_util.py

@@ -24,16 +24,15 @@ def get_api_key():
 
 
 def make_url_request(resource_url, try_authenticate=True):
-    """
-        Make sa request and adds the above Github access credentials
-    Args:
-        resource_url: str
-            The url to retrieve
-        try_authenticate: bool
-            If true add the above credentials
+    """ Make a request and adds the above Github access credentials.
+
+    Parameters:
+        resource_url (str): The url to retrieve.
+        try_authenticate (bool): If true add the above credentials.
 
     Returns:
         url_request
+
     """
     request = urllib.request.Request(resource_url)
     if try_authenticate and get_api_key():

hed/tools/remodeling/backup_manager.py

@@ -222,12 +222,12 @@ def _check_backup_consistency(self, backup_name):
     def get_task(task_names, file_path):
         """ Return the task if the file name contains a task_xxx where xxx is in task_names.
 
-        Args:
+        Parameters:
             task_names (list):  List of task names (without the task_ prefix).
             file_path (str):    Path of the filename to be tested.
 
         Returns:
-            str  the task name or '' if there is no task_xxx or xxx is not in task_names.
+            str:  the task name or '' if there is no task_xxx or xxx is not in task_names.
 
         """
 

hed/tools/remodeling/dispatcher.py

@@ -92,13 +92,13 @@ def get_data_file(self, file_designator):
         :raises HedFileError:
             - If a valid file cannot be found.
 
-        Notes:   
-        - If a string is passed and there is a backup manager,
-          the string must correspond to the full path of the file in the original dataset.
-          In this case, the corresponding backup file is read and returned.    
-        - If a string is passed and there is no backup manager,
-          the data file corresponding to the file_designator is read and returned.    
-        - If a Pandas DataFrame is passed, a copy is returned.    
+        Notes:  
+            - If a string is passed and there is a backup manager,
+              the string must correspond to the full path of the file in the original dataset.
+              In this case, the corresponding backup file is read and returned.    
+            - If a string is passed and there is no backup manager,
+              the data file corresponding to the file_designator is read and returned.    
+            - If a Pandas DataFrame is passed, a copy is returned.    
 
         """
         if isinstance(file_designator, pd.DataFrame):

hed/tools/util/data_util.py

@@ -277,9 +277,9 @@ def separate_values(values, target_values):
             list:  Target values present in values.
             list:  Target values missing from values.
 
-     Notes:
+     Notes:  
          - The function computes the set difference of target_cols and base_cols and returns a list
-         of columns of target_cols that are in base_cols and a list of those missing.
+           of columns of target_cols that are in base_cols and a list of those missing.
 
      """
 

hed/tools/util/io_util.py

@@ -266,10 +266,10 @@ def parse_bids_filename(file_path):
         dict:  Dictionary with key-value pair being (entity type, entity value).
 
     :raises HedFileError:
-    - If filename does not conform to name-value_suffix format.
+        - If filename does not conform to name-value_suffix format.
 
-    Notes:
-            into BIDS suffix, extension, and a dictionary of entity name-value pairs.
+    Notes:  
+        - splits into BIDS suffix, extension, and a dictionary of entity name-value pairs.
 
     """