This comprehensive guide provides step-by-step instructions for using HED Python tools in various scenarios, from basic validation to advanced analysis workflows.
- Getting Started
- Working with HED Schemas
- Validating HED Strings
- Working with BIDS Datasets
- Spreadsheet Integration
- Advanced Usage
- Best Practices
- Troubleshooting
Install HEDTools from PyPI:
pip install hedtoolsFor the latest development version from GitHub:
pip install git+https://github.com/hed-standard/hed-python/@mainHere's a simple example to get you started with HED validation:
from hed import HedString, load_schema
# Load the latest HED schema
schema = load_schema()
# Create a HED string
hed_string = HedString("Sensory-event, Visual-presentation, (Onset, (Red, Square))")
# Validate the string
issues = hed_string.validate(schema)
if issues:
print("Validation issues found:")
for issue in issues:
print(f" - {issue}")
else:
print("✓ HED string is valid!")from hed import load_schema
# Load the latest official schema
schema = load_schema()
# Load a specific version
schema = load_schema(version="8.2.0")
# Load from a local file
schema = load_schema("path/to/schema.xml")
# Load from URL
schema = load_schema("https://example.com/schema.xml")# Get schema version
print(f"Schema version: {schema.version}")
# Get all tags
all_tags = schema.get_all_tags()
# Check if a tag exists
exists = schema.check_compliance("Sensory-event")
# Get tag attributes
attributes = schema.get_tag_attributes("Sensory-event")from hed import HedString
hed_string = HedString("Red, Blue, Green")
issues = hed_string.validate(schema)
# Check for specific types of errors
syntax_issues = [issue for issue in issues if issue.code == 'SYNTAX_ERROR']hed_strings = [
"Sensory-event, Visual-presentation",
"Invalid-tag, Another-invalid",
"Onset, (Red, Square)"
]
for i, hed_str in enumerate(hed_strings):
hed_string = HedString(hed_str)
issues = hed_string.validate(schema)
if issues:
print(f"String {i+1} has {len(issues)} issues")from hed.models import TabularInput
import pandas as pd
# Load events file
events_df = pd.read_csv("sub-01_task-rest_events.tsv", sep='\t')
# Create tabular input
tabular = TabularInput(events_df, name="events")
# Validate HED annotations
issues = tabular.validate(schema)from hed.models import Sidecar
# Load and validate sidecar
sidecar = Sidecar("task-rest_events.json")
issues = sidecar.validate(schema)
# Extract HED strings
hed_dict = sidecar.extract_definitions(schema)from hed.models import SpreadsheetInput
# Load spreadsheet
spreadsheet = SpreadsheetInput("data.xlsx", worksheet_name="Sheet1")
# Validate HED columns
issues = spreadsheet.validate(schema, hed_columns=[2, 3])import os
from pathlib import Path
data_dir = Path("data/")
for file_path in data_dir.glob("*.xlsx"):
spreadsheet = SpreadsheetInput(str(file_path))
issues = spreadsheet.validate(schema)
if issues:
print(f"Issues in {file_path.name}: {len(issues)}")from hed.validator import HedValidator
validator = HedValidator(schema)
# Custom validation rules
def custom_validation(hed_string):
# Your custom logic here
return []
# Apply custom validation
issues = custom_validation(hed_string)# Compare schemas
from hed.schema import schema_comparer
differences = schema_comparer.compare_schemas(old_schema, new_schema)
# Merge schemas
merged_schema = old_schema.merge_with(extension_schema)from hed.errors import HedFileError, ErrorHandler
try:
schema = load_schema("invalid_path.xml")
except HedFileError as e:
print(f"Error loading schema: {e}")
# Custom error handling
error_handler = ErrorHandler()
error_handler.add_context("Processing file: data.xlsx")- Always validate your HED strings before using them in analysis
- Use the latest schema version unless you have specific requirements
- Handle errors gracefully in production code
- Cache schemas when processing multiple files
- Use batch processing for large datasets
- Schema not found: Ensure you have internet connection for downloading schemas
- Validation errors: Check HED syntax and schema compliance
- File format issues: Ensure your files are properly formatted TSV/CSV/JSON
- Check the API Reference for detailed function documentation
- Visit our GitHub Issues page
- Consult the HED specification