Moved hedtools Jupyter examples from hed-examples

Author: VisLab

.github/workflows/notebook_tests.yaml

@@ -0,0 +1,59 @@
+name: Notebook Tests
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'examples/**'
+      - 'tests/test_notebooks.py'
+      - 'pyproject.toml'
+      - 'requirements*.txt'
+  pull_request:
+    branches: [main]
+    paths:
+      - 'examples/**'
+      - 'tests/test_notebooks.py'
+      - 'pyproject.toml'
+      - 'requirements*.txt'
+
+permissions:
+  contents: read
+
+jobs:
+  test-notebooks:
+    name: Test Jupyter Notebooks
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          submodules: true
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r requirements.txt
+          # Install hedtools from repo + Jupyter dependencies
+          # Note: examples/ directory is from the checkout, not PyPI
+          pip install jupyter notebook nbformat nbconvert ipykernel
+
+      - name: Test notebook structure and imports
+        run: |
+          python -m unittest tests.test_notebooks.TestNotebooks -v
+
+      - name: Test notebook execution setup
+        run: |
+          python -m unittest tests.test_notebooks.TestNotebookExecution -v
+
+      - name: List example notebooks
+        run: |
+          echo "Example notebooks found:"
+          ls -la examples/*.ipynb

.gitignore

@@ -59,6 +59,7 @@ lib/
 lib64/
 parts/
 sdist/
+.status/
 status/
 var/
 *.egg-info/

MANIFEST.in

@@ -1,3 +1,4 @@
 include versioneer.py
 include hed/_version.py
-include requirements.txt
+include requirements.txt
+recursive-include examples *.ipynb *.md

README.md

@@ -97,6 +97,36 @@ run_remodel /path/to/data /path/to/config.json
 
 For more examples, see the [user guide](https://www.hedtags.org/hed-python/user_guide.html).
 
+### Jupyter notebook examples
+
+**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:
+
+- **validate_bids_dataset.ipynb** - Validate HED annotations in a BIDS dataset
+- **summarize_events.ipynb** - Summarize event file contents and value counts
+- **sidecar_to_spreadsheet.ipynb** - Convert JSON sidecars to spreadsheet format
+- **merge_spreadsheet_into_sidecar.ipynb** - Merge spreadsheet annotations into JSON sidecars
+- **extract_json_template.ipynb** - Generate JSON sidecar templates from event files
+- **find_event_combinations.ipynb** - Find unique combinations of event values
+- **validate_bids_dataset_with_libraries.ipynb** - Validate with HED library schemas
+
+To use these notebooks:
+
+```bash
+# Clone the repository to get the examples
+git clone https://github.com/hed-standard/hed-python.git
+cd hed-python
+
+# Install HEDTools with Jupyter support
+pip install -e .[examples]
+
+# Launch Jupyter
+jupyter notebook examples/
+```
+
+See [`examples/README.md`](examples/README.md) for more details.
+
 ## Documentation
 
 📖 **Full Documentation:** [https://www.hedtags.org/hed-python](https://www.hedtags.org/hed-python)
@@ -183,7 +213,11 @@ We welcome contributions! Here's how you can help:
 git clone https://github.com/hed-standard/hed-python.git
 cd hed-python
 
-# Install in development mode with dependencies
+# Install in development mode with all dependencies (including Jupyter)
+pip install -e .[examples]
+pip install -r requirements-dev.txt
+
+# Or just core development dependencies
 pip install -e .
 pip install -r requirements.txt
 
@@ -192,6 +226,9 @@ python -m unittest discover tests
 
 # Run specific test file
 python -m unittest tests/path/to/test_file.py
+
+# Test notebooks (requires Jupyter dependencies)
+python -m unittest tests.test_notebooks
 ```
 
 For detailed contribution guidelines, please see [CONTRIBUTING.md](CONTRIBUTING.md) (coming soon).

examples/README.md

@@ -0,0 +1,67 @@
+### Jupyter notebooks to demo HED processing with BIDS
+
+The Jupyter notebooks in this directory are useful for annotating,
+validating, summarizing, and analyzing your BIDS datasets.
+
+**Table 1:** Useful Jupyter notebooks for processing BIDS datasets.
+
+| Notebooks                                                                                                                                                              | Purpose                                                                 | 
+|------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------| 
+| [`extract_json_template`](https://github.com/hed-standard/hed-examples/blob/main/src/jupyter_notebooks/bids/extract_json_template.ipynb)                               | Creates a JSON sidecar based on all the event files in a dataset.       |
+| [`find_event_combinations`](https://github.com/hed-standard/hed-examples/blob/main/src/jupyter_notebooks/bids/find_event_combinations.ipynb)                           | Creates a spreadsheet of unique combinations of event values.           |
+| [`merge_spreadsheet_into_sidecar`](https://github.com/hed-standard/hed-examples/blob/main/src/jupyter_notebooks/bids/merge_spreadsheet_into_sidecar.ipynb)             | Merges a spreadsheet version of a sidecar into a JSON sidecar.          |
+| [`sidecar_to_spreadsheet`](https://github.com/hed-standard/hed-examples/blob/main/src/jupyter_notebooks/bids/sidecar_to_spreadsheet.ipynb)                             | Converts the HED portion of a JSON sidecar into a 4-column spreadsheet. |
+| [`summarize_events`](https://github.com/hed-standard/hed-examples/blob/main/src/jupyter_notebooks/bids/summarize_events.ipynb)                                         | Summarizes the contents of the event files, including value counts.     |  
+| [`validate_bids_dataset`](https://github.com/hed-standard/hed-examples/blob/main/src/jupyter_notebooks/bids/validate_bids_dataset.ipynb)                               | Validates the HED annotations in a BIDS dataset.                        |
+| [`validate_bids_dataset_with_libraries`](https://github.com/hed-standard/hed-examples/blob/main/src/jupyter_notebooks/bids/validate_bids_dataset_with_libraries.ipynb) | Demonstrates use of HED libraries in validation.                        |  
+| [`validate_bids_datasets`](https://github.com/hed-standard/hed-examples/blob/main/src/jupyter_notebooks/bids/validate_bids_datasets.ipynb)                             | Validates the HED annotations in a list of BIDS datasets.               |  
+
+## Getting Started
+
+**Note:** These example notebooks are only available in the [GitHub repository](https://github.com/hed-standard/hed-python),
+not in the PyPI distribution. To use them, clone or download the repository.
+
+### Installation
+
+1. **Clone the repository** (to get the example notebooks):
+   ```bash
+   git clone https://github.com/hed-standard/hed-python.git
+   cd hed-python/examples
+   ```
+
+2. **Install HEDTools with Jupyter support**:
+   
+   From PyPI:
+   ```bash
+   pip install hedtools jupyter notebook
+   ```
+   
+   Or from the repository root in development mode:
+   ```bash
+   cd ..
+   pip install -e .[examples]
+   ```
+
+3. **Launch Jupyter** and open the notebooks:
+   ```bash
+   jupyter notebook
+   ```
+
+### Alternative: Download examples separately
+
+If you already have `hedtools` installed from PyPI, you can download just the examples:
+
+```bash
+# Download the examples directory from GitHub
+svn export https://github.com/hed-standard/hed-python/trunk/examples
+
+# Or manually download from:
+# https://github.com/hed-standard/hed-python/tree/main/examples
+```
+
+### Requirements
+
+- Python 3.10 or greater
+- HEDTools package
+- Jupyter notebook environment
+