Skip to content

Commit 2909367

Browse files
VisLabVisLab
committed
Worked on the user guide
1 parent aadf9ea commit 2909367

17 files changed

Lines changed: 879 additions & 355 deletions

‎.github/workflows/codespell.yaml‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,9 +3,9 @@ name: Codespell
33

44
on:
55
push:
6-
branches: [develop]
6+
branches: [main]
77
pull_request:
8-
branches: [develop]
8+
branches: [main]
99

1010
permissions:
1111
contents: read

‎.github/workflows/links.yml‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
---
2+
name: Lychee link checker
3+
4+
on:
5+
workflow_dispatch:
6+
schedule:
7+
# Run weekly on Sundays at 3 AM UTC to catch broken links
8+
- cron: '0 3 * * 0'
9+
10+
permissions:
11+
contents: read
12+
13+
jobs:
14+
link-checker:
15+
name: Lychee link checker
16+
runs-on: ubuntu-latest
17+
18+
steps:
19+
- name: Checkout
20+
uses: actions/checkout@v6
21+
22+
- name: Setup Python
23+
uses: actions/setup-python@v5
24+
with:
25+
python-version: '3.12'
26+
cache: 'pip'
27+
28+
- name: Install dependencies
29+
run: |
30+
pip install --upgrade pip
31+
pip install -r docs/requirements.txt
32+
pip install -e .
33+
34+
- name: Build documentation with Sphinx
35+
run: |
36+
cd docs
37+
sphinx-build -b html . _build/html
38+
39+
- name: Link Checker on built documentation
40+
id: lychee
41+
uses: lycheeverse/lychee-action@v2.7.0
42+
with:
43+
# Check the built HTML files recursively (includes internal links)
44+
args: --config lychee.toml --verbose --no-progress --max-redirects 10 'docs/_build/html/**/*.html'
45+
fail: true

‎.github/workflows/mdformat.yml‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
---
2+
name: Mdformat
3+
4+
on:
5+
push:
6+
branches: [main]
7+
pull_request:
8+
branches: [main]
9+
10+
permissions:
11+
contents: read
12+
13+
jobs:
14+
mdformat:
15+
name: Markdown formatting
16+
runs-on: ubuntu-latest
17+
18+
steps:
19+
- name: Checkout
20+
uses: actions/checkout@v6
21+
22+
- name: Set up Python
23+
uses: actions/setup-python@v6
24+
with:
25+
python-version: '3.12'
26+
27+
- name: Install dependencies
28+
run: |
29+
python -m pip install --upgrade pip
30+
pip install mdformat>=0.7.0 mdformat-myst>=0.1.5 mdformat-tables>=0.4.0
31+
32+
- name: Run mdformat (check only)
33+
run: |
34+
mdformat --check --wrap no --number docs/
35+
mdformat --check --wrap no --number *.md

‎.github/workflows/notebook_tests.yaml‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -41,8 +41,8 @@ jobs:
4141
run: |
4242
python -m pip install --upgrade pip
4343
pip install -r requirements.txt
44-
# Install hedtools from repo + Jupyter dependencies
45-
# Note: examples/ directory is from the checkout, not PyPI
44+
pip install -e .
45+
# Install Jupyter dependencies for running notebooks
4646
pip install jupyter notebook nbformat nbconvert ipykernel
4747
4848
- name: Test notebook structure and imports

‎.github/workflows/test_installer.yaml‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
on:
22
push:
3-
branches: ["develop"]
3+
branches: ["main"]
44
pull_request:
5-
branches: ["develop"]
5+
branches: ["main"]
66

77
jobs:
88
build:

‎.lycheeignore‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
<!-- This file lists all links/regex to be ignored by lychee in the link checker -->
2+
# ScienceDirect links (require authentication/cookies)
3+
https://www.sciencedirect.com/science/article/pii/S1053811921010387
4+
https://www.sciencedirect.com/science/article/pii/S0010945221001106
5+
https://www.sciencedirect.com/science/article/pii/S1388245717309069
6+
7+
# Springer links (503 Service Unavailable errors, but links work in browsers)
8+
^https?://link\.springer\.com/
9+
10+
# INCF links (certificate/network issues)
11+
^https?://.*\.incf\.org/
12+
^https?://incf\.org/
13+
14+
# DOI links that return 403 but work in browsers
15+
^https?://doi\.org/10\.1111/epi\.18113
16+
17+
# NPM package links (blocks automated requests)
18+
^https?://.*\.npmjs\.com/package/hed-validator
19+
20+
# MathWorks links (blocks automated requests)
21+
^https?://.*\.mathworks\.com/
22+
23+
# Brain Meeting poster links (expired/removed)
24+
^https?://brainmeeting.*\.ipostersessions\.com/
25+
^https?://globalbrainconsortium\.org/documents/GBC_March-2023_Agenda_Annual_Meeting\.pdf
26+
27+
# CANCTA network links (authentication/access issues)
28+
^https?://.*\.cancta\.net/
29+
^https?://cancta\.net/
30+
31+
# GitHub discussions (programmatic access blocked)
32+
^https?://github\.com/hed-standard/hed-python/discussions
33+
34+
# HED tools services (programmatic access blocked)
35+
^https?://hedtools\.org/hed/services_submit
36+
37+
# Neuroinformatics registration (certificate issues)
38+
^https?://neuroinformatics\.incf\.org/
39+
40+
# Internal anchor links (false positives from lychee)
41+
(_anchor|-anchor)
42+

‎docs/introduction.md‎

Lines changed: 140 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,33 +1,158 @@
1-
# Introduction to HED
1+
# Introduction to hedtools
22

3-
## Why HED?
3+
## What is HED?
44

5-
!!! info "Why use HED?"
6-
HED (Hierarchical Event Descriptors) is an infrastructure and a controlled vocabulary that allows researchers to annotate their experimental data, especially events, so that tools can automatically use this information in analysis.
5+
HED (Hierarchical Event Descriptors) is a framework for systematically describing events and experimental metadata in machine-actionable form. HED provides:
76

8-
For more information on using Hierarchical Event Descriptors (HED) visit [HED project homepage](https://www.hedtags.org).
7+
- **Controlled vocabulary** for annotating experimental data and events
8+
- **Standardized infrastructure** enabling automated analysis and interpretation
9+
- **Integration** with major neuroimaging standards (BIDS and NWB)
910

10-
## Installing hedtools
11+
For more information, visit the [HED project homepage](https://www.hedtags.org).
1112

12-
You can install hedtools from PyPI:
13+
## What is hedtools?
14+
15+
The **hedtools** Python package (`hed-python` repository) provides:
16+
17+
- **Core validation** of HED annotations against schema specifications
18+
- **BIDS integration** for neuroimaging dataset processing
19+
- **Analysis tools** for event summarization, temporal processing, and tag analysis
20+
- **Transformation utilities** for converting between formats (JSON ↔ spreadsheet)
21+
- **Command-line interface** for scripting and automation
22+
- **Jupyter notebooks** for interactive analysis workflows
23+
24+
### Related tools and resources
25+
26+
- **[HED homepage](https://www.hedtags.org)**: Overview and links for HED
27+
- **[HED Schemas](https://github.com/hed-standard/hed-schemas)**: Standardized vocabularies in XML/MediaWiki/OWL formats
28+
- **[HED Specification](https://www.hedtags.org/hed-specification/)**: Formal specification defining HED annotation rules
29+
- **[HED Online Tools](https://hedtools.org/hed)**: Web-based interface requiring no programming
30+
- **[HED Examples](https://github.com/hed-standard/hed-examples)**: Example datasets annotated with HED
31+
- **[HED Resources](https://www.hedtags.org/hed-resources)**: Comprehensive tutorials and documentation
32+
- **[HED MATLAB Tools](https://www.hedtags.org/hed-resources/HedMatlabTools.html)**: MATLAB wrapper for Python tools
33+
34+
## Installation
35+
36+
### From PyPI (Recommended)
37+
38+
Install the latest stable release:
1339

1440
```bash
1541
pip install hedtools
1642
```
1743

18-
Or install directly from the [GitHub repository](https://github.com/hed-standard/hed-python):
44+
**Note**: The PyPI package includes the core hedtools library but **not the example Jupyter notebooks**. To access the notebooks, see the options below.
45+
46+
### For Jupyter Notebook Examples
47+
48+
The example notebooks are only available in the GitHub repository. Choose one of these options:
49+
50+
**Option 1: Clone the full repository**
51+
52+
```bash
53+
git clone https://github.com/hed-standard/hed-python.git
54+
cd hed-python
55+
pip install -r requirements.txt
56+
pip install jupyter notebook
57+
# Notebooks are in: examples/
58+
```
59+
60+
**Option 2: Download just the examples directory**
61+
62+
```bash
63+
svn export https://github.com/hed-standard/hed-python/trunk/examples
64+
cd examples
65+
pip install hedtools jupyter notebook
66+
```
67+
68+
See [examples/README.md](../examples/README.md) for detailed notebook documentation.
69+
70+
### From GitHub (Latest Development Version)
71+
72+
```bash
73+
pip install git+https://github.com/hed-standard/hed-python/@main
74+
```
75+
76+
### For development
77+
78+
Clone the repository and install in editable mode:
1979

2080
```bash
21-
pip install git+https://github.com/hed-standard/hed-python.git
81+
git clone https://github.com/hed-standard/hed-python.git
82+
cd hed-python
83+
pip install -e .
84+
```
85+
86+
### Python requirements
87+
88+
- **Python 3.10 or later** is required
89+
- Core dependencies: pandas, numpy, defusedxml, openpyxl
90+
- Jupyter support: Install with `pip install jupyter notebook`
91+
92+
## Getting help
93+
94+
### Documentation resources
95+
96+
- **[User Guide](user_guide.md)**: Step-by-step instructions and examples
97+
- **[API reference](api/index.html)**: Detailed function and class documentation
98+
- **[HED specification](https://hed-specification.readthedocs.io/)**: Formal annotation rules
99+
- **[HED resources](https://www.hedtags.org/hed-resources)**: HED tutorials and guides
100+
101+
### Support
102+
103+
- **Issues and bugs**: [Open an issue](https://github.com/hed-standard/hed-python/issues) on GitHub
104+
- **Questions**: Use GitHub issues
105+
- **Online validation**: Try [HED online tools](https://hedtools.org/hed) for web-based access
106+
107+
## Quick start
108+
109+
### Basic validation example
110+
111+
```python
112+
from hed import HedString, load_schema, get_printable_issue_string
113+
114+
# Load the latest HED schema
115+
schema = load_schema()
116+
117+
# Create and validate a HED string
118+
hed_string = HedString("Sensory-event, Visual-presentation, (Onset, (Red, Square))", schema)
119+
issues = hed_string.validate(schema)
120+
121+
if issues:
122+
print(get_printable_issue_string(issues, "Validation issues found:"))
123+
else:
124+
print("✓ HED string is valid!")
22125
```
23126

24-
## Finding help
127+
### BIDS dataset validation
128+
129+
```python
130+
from hed.tools import BidsDataset
25131

26-
### Documentation
132+
# Load and validate a BIDS dataset
133+
dataset = BidsDataset("path/to/bids/dataset") # the description has schema version
134+
issues = dataset.validate()
27135

28-
- See [HED resources](https://www.hed-resources.org) for user documentation and tutorials
29-
- The [HED online tools](https://hedtools.org) provide an easy-to-use interface that requires no programming
136+
if issues:
137+
print(f"Found {len(issues)} validation issues")
138+
else:
139+
print("✓ Dataset HED annotations are valid!")
140+
```
141+
142+
### Working with sidecars
143+
144+
```python
145+
from hed import Sidecar, load_schema_version
146+
147+
# Load and validate a BIDS JSON sidecar
148+
schema = load_schema_version("8.4.0")
149+
sidecar = Sidecar("task-rest_events.json")
150+
issues = sidecar.validate(schema)
151+
```
30152

31-
### Issues and problems
153+
## Next steps
32154

33-
If you notice a bug in the python hedtools code or encounter other problems using the tools, please [open an issue](https://github.com/hed-standard/hed-python/issues) in the hed-python repository on GitHub.
155+
- **Explore the [User Guide](user_guide.md)** for detailed workflows
156+
- **Try the [Jupyter notebooks](../examples/README.md)** for interactive examples
157+
- **Check the [API Reference](api/index.html)** for complete function documentation
158+
- **Validate your data** using the [HED online tools](https://hedtools.org/hed) or the [HED browser-based tools](https://www.hedtags.org/hed-javascript)

0 commit comments

Comments
 (0)