Inspect3D Advanced Query Section: Difference between revisions

From Software Product Documentation
Jump to navigation Jump to search
(Updated all references to Group/Sub-Group to Query/Condition.)
 
(19 intermediate revisions by 3 users not shown)
Line 6: Line 6:




=Introduction=
The Query Builder dialog is used to define the queries that will extract signals from the loaded CMZ library. The dialog also allows you to group specific signals together based on a number of possible features, e.g. right/left or intact/affected.


The group definition dialog is used to define which signals you want to query from the CMZ library and allows you to group data together (ex. right and left side, intact/affected).
[[Image:querybuilder.png|700 px]]


[[Image:FullAdvancedQueriesDialogue3.png]]
==Auto-Populate Queries==


=Sections=
Inspect3D has the convenient ability to automatically define queries based on common signals and groupings. This feature saves the user from the tedious task of manually defining common queries. More information about Auto-Populating Groups can be found [[Inspect3D:_AutoPopulate_Groups|here]].


==Group Definition File==
==Query Definition File==


[[Image:I3DAdvancedQueriesDialogueLoadSave.png]]
[[Image:I3DAdvancedQueriesDialogueLoadSave.png]]


You can save group definitions (.q3d) so they can be loaded again (for use on the same or a different CMZ library). You can save one group definition at a time to a file, or all files.
Inspect3D also allows users to save time by saving queries definitions to a [[Q3D Query File|.q3d file]] so that they can be easily re-used during future analysis. This capability is at its most useful when using the Load Group Def & Compute Groups option in the Group Definitions drop-down menu.


==Groups and Sub Groups==
==Queries and Conditions==


[[Image:I3DAdvancedQueriesDialogueQueryName2.png|left]]
{| style= width="100%"
| style="width: 50%" align="left" style="vertical-align:top"|
You can define Groups and Sub-Groups for the signals in the CMZ library.
* An example <b>Group</b> is "AnkleMoment_X"
* Example <b>Sub-Groups</b> for "AnkleMoment_X" are "LAnkleMoment_X" and "RAnkleMoment_X"
* A group can have as many Sub-Groups as necessary (1-N)


You can define Groups and Sub-Groups. A <b>Group</b> would be "AnkleMoment_X" while a <b>Sub-Group</b> would be "LAnkleMoment_X" and "RAnkleMoment_X".
Names for Queries and Conditions can include spaces and special characters. Note, however, that some special characters can cause difficulty for updating CMZ libraries with exclusions. Condition names can be repeated between different queries but not within a single query.
| style= "width: 50%" align="right" style="vertical-align:top"|
[[Image:I3DAdvancedQueriesDialogueQueryName2.png|right]]
|}


Note: Groups and Sub-Groups can use spaces and special characters - if you plan to update the CMZ files with exclusions, be cautious using special characters. Sub-Group names can be repeated in different groups (but not within the same group).
==Condition Definition==


==Conditions==
The Condition Definition lets you define the signals you want to query. Query results are defined according to the signals you want from the CMZ library, the events or event sequences to which you want to time normalize the signals, and any further refinements that you want to apply, e.g., threshold values.


<table>
===Signals===
<tr>
{| style= width="100%"
<td>
| style="width: 50%" align="left" style="vertical-align:top"|
 
[[File:I3D_GroupDef_Signals.png|350px]]
[[Image:I3DAdvancedQueriesDialogueConditions3.png]]
| style= "width: 50%" align="left" style="vertical-align:top"|
 
This tab allows the user to select a signal according to how it is specified in the [[Data_Tree_Summary|Visual3D Data Tree]]. This specification includes four components with an additional option to negate the results.
</td>
* Type
<td>
* Folder
 
* Name
<big>
* Component
[[Image:I3DAdvancedQueriesDialogueModifyConditionName.png]]
* Negate Results
 
|}
'''Modify Name''' - Allows you to change the name of an existing query without creating a new query from scratch. This section of the Advanced Queries Dialogue is found to the top right.
 
'''Load Query''' - Allows you to load a query that has previously been created and saved.
 
'''Save Query''' - Allows you to save a query that you have created and use it again at a later date.
 
'''Save all to one file''' - Allows you to combine multiple queries into a single file that can be used again at a later date.
 
'''Conditions''' - Displays a list of the conditions that have been created using the Events, Signals, and Refinement tab. The conditions are a powerful tool which allows users to combine different conditions into a single query. Example 1: a query could be created call KneeAngle that has a condition for both the left knee angle and the right knee angle. Example 2: in a population where some of participants have a left knee replacements and some have right knee replacements a query called AffectedLeg can be created. It will contain a condition that includes all of the participants who have had their left knee replaced and a condition that includes all the participants who have had their right knee replaced.
 
'''Add''' - Allows you to begin building a new condition.
 
'''Modify''' - Allows you to change the parameters of a previously created condition.  
 
'''Remove''' - Allows you to remove one of the listed conditions from the query.  
</big>
 
</td>
</tr>
</table>
 
==Events==
 
<big>
Condition for each query must be started with the name of the condition and the name must include either Right or Left in it.
</big>


===Events===
===Events===
 
{| style= width="100%"
<table>
| style="width: 50%" align="left" style="vertical-align:top"|
<tr>
[[File:I3D_GroupDef_Events.png|350px]]
<td>
| style= "width: 50%" align="left" style="vertical-align:top"|
 
This tab allows user to specify the events to which the data will be normalized, which event sequences should be excluded, and how the data should be normalized.
[[Image:I3DAdvancedQueriesDialogueEvents.png]]
* <b>Event Sequence:</b> Events to normalize data to
 
** Typically Kinematic Signals are normalized from R/LHS to R/LHS
</td>
** Typically Kinetic Signals are normalized from R/LON to R/LHS
<td>
* <b>Exclude Events:</b>
 
** Event sequences that data should not be included
<big>
* <b>Number of Points:</b> Typically a gait cycle is normalized to 101 data points
The Events will make Inspect3D select all the information in between two or more events.
* <b>Spline Type:</b> Cubic or Linear - you should use a cubic spline to normalize the data
 
|}
'''All Events''' - These list all the events available in the CMO files that you have loaded.
 
'''Event Sequence''' - This lists the starting and ending events from which Inspect3D will take information. In the example to the left the event sequence will start with a right heel strike and end on the next left heel strike.
 
'''Exclude Events''' - Events that are added to this list will cause any event sequences that contain the event to be excluded.
 
'''Arrows''' - The arrows allow you to add or remove events from the Event Sequence list. Events can also be transferred between lists by double clicking on them.  
 
'''Up & Down''' - The Up and Down buttons allow you to reorder the events that you have moved to the Event Sequence list.
</big>
 
</td>
</tr>
</table>
 
===Signals===
 
<table>
<tr>
<td>
 
[[Image:I3DAdvancedQueriesDialogueSignals.png]]
 
</td>
<td>
 
<big>
The Signals tab tells Inspect3D which type of data to use for the query.
 
'''Type''' - The type of data available for querying depends on which types of data you have saved in your CMO file. They may include: analog, COFP, force, free moment, landmark, metric, tag, and target.
 
'''Folder''' - This allows you to specify which folder you want to retrieve your data type from, the common options are original and processed.
 
'''Component''' - Certain types of data will have multiple components that you can select from. For example target data often has three components which are the x, y, and z coordinates.
 
'''All Signals''' - This presents a list of all the signals that are available to be used, based on the type of data that you have selected above.
</big>
 
</td>
</tr>
</table>


===Refinement===
===Refinement===
 
{| style= width="100%"
<table>
| style="width: 50%" align="left" style="vertical-align:top"|
<tr>
[[File:I3D_GroupDef_Refinement.png|350px]]
<td>
| style= "width: 50%" align="left" style="vertical-align:top"|
 
This tab permits signal selection to be refined according to additional conditions that must be met. There are two broad types of refinements:
[[Image:I3DAdvancedQueriesDialogueRefinement3.png]]
* <b>Refine using tag:</b> Any tags that exist in the workspace can be selected
 
** <b>Use AND Logic:</b> Determines how to treat refinements based on more than one tag. If checked, then the query will only include trials that contain ALL of the selected tags. If unchecked then the query will include trials that contain ANY of the selected tags.
<br>
|}
<br>
<br>
<br>
<br>
<br>
 
{| style= width="100%"
[[Image:I3DRefinementDialogue.png]]
| style="width: 50%" align="left" style="vertical-align:top"|
 
* <b>Refine using signal:</b> These refinements allow users to specify additional criteria that must be met before a signal in brought into the group you define. These criteria are defined using the following information:
</td>
** <b>Refinement Name:</b> Each refinement in a sub-group requires a unique name
<td>
** <b>Signal Definition:</b> Specify the signal you want to work with as it is referenced in the [[Data_Tree_Summary|Visual3D Data Tree]], i.e., Type, Folder, Name, and Component.
 
** <b>Value Must Be:</b> There are 6 types of criteria that can be specified for a refinement.
<big>
*** <b>Less Than</b>: The signal must be less than the specified threshold to be included
The Refinement tab tells Inspect3D to only include data that meets certain criteria.
*** <b>Greater Than</b>: The signal must be greater than the specified threshold to be included
 
*** <b>Equal To</b>: The signal must be equal to the specified threshold to be included
'''Refine Using Signal''' - The signal controls will only become active when the Refine Using Signal checkbox is selected.  
*** <b>Not Equal To</b>: The signal must not be equal to the specified threshold to be included
 
*** <b>Between</b>: The signal must be between the two specified values to be included
'''Add'' - Clicking on the add button will add another refinement to the list and open the Refinement Dialogue. Once a refinement is added to the list there will be a red negative button that allows you to delete the refinement and an edit button which will reopen the Refinement Dialogue and allow the refinement to be altered.  
*** <b>Manual</b>: The signal must satisfy the specified [[Expressions|Visual3D Expression]]
 
| style= "width: 50%" align="left" style="vertical-align:top"|
'''Name Text Box''' - The text box allows the refinement to be named so that multiple refinements can be sorted through.  
[[File:I3D_GroupDef_RefinementDialog.png|250px]]
 
|}
'''Type''' - The types of signals that can be used to refine the query are often: LINK_MODEL_BASED, TARGET, ANALOG, FORCE, COFP, FREEMOMENT, LANDMARK, and METRIC.  
 
'''Folder''' - Allows you to specify which folder signal should be taken from. Often the options are ORIGINAL and PROCESSED.
 
'''Name''' - Allows you to select the name of the signal that should be used.  
 
'''Component''' - Allows you to select the component of the signal for signals such as targets that can have x, y and z components.
 
'''Value Must Be''' - Controls the field below it and allows you to specify that included metrics must be either: less than, greater than, equal to, not equal to, or between.
 
'''Refine using tag''' - The tag section will only become active and used in the if the Refine using tag checkbox is selected.
 
'''Use AND Logic''' - If the Use AND Logic checkbox is selected then .c3d files will only be used in the refinement if both tags are applied to the file. Otherwise the refinement will include all of the .c3d files that have the tags selected.
 
'''Tags (multi select)''' - The tags field lists all the Tags that are in the .c3d files that have been loaded and are available for refinement. Selecting Tags mean that they will be included in the query.
 
'''Cancel''' - Removes the data entered into the field without saving or acting on it.
 
'''Save''' - Adds the conditions to the overall query.
</big>
 
</td>
</tr>
</table>
 
==Controls==
 
[[Image:I3DAdvancedQueriesDialogueClose.png]]
 
<big>
The Close button will shut down the Advanced Query dialogue box and return you to Inspect3D's main window.
 
[[Image:I3DAdvancedQueriesDialoguePerformQuery.png]]
 
The Perform Query Button will run the query that you have specified so that it will be available in the Query Data tab.
</big>


[[Category:Inspect3D]]
[[Category:Inspect3D]]

Latest revision as of 17:12, 19 October 2023

Language:  English  • français • italiano • português • español 


The Query Builder dialog is used to define the queries that will extract signals from the loaded CMZ library. The dialog also allows you to group specific signals together based on a number of possible features, e.g. right/left or intact/affected.

Auto-Populate Queries

Inspect3D has the convenient ability to automatically define queries based on common signals and groupings. This feature saves the user from the tedious task of manually defining common queries. More information about Auto-Populating Groups can be found here.

Query Definition File

Inspect3D also allows users to save time by saving queries definitions to a .q3d file so that they can be easily re-used during future analysis. This capability is at its most useful when using the Load Group Def & Compute Groups option in the Group Definitions drop-down menu.

Queries and Conditions

You can define Groups and Sub-Groups for the signals in the CMZ library.

  • An example Group is "AnkleMoment_X"
  • Example Sub-Groups for "AnkleMoment_X" are "LAnkleMoment_X" and "RAnkleMoment_X"
  • A group can have as many Sub-Groups as necessary (1-N)

Names for Queries and Conditions can include spaces and special characters. Note, however, that some special characters can cause difficulty for updating CMZ libraries with exclusions. Condition names can be repeated between different queries but not within a single query.

Condition Definition

The Condition Definition lets you define the signals you want to query. Query results are defined according to the signals you want from the CMZ library, the events or event sequences to which you want to time normalize the signals, and any further refinements that you want to apply, e.g., threshold values.

Signals

This tab allows the user to select a signal according to how it is specified in the Visual3D Data Tree. This specification includes four components with an additional option to negate the results.

  • Type
  • Folder
  • Name
  • Component
  • Negate Results

Events

This tab allows user to specify the events to which the data will be normalized, which event sequences should be excluded, and how the data should be normalized.

  • Event Sequence: Events to normalize data to
    • Typically Kinematic Signals are normalized from R/LHS to R/LHS
    • Typically Kinetic Signals are normalized from R/LON to R/LHS
  • Exclude Events:
    • Event sequences that data should not be included
  • Number of Points: Typically a gait cycle is normalized to 101 data points
  • Spline Type: Cubic or Linear - you should use a cubic spline to normalize the data

Refinement

This tab permits signal selection to be refined according to additional conditions that must be met. There are two broad types of refinements:

  • Refine using tag: Any tags that exist in the workspace can be selected
    • Use AND Logic: Determines how to treat refinements based on more than one tag. If checked, then the query will only include trials that contain ALL of the selected tags. If unchecked then the query will include trials that contain ANY of the selected tags.



  • Refine using signal: These refinements allow users to specify additional criteria that must be met before a signal in brought into the group you define. These criteria are defined using the following information:
    • Refinement Name: Each refinement in a sub-group requires a unique name
    • Signal Definition: Specify the signal you want to work with as it is referenced in the Visual3D Data Tree, i.e., Type, Folder, Name, and Component.
    • Value Must Be: There are 6 types of criteria that can be specified for a refinement.
      • Less Than: The signal must be less than the specified threshold to be included
      • Greater Than: The signal must be greater than the specified threshold to be included
      • Equal To: The signal must be equal to the specified threshold to be included
      • Not Equal To: The signal must not be equal to the specified threshold to be included
      • Between: The signal must be between the two specified values to be included
      • Manual: The signal must satisfy the specified Visual3D Expression

Retrieved from ""