From 9cb0f50fceb6e9fb158c30cfb96a31b062608e68 Mon Sep 17 00:00:00 2001 From: Kay Robbins <1189050+VisLab@users.noreply.github.com> Date: Mon, 26 Jan 2026 10:03:02 -0600 Subject: [PATCH 1/2] Renamed various headings in the docs --- README.md | 45 ++++++++++++++++++++++++++++++++++++++++++ docs/api/errors.rst | 4 ++-- docs/api/index.rst | 4 ++-- docs/api/models.rst | 4 ++-- docs/api/schema.rst | 4 ++-- docs/api/tools.rst | 4 ++-- docs/api/validator.rst | 4 ++-- docs/index.rst | 4 ++-- docs/overview.md | 23 ++++++++++++++++++++- docs/user_guide.md | 42 +++++++++++++++++++++++++++++++++++++++ examples/README.md | 33 +++++++++++++++++++++++++++++++ 11 files changed, 156 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index 8a36ddc7..0426fb82 100644 --- a/README.md +++ b/README.md @@ -2,10 +2,16 @@ # HEDTools - Python +```{index} HEDTools, Python tools, validation, analysis +``` + > Python tools for validation, analysis, and transformation of HED (Hierarchical Event Descriptors) tagged datasets. ## Overview +```{index} HED, Hierarchical Event Descriptors, BIDS, NWB +``` + HED (Hierarchical Event Descriptors) is a framework for systematically describing both laboratory and real-world events as well as other experimental metadata. HED tags are comma-separated path strings that provide a standardized vocabulary for annotating events and experimental conditions. **Key Features:** @@ -20,8 +26,14 @@ HED (Hierarchical Event Descriptors) is a framework for systematically describin ## Quick start +```{index} quick start, getting started, installation +``` + ### Online tools (no installation required) +```{index} online tools, web tools, hedtools.org +``` + For simple validation or transformation tasks, use the online tools at [https://hedtools.org/hed](https://hedtools.org/hed) - no installation needed! Browser-based validation (no data upload) is available at [https://www.hedtags.org/hed-javascript](https://www.hedtags.org/hed-javascript) @@ -30,6 +42,9 @@ A development version of the online tools is available at: [https://hedtools.org ### Python installation +```{index} installation; Python, pip install, PyPI +``` + **Requirements:** Python 3.10 or higher Install from PyPI: @@ -46,6 +61,9 @@ pip install git+https://github.com/hed-standard/hed-python/@main ### Basic usage +```{index} usage examples, HedString, load_schema_version, validation example +``` + ```python from hed import HedString, load_schema_version @@ -65,6 +83,9 @@ else: ### Command-line tools +```{index} command-line tools, CLI, hedpy, validate-bids, extract-sidecar +``` + HEDTools provides a unified command-line interface with git-like subcommands: ```bash @@ -97,6 +118,9 @@ For more examples, see the [user guide](https://www.hedtags.org/hed-python/user_ ### Jupyter notebook examples +```{index} Jupyter notebooks, examples, interactive workflows +``` + **Note:** Example notebooks are available in the [GitHub repository](https://github.com/hed-standard/hed-python/tree/main/examples) only, not in the PyPI package. The [`examples/`](examples/) directory contains Jupyter notebooks demonstrating common HED workflows with BIDS datasets: @@ -127,6 +151,9 @@ See [`examples/README.md`](examples/README.md) for more details. ## Documentation +```{index} documentation, user guide, API reference, Sphinx +``` + 📖 **Full Documentation:** [https://www.hedtags.org/hed-python](https://www.hedtags.org/hed-python) - [User guide](https://www.hedtags.org/hed-python/user_guide.html) - Usage instructions @@ -135,6 +162,9 @@ See [`examples/README.md`](examples/README.md) for more details. ### Building docs locally +```{index} building documentation, sphinx-build +``` + ```bash # Install documentation dependencies pip install -e .[docs] @@ -152,6 +182,9 @@ make html ### Formatting with Black +```{index} Black, code formatting, style guide +``` + This project uses [Black](https://black.readthedocs.io/) for consistent code formatting. ```bash @@ -184,6 +217,9 @@ black --workers 1 . ## Related repositories +```{index} HED ecosystem, repositories, hed-schemas, hed-specification +``` + The HED ecosystem consists of several interconnected repositories: | Repository | Description | @@ -198,6 +234,9 @@ The HED ecosystem consists of several interconnected repositories: ## Contributing +```{index} contributing, development setup, pull requests +``` + We welcome contributions! Here's how you can help: 1. **Report issues:** Use [GitHub Issues](https://github.com/hed-standard/hed-python/issues) for bug reports and feature requests @@ -234,8 +273,14 @@ For detailed contribution guidelines, please see [CONTRIBUTING.md](CONTRIBUTING. ## Configuration +```{index} configuration, schema caching, cache directory +``` + ### Schema caching +~~~{index} schema; caching, ~/.hedtools +~~~ + By default, HED schemas are cached in `~/.hedtools/` (location varies by OS). ```python diff --git a/docs/api/errors.rst b/docs/api/errors.rst index 8b58a4c0..94715532 100644 --- a/docs/api/errors.rst +++ b/docs/api/errors.rst @@ -1,5 +1,5 @@ -Errors -====== +Python HEDTools error handling +============================== Error handling and reporting classes for HED validation and processing. diff --git a/docs/api/index.rst b/docs/api/index.rst index 44c4ebc2..111712da 100644 --- a/docs/api/index.rst +++ b/docs/api/index.rst @@ -1,7 +1,7 @@ Python HEDTools API =================== -This section contains the complete API reference for HED Python tools. +This section contains the complete API reference for Python HEDTools. .. toctree:: :maxdepth: 2 @@ -15,7 +15,7 @@ This section contains the complete API reference for HED Python tools. Core modules overview --------------------- -The HED Python tools package is organized into several key modules: +The Python HEDTools package is organized into several key modules: * **Models**: Core data structures for HED annotations and tags * **Schema**: HED schema management and validation diff --git a/docs/api/models.rst b/docs/api/models.rst index 48dc5392..beb8f53e 100644 --- a/docs/api/models.rst +++ b/docs/api/models.rst @@ -1,5 +1,5 @@ -Models -====== +Python HEDTools models +============================= Core data models for working with HED data structures. diff --git a/docs/api/schema.rst b/docs/api/schema.rst index b9be25a2..cabe03bd 100644 --- a/docs/api/schema.rst +++ b/docs/api/schema.rst @@ -1,5 +1,5 @@ -Schema -====== +Python HEDTools schema +====================== HED schema management and validation tools. diff --git a/docs/api/tools.rst b/docs/api/tools.rst index 414c3e94..e00c2087 100644 --- a/docs/api/tools.rst +++ b/docs/api/tools.rst @@ -1,5 +1,5 @@ -Tools -===== +Python HEDTools tools +============================= Utility functions and data processing tools for HED operations. diff --git a/docs/api/validator.rst b/docs/api/validator.rst index 2b25ce8d..a25b0360 100644 --- a/docs/api/validator.rst +++ b/docs/api/validator.rst @@ -1,5 +1,5 @@ -Validator -========= +Python HEDTools validator +========================= Validation tools for HED data structures and annotations. diff --git a/docs/index.rst b/docs/index.rst index f872e06a..b0d83d7e 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -45,7 +45,7 @@ Python HEDTools API API -Index -===== +Python HEDtools index +---------------------- * :ref:`genindex` diff --git a/docs/overview.md b/docs/overview.md index 7c78256b..477c9175 100644 --- a/docs/overview.md +++ b/docs/overview.md @@ -1,7 +1,13 @@ # Python HEDTools overview +```{index} single: HED; overview +``` + ## What is HED? +```{index} HED, Hierarchical Event Descriptors, controlled vocabulary, BIDS, NWB +``` + HED (Hierarchical Event Descriptors) is a framework for systematically describing events and experimental metadata in machine-actionable form. HED provides: - **Controlled vocabulary** for annotating experimental data and events @@ -10,7 +16,10 @@ HED (Hierarchical Event Descriptors) is a framework for systematically describin For more information, visit the HED project [homepage](https://www.hedtags.org) and the [resources page](https://www.hedtags.org/hed-resources). The [table-remodeler](https://www.hedtags.org/table-remodeler) tools are now in a separate repository. -## What is HEDTools? +## What are Pythong HEDTools? + +```{index} hedtools, validation, BIDS integration, NWB support +``` The **hedtools** Python package (`hed-python` repository) provides: @@ -36,6 +45,9 @@ The **hedtools** Python package (`hed-python` repository) provides: ## Installation +```{index} installation, pip, PyPI +``` + ### From PyPI (recommended) Install the latest stable release: @@ -112,6 +124,9 @@ pip install -e . ### Basic validation example +```{index} validation; HED string, HedString +``` + ```python from hed import HedString, load_schema, get_printable_issue_string @@ -130,6 +145,9 @@ else: ### BIDS dataset validation +```{index} BIDS; validation, BidsDataset +``` + ```python from hed.tools import BidsDataset @@ -145,6 +163,9 @@ else: ### Working with sidecars +```{index} sidecar, JSON sidecar, Sidecar class +``` + ```python from hed import Sidecar, load_schema_version diff --git a/docs/user_guide.md b/docs/user_guide.md index c27f1928..b1f5bc8b 100644 --- a/docs/user_guide.md +++ b/docs/user_guide.md @@ -1,5 +1,8 @@ # Python HEDTools guide +```{index} user guide, tutorial, getting started +``` + This guide provides step-by-step instructions for using the HED Python tools for validation, BIDS integration, and analysis. ## Quick links @@ -63,6 +66,9 @@ else: ## Working with HED schemas +```{index} schema; loading, schema; validation, load_schema, load_schema_version +``` + ### Loading schemas ```python @@ -83,6 +89,9 @@ schema = load_schema("https://raw.githubusercontent.com/hed-standard/hed-schemas ### Working with library schemas +```{index} schema; library, library schema, score library, lang library +``` + HED supports library schemas that extend the base vocabulary. ```python @@ -100,6 +109,9 @@ Note: It is now standard for a library schema to be partnered with a standard sc ## Validating HED strings +```{index} validation; HED strings, HedString class, validate method +``` + ### Basic validation The HED string must be created with a schema, and validation is performed on the string object: @@ -137,6 +149,9 @@ if issues: ## Working with BIDS datasets +```{index} BIDS; dataset validation, BidsDataset class, dataset_description.json +``` + ### Dataset-level validation ```python @@ -162,6 +177,9 @@ Since a BIDS dataset includes the HED version in its `dataset_description.json`, ### Working with individual event files +```{index} TabularInput, event files, tsv files +``` + ```python from hed import TabularInput, load_schema_version @@ -184,6 +202,9 @@ def_dict = tabular.get_def_dict(schema) ## Working with sidecars +```{index} Sidecar class, JSON sidecar, sidecar validation +``` + ### Loading and validating sidecars ```python @@ -201,6 +222,9 @@ issues = sidecar.validate(schema) ### Extracting definitions +```{index} definitions, DefinitionDict, get_def_dict +``` + ```python from hed import Sidecar, load_schema_version @@ -228,6 +252,9 @@ json_string = sidecar.get_as_json_string() ## Jupyter notebooks +```{index} Jupyter notebooks, examples, workflows +``` + The [examples](https://github.com/hed-standard/hed-python/tree/main/examples) directory in the GitHub [hed-python](https://github.com/hed-standard/hed-python) repository contains Jupyter notebooks for BIDS annotation workflows. These notebooks are **not included in the PyPI package**. ### Available notebooks @@ -275,6 +302,9 @@ See the examples [README](https://github.com/hed-standard/hed-python/tree/main/e ## Command-line tools +```{index} CLI, command-line interface, hedpy, scripts +``` + HEDTools provides a unified command-line interface (CLI) using a **git-style command structure**. The main command is `hedpy`, which provides subcommands for validation and schema management. ### Available commands @@ -509,6 +539,9 @@ ______________________________________________________________________ ### Schema development +```{index} schema; development, schema; conversion, schema; validation, hedpy schema +``` + The `hedpy schema` command group provides tools for validating, converting, and managing HED schemas during development. #### Schema validation @@ -557,6 +590,9 @@ Once a schema has been developed and tested, these commands prepare it for offic #### Add HED IDs +```{index} HED IDs, schema; IDs, schema; release +``` + HED IDs are unique identifiers assigned to each schema term, enabling stable references across schema versions and format conversions. These IDs must be added before releasing a schema. ```bash @@ -678,6 +714,9 @@ ______________________________________________________________________ ## Best practices +```{index} best practices, schema management, validation workflow +``` + ### Schema management 1. **Don't modify released schemas** - they're immutable and shared @@ -724,6 +763,9 @@ If you are annotating an NWB dataset, the instructions are somewhat similar but ## Troubleshooting +```{index} troubleshooting, errors, debugging +``` + ### Common issues #### Schema loading errors diff --git a/examples/README.md b/examples/README.md index 70c73d87..2d720588 100644 --- a/examples/README.md +++ b/examples/README.md @@ -1,11 +1,17 @@ # Jupyter notebooks for annotation +```{index} Jupyter notebooks, annotation workflows, examples +``` + This directory contains Jupyter notebooks that provide interactive workflows for annotation, validation, and analysis. **📖 For detailed documentation, see the [Jupyter notebooks section](../docs/user_guide.md#jupyter-notebooks)** ## Available Notebooks +```{index} notebooks list, extract template, validate dataset, sidecar conversion +``` + | Notebook | Purpose | | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------ | | [extract_json_template.ipynb](extract_json_template.ipynb) | Create JSON sidecar template from all event files in dataset | @@ -19,6 +25,9 @@ This directory contains Jupyter notebooks that provide interactive workflows for ## Quick Start +```{index} quick start; notebooks, installation; notebooks +``` + ### Prerequisites - **Python 3.10+** required @@ -51,6 +60,9 @@ jupyter notebook ## Typical Annotation Workflow +```{index} annotation workflow, BIDS annotation, workflow steps +``` + A recommended workflow for annotating a new BIDS dataset: 1. **📊 Summarize events** → Understand your event structure @@ -62,38 +74,59 @@ A recommended workflow for annotating a new BIDS dataset: ## Notebook descriptions +```{index} notebook descriptions, templates, validation, spreadsheet conversion +``` + ### Extract JSON template +```{index} extract template, JSON template, sidecar template +``` + Creates a JSON sidecar template based on all unique values found across all event files in your BIDS dataset. **Key parameters**: `dataset_path`, `exclude_dirs`, `skip_columns`, `value_columns` ### Find event combinations +```{index} event combinations, column relationships +``` + Extracts all unique combinations of values across specified columns, useful for understanding column relationships or creating recoding mappings. **Key parameters**: `dataset_path`, `key_columns`, `output_path` ### Merge spreadsheet into sidecar +```{index} merge spreadsheet, spreadsheet to JSON, annotation merging +``` + Merges a 4-column spreadsheet (with edited HED annotations) back into a BIDS JSON sidecar file (which could be empty). **Key parameters**: `spreadsheet_path`, `sidecar_path`, `description_tag`, `output_path` ### Sidecar to Spreadsheet +```{index} sidecar to spreadsheet, JSON to spreadsheet, 4-column format +``` + Converts the HED content of a JSON sidecar into a 4-column spreadsheet for easier viewing and editing. **Output format**: `column_name | column_value | description | HED` ### Summarize events +```{index} summarize events, event analysis, value distributions +``` + Provides an overview of event file structure, column names, and value distributions across the entire dataset. **Key parameters**: `dataset_path`, `exclude_dirs`, `skip_columns`, `value_columns` ### Validate BIDS dataset +```{index} validate BIDS, dataset validation, HED validation +``` + Validates all HED annotations in a BIDS dataset against the specified schema. **Key parameters**: `dataset_path`, `check_for_warnings` From fb016382f417dfc09cbb4da2881087721a791fb9 Mon Sep 17 00:00:00 2001 From: Kay Robbins <1189050+VisLab@users.noreply.github.com> Date: Mon, 26 Jan 2026 10:28:24 -0600 Subject: [PATCH 2/2] Fixed spelling error --- docs/overview.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/overview.md b/docs/overview.md index 477c9175..0d74013f 100644 --- a/docs/overview.md +++ b/docs/overview.md @@ -16,7 +16,7 @@ HED (Hierarchical Event Descriptors) is a framework for systematically describin For more information, visit the HED project [homepage](https://www.hedtags.org) and the [resources page](https://www.hedtags.org/hed-resources). The [table-remodeler](https://www.hedtags.org/table-remodeler) tools are now in a separate repository. -## What are Pythong HEDTools? +## What are Python HEDTools? ```{index} hedtools, validation, BIDS integration, NWB support ```