Skip to content

Commit d8c288e

Browse files
VisLabVisLab
authored
Merge pull request #1188 from VisLab/add_examples
Updated the spec_test location and the documentation for the CLI
2 parents 2e3183e + c52a50b commit d8c288e

File tree

49 files changed

+20626
-21
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

49 files changed

+20626
-21
lines changed

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -136,6 +136,7 @@ hed_cache/
136136
spec_tests/hed-specification/tests
137137
spec_tests/hed-examples
138138
spec_tests/*.json
139+
spec_tests/hed-tests/json_test_data
139140

140141
# GitHub Copilot instructions (project-specific)
141142
.github/copilot-instructions.md

‎.gitmodules‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
1-
[submodule "spec_tests/hed-specification"]
2-
path = spec_tests/hed-specification
3-
url = https://github.com/hed-standard/hed-specification/
1+
[submodule "spec_tests/hed-tests"]
2+
path = spec_tests/hed-tests
3+
url = https://github.com/hed-standard/hed-tests/
44
branch = main
55

66
[submodule "spec_tests/hed-examples"]

docs/source/_static/images/croppedWideLogo.png renamed to docs/_static/images/croppedWideLogo.png

File renamed without changes.

‎docs/conf.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -38,7 +38,7 @@
3838
html_js_files = ["gh_icon_fix.js"]
3939

4040
# Add logo
41-
html_logo = "source/_static/images/croppedWideLogo.png"
41+
html_logo = "_static/images/croppedWideLogo.png"
4242

4343
# Furo theme options
4444
html_theme_options = {

‎docs/user_guide.md‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -283,6 +283,9 @@ HEDTools provides a unified command-line interface (CLI) using a **git-style com
283283
| ----------------------------- | ----------------------------------------------------------- |
284284
| **Annotation management** | |
285285
| `hedpy validate bids-dataset` | Validate HED annotations in BIDS datasets |
286+
| `hedpy validate string` | Validate HED annotations in a string |
287+
| `hedpy validate sidecar` | Validate HED annotations in a JSON sidecar |
288+
| `hedpy validate tabular` | Validate HED annotations in a tabular file (TSV) |
286289
| `hedpy extract bids-sidecar` | Extract JSON sidecar template from tabular (`.tsv`) files |
287290
| **Schema management** | |
288291
| `hedpy schema validate` | Validate HED schema files |
@@ -403,6 +406,62 @@ hedpy validate bids-dataset /path/to/bids/dataset \
403406

404407
______________________________________________________________________
405408

409+
### String validation
410+
411+
Validate a HED string using `hedpy validate string`.
412+
413+
```bash
414+
# Basic validation
415+
hedpy validate string "Event, Action" -sv 8.3.0
416+
417+
# With definitions
418+
hedpy validate string "Event, Def/MyDef" \
419+
-sv 8.4.0 \
420+
-d "(Definition/MyDef, (Action, Move))"
421+
422+
# Check for warnings
423+
hedpy validate string "Event, Action/Button-press" -sv 8.4.0 -w
424+
```
425+
426+
______________________________________________________________________
427+
428+
### Sidecar validation
429+
430+
Validate a HED JSON sidecar using `hedpy validate sidecar`.
431+
432+
```bash
433+
# Basic validation
434+
hedpy validate sidecar task-rest_events.json -sv 8.3.0
435+
436+
# With multiple schemas
437+
hedpy validate sidecar task-rest_events.json -sv 8.3.0 -sv score_1.1.0
438+
439+
# Check for warnings and save to file
440+
hedpy validate sidecar task-rest_events.json -sv 8.4.0 -w -o results.txt
441+
```
442+
443+
______________________________________________________________________
444+
445+
### Tabular validation
446+
447+
Validate a HED tabular file (TSV) using `hedpy validate tabular`.
448+
449+
```bash
450+
# Basic validation
451+
hedpy validate tabular events.tsv -sv 8.3.0
452+
453+
# With a sidecar
454+
hedpy validate tabular events.tsv -s sidecar.json -sv 8.3.0
455+
456+
# Limit errors
457+
hedpy validate tabular events.tsv -sv 8.3.0 -el 5
458+
459+
# Check for warnings and output JSON
460+
hedpy validate tabular events.tsv -sv 8.3.0 -w -f json -o results.json
461+
```
462+
463+
______________________________________________________________________
464+
406465
### Sidecar template extraction
407466

408467
Extract a JSON sidecar template from BIDS event files using `hedpy extract bids-sidecar`.
@@ -534,6 +593,9 @@ For backward compatibility, you can still access scripts directly using Python m
534593
```bash
535594
# Validation
536595
python -m hed.scripts.validate_bids /path/to/dataset --check-warnings
596+
python -m hed.scripts.validate_hed_string "Event, Action" -sv 8.3.0
597+
python -m hed.scripts.validate_hed_sidecar sidecar.json -sv 8.3.0
598+
python -m hed.scripts.validate_hed_tabular events.tsv -sv 8.3.0
537599

538600
# Sidecar extraction
539601
python -m hed.scripts.hed_extract_bids_sidecar /path/to/dataset -s events

‎spec_tests/hed-specification‎

Lines changed: 0 additions & 1 deletion
This file was deleted.

‎spec_tests/hed-tests/json_test_data/schema_tests/SCHEMA_ATTRIBUTE_INVALID.json‎

Lines changed: 126 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,126 @@
1+
[
2+
{
3+
"error_code": "SCHEMA_ATTRIBUTE_INVALID",
4+
"name": "attribute-invalid-unknown",
5+
"warning": true,
6+
"description": "A schema attribute issue, saying there is an unknown one.",
7+
"schema": "",
8+
"error_category": "schema_development",
9+
"common_causes": [
10+
"Using undefined schema attributes",
11+
"Applying attributes to wrong element types",
12+
"Typos in attribute names",
13+
"Using attributes from different schema versions",
14+
"Incorrect attribute property assignments"
15+
],
16+
"explanation": "Schema attributes must be defined in the schema attributes section before use, and must be applied to the correct element types (tags, units, value classes, etc.). Each attribute has specific properties that determine where it can be used.",
17+
"correction_strategy": "Define missing attributes or fix attribute usage",
18+
"correction_examples": [
19+
{
20+
"wrong": "'''Tag-with-unknown''' {unknownAttribute}",
21+
"correct": "'''Tag-with-unknown''' {extensionAllowed}",
22+
"explanation": "Replaced undefined attribute with valid schema attribute"
23+
},
24+
{
25+
"wrong": "* mod1 {unitAttribute}[Wrong attribute type]",
26+
"correct": "* mod1 {unitModifierProperty}",
27+
"explanation": "Used correct property type for unit modifier"
28+
}
29+
],
30+
"correction_patterns": [
31+
"Define all schema attributes in the Schema attributes section",
32+
"Ensure attribute properties match element types",
33+
"Use correct property types: nodeClassProperty, unitProperty, etc.",
34+
"Check attribute names for typos",
35+
"Verify attribute compatibility with schema version"
36+
],
37+
"fix_instructions": [
38+
"1. Check if the attribute is defined in Schema attributes section",
39+
"2. Verify the attribute property type matches the element",
40+
"3. Correct spelling of attribute names",
41+
"4. Add missing attribute definitions if needed",
42+
"5. Ensure proper property assignment"
43+
],
44+
"validation_hints": [
45+
"Review schema attributes section for all used attributes",
46+
"Check property types match element usage",
47+
"Verify attribute names are spelled correctly",
48+
"Ensure attributes exist in current schema version"
49+
],
50+
"specification_reference": "A.1.4. Schema attributes",
51+
"related_errors": [
52+
"SCHEMA_ATTRIBUTE_VALUE_INVALID",
53+
"SCHEMA_SECTION_MISSING"
54+
],
55+
"definitions": [],
56+
"tests": {
57+
"schema_tests": {
58+
"fails": [
59+
[
60+
"HED version=\"1.0.0\"",
61+
"'''Prologue'''",
62+
"!# start schema",
63+
"'''Tag-with-unknown''' {unknownAttribute}",
64+
"!# end schema",
65+
"'''Unit classes'''",
66+
"'''Unit modifiers'''",
67+
"'''Value classes'''",
68+
"'''Schema attributes'''",
69+
"'''Properties'''",
70+
"'''Epilogue'''",
71+
"!# end hed"
72+
],
73+
[
74+
"HED version=\"1.0.0\"",
75+
"'''Prologue'''",
76+
"!# start schema",
77+
"'''Tag-with-unknown''' {unitAttribute}",
78+
"!# end schema",
79+
"'''Unit classes'''",
80+
"'''Unit modifiers'''",
81+
"'''Value classes'''",
82+
"'''Schema attributes''' <nowiki>{unitProperty}</nowiki>",
83+
"* unitAttribute <nowiki>{unitProperty}</nowiki>",
84+
"'''Properties''' <nowiki></nowiki>",
85+
"* unitProperty <nowiki></nowiki>",
86+
"'''Epilogue'''",
87+
"!# end hed"
88+
],
89+
[
90+
"HED version=\"1.0.0\"",
91+
"'''Prologue'''",
92+
"!# start schema",
93+
"'''Tag'''",
94+
"!# end schema",
95+
"'''Unit classes'''",
96+
"'''Unit modifiers''' <nowiki></nowiki>",
97+
"* mod1 <nowiki>{unitAttribute}[Wrong attribute type]</nowiki>",
98+
"'''Value classes'''",
99+
"'''Schema attributes''' <nowiki>{unitProperty}</nowiki>",
100+
"* unitAttribute <nowiki>{unitProperty}</nowiki>",
101+
"'''Properties''' <nowiki></nowiki>",
102+
"* unitProperty <nowiki></nowiki>",
103+
"'''Epilogue'''",
104+
"!# end hed"
105+
]
106+
],
107+
"passes": [
108+
[
109+
"HED version=\"1.0.0\" library=\"score\" withStandard=\"8.2.0\" unmerged=\"True\"",
110+
"'''Prologue'''",
111+
"!# start schema",
112+
"'''Tag-with-unknown''' {suggestedTag=Event}",
113+
"!# end schema",
114+
"'''Unit classes'''",
115+
"'''Unit modifiers'''",
116+
"'''Value classes'''",
117+
"'''Schema attributes'''",
118+
"'''Properties'''",
119+
"'''Epilogue'''",
120+
"!# end hed"
121+
]
122+
]
123+
}
124+
}
125+
}
126+
]

‎spec_tests/hed-tests/json_test_data/schema_tests/SCHEMA_ATTRIBUTE_VALUE_INVALID_ALLOWED_CHARACTER.json‎

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
[
2+
{
3+
"error_code": "SCHEMA_ATTRIBUTE_VALUE_INVALID",
4+
"name": "attribute-invalid-allowed-character",
5+
"warning": true,
6+
"description": "A schema unit has an invalid conversion factor",
7+
"schema": "",
8+
"error_category": "schema_development",
9+
"common_causes": [
10+
"Using invalid characters in allowedCharacter attribute values",
11+
"Incorrect character specification format",
12+
"Including forbidden characters in allowed character sets",
13+
"Malformed character range specifications",
14+
"Using deprecated character specification syntax"
15+
],
16+
"explanation": "The allowedCharacter attribute defines valid characters for specific schema elements. Invalid character specifications can cause parsing errors and validation failures.",
17+
"correction_strategy": "Use valid character specifications according to HED schema format",
18+
"correction_examples": [
19+
{
20+
"wrong": "allowedCharacter=\"[invalid]\"",
21+
"correct": "allowedCharacter=\"letters,digits\"",
22+
"explanation": "Replaced invalid character specification with valid format"
23+
}
24+
],
25+
"correction_patterns": [
26+
"Use standard character class names (letters, digits, etc.)",
27+
"Avoid invalid character specifications",
28+
"Follow HED character specification format"
29+
],
30+
"fix_instructions": [
31+
"1. Identify invalid allowedCharacter specifications",
32+
"2. Replace with valid character class names",
33+
"3. Verify character specification syntax",
34+
"4. Test schema validation with corrected attributes"
35+
],
36+
"validation_hints": [
37+
"Check character specification format",
38+
"Verify against HED allowed character classes",
39+
"Test schema loading after character corrections"
40+
],
41+
"specification_reference": "3.1.2.3. Schema attributes and character specifications",
42+
"related_errors": ["SCHEMA_ATTRIBUTE_INVALID", "CHARACTER_INVALID"],
43+
"definitions": [],
44+
"tests": {
45+
"schema_tests": {
46+
"fails": [
47+
[
48+
"HED version=\"1.0.0\" library=\"score\" withStandard=\"8.2.0\" unmerged=\"True\"",
49+
"'''Prologue'''",
50+
"!# start schema",
51+
"!# end schema",
52+
"'''Unit classes''' ",
53+
"'''Unit modifiers'''",
54+
"'''Value classes'''",
55+
"* testValueClass {allowedCharacter=?d}",
56+
"'''Schema attributes'''",
57+
"'''Properties'''",
58+
"'''Epilogue'''",
59+
"!# end hed"
60+
]
61+
],
62+
"passes": [
63+
[
64+
"HED version=\"1.0.0\" library=\"score\" withStandard=\"8.2.0\" unmerged=\"True\"",
65+
"'''Prologue'''",
66+
"!# start schema",
67+
"!# end schema",
68+
"'''Unit classes''' ",
69+
"'''Unit modifiers'''",
70+
"'''Value classes'''",
71+
"* testValueClass {allowedCharacter=?, allowedCharacter=letters}",
72+
"'''Schema attributes'''",
73+
"'''Properties'''",
74+
"'''Epilogue'''",
75+
"!# end hed"
76+
],
77+
[
78+
"HED version=\"1.0.0\" library=\"score\" withStandard=\"8.2.0\" unmerged=\"True\"",
79+
"'''Prologue'''",
80+
"!# start schema",
81+
"!# end schema",
82+
"'''Unit classes''' ",
83+
"'''Unit modifiers'''",
84+
"'''Value classes'''",
85+
"* testValueClass {allowedCharacter=letters}",
86+
"'''Schema attributes'''",
87+
"'''Properties'''",
88+
"'''Epilogue'''",
89+
"!# end hed"
90+
]
91+
]
92+
}
93+
}
94+
}
95+
]

0 commit comments

Comments
 (0)