Merge pull request #850 from VisLab/develop

Implemented context handling for factor by hed tags

hed/errors/error_reporter.py

@@ -83,7 +83,7 @@ def hed_tag_error(error_type, default_severity=ErrorSeverity.ERROR, has_sub_tag=
     Parameters:
         error_type (str): A value from error_types or optionally another value.
         default_severity (ErrorSeverity): The default severity for the decorated error.
-        has_sub_tag (bool): If true, this error message also wants a sub_tag passed down.  eg "This" in "This/Is/A/Tag"
+        has_sub_tag (bool): If True, this error message also wants a sub_tag passed down.  eg "This" in "This/Is/A/Tag"
         actual_code (str): The actual error to report to the outside world.
 
     """
@@ -442,7 +442,7 @@ def get_printable_issue_string(issues, title=None, severity=None, skip_filename=
         issues (list):  Issues to print.
         title (str):  Optional title that will always show up first if present(even if there are no validation issues).
         severity (int):        Return only warnings >= severity.
-        skip_filename (bool):  If true, don't add the filename context to the printable string.
+        skip_filename (bool):  If True, don't add the filename context to the printable string.
         add_link (bool): Add a link at the end of message to the appropriate error if True
     Returns:
         str:   A string containing printable version of the issues or ''.
@@ -466,7 +466,7 @@ def get_printable_issue_string_html(issues, title=None, severity=None, skip_file
         issues (list):  Issues to print.
         title (str):  Optional title that will always show up first if present.
         severity (int): Return only warnings >= severity.
-        skip_filename (bool): If true, don't add the filename context to the printable string.
+        skip_filename (bool): If True, don't add the filename context to the printable string.
 
     Returns:
         str: An HTML string containing the issues or ''.
@@ -568,7 +568,7 @@ def _get_context_from_issue(val_issue, skip_filename=True):
 
     Parameters:
         val_issue (dict): A dictionary a representing a single error.
-        skip_filename (bool): If true, don't gather the filename context.
+        skip_filename (bool): If True, don't gather the filename context.
 
     Returns:
         list: A list of tuples containing the context_type and context for the given issue.

hed/models/base_input.py

@@ -1,3 +1,6 @@
+"""
+Superclass representing a basic columnar file.
+"""
 import re
 import os
 

hed/models/basic_search.py

@@ -1,3 +1,6 @@
+"""
+Utilities to support HED searches based on strings.
+"""
 import re
 from itertools import combinations, product
 from collections import defaultdict

hed/models/column_mapper.py

@@ -1,3 +1,6 @@
+"""
+Mapping of a base input file columns into HED tags.
+"""
 from hed.models.column_metadata import ColumnMetadata, ColumnType
 from hed.models.sidecar import Sidecar
 from hed.errors.error_reporter import ErrorHandler
@@ -124,8 +127,8 @@ def check_for_blank_names(column_map, allow_blank_names):
         """ Validate there are no blank column names
 
         Parameters:
-            column_map(iterable): A list of column names
-            allow_blank_names(bool): Only find issues if this is true
+            column_map(iterable): A list of column names.
+            allow_blank_names(bool): Only find issues if True.
 
         Returns:
             issues(list): A list of dicts, one per issue.

hed/models/column_metadata.py

@@ -1,3 +1,6 @@
+"""
+Column type of a column in a ColumnMapper.
+"""
 from enum import Enum
 from hed.errors.error_types import SidecarErrors
 import pandas as pd

hed/models/def_expand_gather.py

@@ -1,3 +1,6 @@
+"""
+Classes to resolve ambiguities, gather, expand definitions.
+"""
 import pandas as pd
 from hed.models.definition_dict import DefinitionDict
 from hed.models.definition_entry import DefinitionEntry

hed/models/definition_dict.py

@@ -1,3 +1,4 @@
+""" Definition handler class. """
 from hed.models.definition_entry import DefinitionEntry
 from hed.models.hed_string import HedString
 from hed.errors.error_types import DefinitionErrors
@@ -7,9 +8,7 @@
 
 
 class DefinitionDict:
-    """ Gathers definitions from a single source.
-
-    """
+    """ Gathers definitions from a single source. """
 
     def __init__(self, def_dicts=None, hed_schema=None):
         """ Definitions to be considered a single source.
@@ -33,12 +32,13 @@ def add_definitions(self, def_dicts, hed_schema=None):
         """ Add definitions from dict(s) or strings(s) to this dict.
 
         Parameters:
-            def_dicts (list, DefinitionDict, dict, or str): DefinitionDict or list of DefinitionDicts/strings/dicts whose
-                definitions should be added.
-                Note - dict form expects DefinitionEntries in the same form as a DefinitionDict
+            def_dicts (list, DefinitionDict, dict, or str): DefinitionDict or list of DefinitionDicts/strings/dicts
+                                                            whose definitions should be added.
+            hed_schema(HedSchema or None): Required if passing strings or lists of strings, unused otherwise.
+
+        Note - dict form expects DefinitionEntries in the same form as a DefinitionDict
                 Note - str or list of strings will parse the strings using the hed_schema.
                 Note - You can mix and match types, eg [DefinitionDict, str, list of str] would be valid input.
-            hed_schema(HedSchema or None): Required if passing strings or lists of strings, unused otherwise.
 
         :raises TypeError:
             - Bad type passed as def_dicts

hed/models/definition_entry.py

@@ -1,7 +1,6 @@
+""" A single definition. """
 import copy
-
 from hed.models.hed_group import HedGroup
-from hed.models.model_constants import DefTagNames
 
 
 class DefinitionEntry:
@@ -33,7 +32,7 @@ def get_definition(self, replace_tag, placeholder_value=None, return_copy_of_tag
             replace_tag (HedTag): The def hed tag to replace with an expanded version
             placeholder_value (str or None):    If present and required, will replace any pound signs
                                                 in the definition contents.
-            return_copy_of_tag(bool): Set to true for validation
+            return_copy_of_tag(bool): Set to True for validation
 
         Returns:
             HedGroup:     The contents of this definition(including the def tag itself)

hed/models/df_util.py

@@ -1,6 +1,6 @@
+""" Utilities for handling the assembly and conversion of HED strings to different forms. """
 from functools import partial
 import pandas as pd
-
 from hed.models.sidecar import Sidecar
 from hed.models.tabular_input import TabularInput
 from hed.models.hed_string import HedString
@@ -9,7 +9,7 @@
 
 def get_assembled(tabular_file, sidecar, hed_schema, extra_def_dicts=None, join_columns=True,
                   shrink_defs=False, expand_defs=True):
-    """Load a tabular file and its associated HED sidecar file.
+    """ Create an array of assembled HedString objects (or list of these) of the same length as tabular file with.
 
     Args:
         tabular_file: str or TabularInput
@@ -21,7 +21,7 @@ def get_assembled(tabular_file, sidecar, hed_schema, extra_def_dicts=None, join_
         extra_def_dicts: list of DefinitionDict, optional
             Any extra DefinitionDict objects to use when parsing the HED tags.
         join_columns: bool
-            If true, join all HED columns into one.
+            If True, join all HED columns into one.
         shrink_defs: bool
             Shrink any def-expand tags found
         expand_defs: bool
@@ -117,7 +117,8 @@ def expand_defs(df, hed_schema, def_dict, columns=None):
 
         for column in columns:
             mask = df[column].str.contains('Def/', case=False)
-            df.loc[mask, column] = df.loc[mask, column].apply(partial(_expand_defs, hed_schema=hed_schema, def_dict=def_dict))
+            df.loc[mask, column] = df.loc[mask, column].apply(partial(_expand_defs,
+                                                                      hed_schema=hed_schema, def_dict=def_dict))
 
 
 def _convert_to_form(hed_string, hed_schema, tag_form):

hed/models/expression_parser.py

@@ -1,7 +1,9 @@
+""" Holder for and manipulation of search results. """
 import re
 
 
 class SearchResult:
+    """ Holder for and manipulation of search results. """
     def __init__(self, group, tag):
         self.group = group
         # todo: rename tag: children

hed/models/hed_group.py

@@ -1,3 +1,4 @@
+""" A single parenthesized hed string. """
 from hed.models.hed_tag import HedTag
 import copy
 from typing import Iterable, Union
@@ -237,7 +238,7 @@ def get_all_groups(self, also_return_depth=False):
 
     @staticmethod
     def _check_in_group(group, group_list):
-        """ Return true if the group is list.
+        """ Return True if the group is list.
 
         Parameters:
             group (HedGroup): The group to check for.
@@ -458,7 +459,7 @@ def find_wildcard_tags(self, search_tags, recursive=False, include_groups=2):
 
         Parameters:
             search_tags (container):    A container of the starts of short tags to search.
-            recursive (bool):           If true, also check subgroups.
+            recursive (bool):           If True, also check subgroups.
             include_groups (0, 1 or 2): Specify return values.
                 If 0: return a list of the HedTags.
                 If 1: return a list of the HedGroups containing the HedTags.

hed/models/hed_string.py

@@ -1,14 +1,12 @@
-"""
-This module is used to split tags in a HED string.
-"""
+""" A HED string with its schema and definitions. """
 import copy
 from hed.models.hed_group import HedGroup
 from hed.models.hed_tag import HedTag
 from hed.models.model_constants import DefTagNames
 
 
 class HedString(HedGroup):
-    """ A HED string. """
+    """ A HED string with its schema and definitions. """
 
     OPENING_GROUP_CHARACTER = '('
     CLOSING_GROUP_CHARACTER = ')'
@@ -278,7 +276,7 @@ def split_hed_string(hed_string):
 
         Notes:
             - The tuple format is as follows
-                - is_hed_tag (bool): A (possible) hed tag if true, delimiter if not.
+                - is_hed_tag (bool): A (possible) hed tag if True, delimiter if not.
                 - start_pos (int):   Index of start of string in hed_string.
                 - end_pos (int):     Index of end of string in hed_string
 

hed/models/hed_tag.py

@@ -1,3 +1,4 @@
+""" A single HED tag. """
 from hed.schema.hed_schema_constants import HedKey
 import copy
 
@@ -158,7 +159,7 @@ def org_base_tag(self):
         return str(self)
 
     def tag_modified(self):
-        """ Return true if tag has been modified from original.
+        """ Return True if tag has been modified from original.
 
         Returns:
             bool: Return True if the tag is modified.
@@ -247,10 +248,10 @@ def org_tag(self):
     def expanded(self):
         """Returns if this is currently expanded or not.
 
-           Will always be false unless expandable is set.  This is primarily used for Def/Def-expand tags at present.
+           Will always be False unless expandable is set.  This is primarily used for Def/Def-expand tags at present.
 
         Returns:
-            bool: Returns true if this is currently expanded
+            bool: Returns True if this is currently expanded
         """
         return self._expanded
 

hed/models/model_constants.py

@@ -1,3 +1,4 @@
+""" Defined constants for definitions, def labels, and expanded labels"""
 COLUMN_TO_HED_TAGS = "column_to_hed_tags"
 ROW_HED_STRING = "HED"
 COLUMN_ISSUES = "column_issues"

hed/models/sidecar.py

@@ -1,3 +1,4 @@
+""" Contents of a JSON file or merged file. """
 import json
 import re
 

hed/models/spreadsheet_input.py

@@ -1,3 +1,4 @@
+""" A spreadsheet of HED tags. """
 from hed.models.column_mapper import ColumnMapper
 from hed.models.base_input import BaseInput
 
@@ -19,7 +20,8 @@ def __init__(self, file=None, file_type=None, worksheet_name=None, tag_columns=N
                 The default value is [1] indicating only the second column has tags.
             has_column_names (bool): True if file has column names. Validation will skip over the first row.
                 first line of the file if the spreadsheet as column names.
-            column_prefix_dictionary (dict or None): Dictionary with keys that are column numbers/names and values are HED tag
+            column_prefix_dictionary (dict or None): Dictionary with keys that are column numbers/names and
+                                                     values are HED tag
                 prefixes to prepend to the tags in that column before processing.
 
         Notes:

hed/models/string_util.py

@@ -1,3 +1,4 @@
+""" Utilities for manipulating HedString objects. """
 from hed.models.hed_string import HedString
 
 

hed/models/tabular_input.py

@@ -1,10 +1,11 @@
+""" A BIDS tabular file with sidecar. """
 from hed.models.column_mapper import ColumnMapper
 from hed.models.base_input import BaseInput
 from hed.models.sidecar import Sidecar
 
 
 class TabularInput(BaseInput):
-    """ A BIDS tabular tsv file with sidecar. """
+    """ A BIDS tabular file with sidecar. """
 
     HED_COLUMN_NAME = "HED"
 

hed/models/timeseries_input.py

@@ -1,9 +1,10 @@
+""" A BIDS time series tabular file. """
 from hed.models.base_input import BaseInput
 from hed.models.sidecar import Sidecar
 
 
 class TimeseriesInput(BaseInput):
-    """ A BIDS time series tsv file."""
+    """ A BIDS time series tabular file. """
 
     HED_COLUMN_NAME = "HED"
 

hed/schema/hed_cache.py

@@ -327,8 +327,8 @@ def _get_hed_xml_versions_from_url(hed_base_url, library_name=None,
     Parameters:
         hed_base_url (str): A single GitHub API url to cache
         library_name(str or None): If str, cache only the named library schemas
-        skip_folders (list): A list of subfolders to skip over when downloading.
-        get_libraries (bool): If true, return a dictionary of version numbers, with an entry for each library name.
+        skip_folders (list): A list of sub folders to skip over when downloading.
+        get_libraries (bool): If True, return a dictionary of version numbers, with an entry for each library name.
 
     Returns:
         list or dict: List of version numbers or dictionary {library_name: [versions]}.

hed/schema/hed_schema.py

@@ -235,7 +235,7 @@ def get_as_mediawiki_string(self, save_merged=False):
         """ Return the schema to a mediawiki string.
 
         Parameters:
-            save_merged (bool): If true, this will save the schema as a merged schema if it is a "withStandard" schema.
+            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:
@@ -249,10 +249,10 @@ def get_as_owl_string(self, save_merged=False, file_format="owl"):
         """ Return the schema to a mediawiki string.
 
         Parameters:
-            save_merged (bool): If true, this will save the schema as a merged schema if it is a "withStandard" schema.
+            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.
             file_format(str or None): Override format from filename extension.
-                Accepts any value rdflib accepts(We fully support "turtle", "xml"("owl" also accepted) and "json-ld")
+                Accepts any value rdflib accepts(We fully support "turtle", "xml"("owl" also accepted) and "json-ld").
                 Other values should work, but aren't as fully supported.
         Returns:
             str:  The schema as a string in mediawiki format.
@@ -270,7 +270,7 @@ def get_as_xml_string(self, save_merged=True):
 
         Parameters:
             save_merged (bool):
-            If true, this will save the schema as a merged schema if it is a "withStandard" schema.
+            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: Return the schema as an XML string.
@@ -285,11 +285,11 @@ def save_as_mediawiki(self, filename, save_merged=False):
         filename: str
             save location
         save_merged: bool
-            If true, this will save the schema as a merged schema if it is a "withStandard" schema.
+            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.
 
         :raises OSError:
-            - File cannot be saved for some reason
+            - File cannot be saved for some reason.
         """
         output_strings = Schema2Wiki.process_schema(self, save_merged)
         with open(filename, mode='w', encoding='utf-8') as opened_file:
@@ -303,7 +303,7 @@ def save_as_owl(self, filename, save_merged=False, file_format=None):
         filename: str
             Save the file here
         save_merged: bool
-            If true, this will save the schema as a merged schema if it is a "withStandard" schema.
+            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.
         file_format(str or None): Required for owl formatted files other than the following:
             .ttl: turtle

hed/schema/hed_schema_entry.py

@@ -296,7 +296,7 @@ def _check_inherited_attribute(self, attribute, return_value=False, return_union
             attribute (str): The attribute to check for.
             return_value (bool): If True, returns the actual value of the attribute.
                                  If False, returns a boolean indicating the presence of the attribute.
-            return_union(bool): If true, return a union of all parent values
+            return_union(bool): If True, return a union of all parent values.
 
         Returns:
             bool or any: Depending on the flag return_value,

hed/schema/hed_schema_section.py

@@ -77,7 +77,7 @@ def get_entries_with_attribute(self, attribute_name, return_name_only=False, sch
 
         Parameters:
             attribute_name (str): The name of the attribute(generally a HedKey entry).
-            return_name_only (bool): If true, return the name as a string rather than the tag entry.
+            return_name_only (bool): If True, return the name as a string rather than the tag entry.
             schema_namespace (str): Prepends given namespace to each name if returning names.
 
         Returns: