From 9b1642e67fb15859c33587992f44f0f22b325f4d Mon Sep 17 00:00:00 2001 From: IanCa Date: Thu, 21 Sep 2023 10:47:24 -0500 Subject: [PATCH] Update search guide with {X:Y} notation, remove [[]] notation --- docs/source/HedSearchGuide.md | 51 ++++++++++++++++++++--------------- 1 file changed, 29 insertions(+), 22 deletions(-) diff --git a/docs/source/HedSearchGuide.md b/docs/source/HedSearchGuide.md index d6d17e1..ec80019 100644 --- a/docs/source/HedSearchGuide.md +++ b/docs/source/HedSearchGuide.md @@ -138,13 +138,13 @@ comma-separated tags and parenthesized groups. The expressions for `A` and `B` are each evaluated and then combined using standard logic. -| Query form | Example query | Matches | Does not match | -|-----------------------------------------------------------------------------------------------------------------------|-----------------------------|----------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------| -| **`A`, `B`**
Match if both `A` and `B`
are matched. | *Event*, *Sensory-event* | *Event*, *Sensory-event*
*Sensory-event*, *Event*
(*Event*, *Sensory-event*) | *Event* | +| Query form | Example query | Matches | Does not match | +|--------------------------------------------------------------------------------------------------|-----------------------------|----------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------| +| **`A`, `B`**
Match if both `A` and `B`
are matched. | *Event*, *Sensory-event* | *Event*, *Sensory-event*
*Sensory-event*, *Event*
(*Event*, *Sensory-event*) | *Event* | | **`A` and `B`**
Match if both `A` and `B`
are matched.
Same as the comma notation. | *Event* and *Sensory-event* | *Event*, *Sensory-event*
*Sensory-event*, *Event*
(*Event*, *Sensory-event*) | | *Event* | -| **`A` or `B`**
Match if either `A` or `B`. | *Event* or *Sensory-event* | *Event*, *Sensory-event*
*Sensory-event*, *Event*
(*Event*, *Sensory-event*)
*Event*
*Sensory-event* | *Agent-trait* | -| **~`A`**
Match groups that do
not contain `A`
`A` can be an arbitrary expression. | [[ *Event*, ~*Action* ]] | (*Event*)
(*Event*, *Animal-agent*)
(*Sensory-event*, (*Action*)) | *Event*
*Event*, *Action*
(*Event*, *Action*)
| -| **@`A`**
Match a line that
does not contain `A`. | @*Event* | *Action*
*Agent-trait*
*Action, Agent-Trait*
(*Action*, *Agent*) | *Event*
(*Action*, *Event*)
(*Action*, *Sensory-event*)
(*Agent*, (*Sensory-event*, *Blue*)) | +| **`A` or `B`**
Match if either `A` or `B`. | *Event* or *Sensory-event* | *Event*, *Sensory-event*
*Sensory-event*, *Event*
(*Event*, *Sensory-event*)
*Event*
*Sensory-event* | *Agent-trait* | +| **~`A`**
Match groups that do
not contain `A`
`A` can be an arbitrary expression. | { *Event*, ~*Action* } | (*Event*)
(*Event*, *Animal-agent*)
(*Sensory-event*, (*Action*)) | *Event*
*Event*, *Action*
(*Event*, *Action*)
| +| **@`A`**
Match a line that
does not contain `A`. | @*Event* | *Action*
*Agent-trait*
*Action, Agent-Trait*
(*Action*, *Agent*) | *Event*
(*Action*, *Event*)
(*Action*, *Sensory-event*)
(*Agent*, (*Sensory-event*, *Blue*)) | ### Group queries @@ -164,31 +164,38 @@ Annotators must group tags using parentheses to make the meaning clear: Indicates a red square and a blue triangle. Group queries allow analysts to detect these groupings. -As with logical queries, +As with logical queries, `A` and `B` represent HED expressions that may contain multiple comma-separated tags and parenthesized groups. -| Query form | Example query | Matches | Does not match | -|--------------------------------------------------------------------------------------------------------------------------|-----------------|-------------------------------------------------------------|------------------------| -| **[[`A`, `B`]]**
Match a group that
contains both `A` and `B`
at the same level
in the same group. | *[[Red, Blue]]* | *(Red, Blue)*
*(Red, Blue, Green)* | *(Red, (Blue, Green))* | -| **[`A`, `B`]**
Match a group that
contains `A` and `B`.
Both `A` and `B` could
be any subgroup level. | *[Red, Blue]* | *(Red, (Blue, Green))*
*((Red, Yellow), (Blue, Green))* | *Red, (Blue, Green)* | - +| Query form | Example query | Matches | Does not match | +|--------------------------------------------------------------------------------------------------------------------------|---------------|-------------------------------------------------------------|---------------------------------------------------------------| +| **{`A`, `B`}**
Match a group that
contains both `A` and `B`
at the same level
in the same group. | *{Red, Blue}* | *(Red, Blue)*
*(Red, Blue, Green)* | *(Red, (Blue, Green))* | +| **[`A`, `B`]**
Match a group that
contains `A` and `B`.
Both `A` and `B` could
be any subgroup level. | *[Red, Blue]* | *(Red, (Blue, Green))*
*((Red, Yellow), (Blue, Green))* | *Red, (Blue, Green)* | +| **{`A`, `B:`}**
Match a group that
contains both `A` and `B`
at the same level
and no other contents. | *{Red, Blue:}* | *(Red, Blue)* | *(Red, Blue, Green)*
*(Red, Blue, (Green))* | +| **{`A`, `B: C`}**
Match a group that
contains both `A` and `B`
at the same level
and optionally `C`. | *{Red, Blue: Green}* | *(Red, Blue)*
*(Red, Blue, Green)* | *(Red, (Blue, Green))*
*(Red, Blue, (Green))*| -These operations can be -arbitrarily nested and combined, as for example in the query: +These operations can be arbitrarily nested and combined, as for example in the query: -> *[`A` or [[`B` and `C`]] ]* +> *[`A` or {`B` and `C`} ]* In this query -Ordering on either the search terms or strings to be searched doesn't matter unless it will impact -precedence on the expression. Use logical grouping with parentheses to assure -the expected order. +Ordering on either the search terms or strings to be searched doesn't matter, +precedence is generally left to right outside of grouping operations. -Precedence is purely left to right outside of grouping operations. -Thus, unlike many traditional programming languages, -**and** does not take precedence over **or**. -This may change in the future. +Wildcard matching is supported, but primarily makes sense in exact matching groups. +You can replace any term with a wildcard: +| Query form | Example query | Matches | Does not match | +|--------------------------------------|-----------------|-----------------------|-------------------------------| +| **`?`**
Matches any tag or group | {`A` and `?`} | *(A, B}
(A, (B))* | *(A)
(B, C)* | +| **`??`**
Matches any tag | {`A` and `??`} | *(A, B}* | *(A)
(B, C)
(A, (B))* | +| **`???`**
Matches any group | {`A` and `???`} | *(A, (B))* | *(A)
(B, C)
(A, B)* | + + +**Notes**: You cannot use negation inside exact matching groups "{X:}" or "{X:Y}" notation.
+You cannot use negation in combination with wildcards ( ?, ??, or ??? )
+In exact group matching, or matches one or the other, not both. eg. {A or B:} matches (A) or (B), but not (A, B) ## Where can HED search be used?