Differences

This shows you the differences between two versions of the page.

--- visual3d:documentation:pipeline:file_commands:select_active_file [2024/07/17 15:42] – removed sgranger
+++ visual3d:documentation:pipeline:file_commands:select_active_file [2025/07/22 15:05] (current) – wikisysop
@@ Line 1: / Line 1: @@
+====== Select Active File ======
+===== Overview =====
+The **Select_Active_File** command is used to define which file(s) are active in the Visual3D workspace. This is important because most pipeline commands operate only on the currently active file(s). If multiple files are open or batch processing is used, this command gives you precise control over which trial a command affects.
+You can select files using three different mechanisms:
+  - FILE_NAME- Target a file or files using full name or wildcard patterns
+  - QUERY- Select based on logical tag conditions (e.g., 'TAG1' & 'NOT(TAG2)')
+  - SUBJECT_TAGS- Select based on subject-level tags (metadata applied to trials)
+==== Understanding the File Selection Methods ====
+**/FILE_NAME=**: Lets you specify the actual filename or use wildcards:
+  * "Trial01.c3d" - selects only one file exactly.
+  * "*.c3d" - wildcard, selects all C3D files
+**/QUERY=**: Lets you use logic expressions to select based on file-level tags
+  * If you have tagged trials like "Walk" and "Run", you can use the following syntax in order to manipulate which files are selected as active.
+  * '/QUERY= Walk + Run'- select all walking or running files.
+  * '/QUERY= Run + NOT(Fatigue) - only running files that are not tagged fatigued
+|Symbol|Meaning (Syntax)|Example|
+|**+**|OR|'TAG1' + 'TAG2'|
+|**|**|OR (Alternative)|'TAG1' **|** 'TAG2'|
+|**&**|AND|'TAG1' &  'TAG2'|
+|**NOT**|Negation|'TAG1' & NOT('TAG2')|
+**'/SUBJECT_TAGS='**- similar to /QUERY, but works at the subject level. Use this if you've applied subject-wide tags like 'ELITE' or 'CONTROL'
+===== Pipeline Command =====
+The command below is as seen on the Visual3D application, the parameters within act as options to manipulate the command.
+<code>
+Select_Active_File
+! /FILE_NAME=
+! /QUERY=
+! /SUBJECT_TAGS=NO_SUBJECT
+</code>
+===== Command Parameters =====
+The following table shows the command parameters and descriptions.
+|**Parameter**|**Description**|
+|**! /FILE_NAME=**|Specifies the file(s) to activate using exact name or wildcard.|
+|**! /QUERY=**|Selects files by tag logic.|
+|**! /SUBJECT_TAGS=**|Filters files by subject-level tags. Defaults to NO_SUBJECT|
+===== Dialog =====
+There is no dedicated dialog box for this command. The GUI equivalent is manually selecting the active file using the file selector dropdown in the toolbar:
+{{:visual3d:documentation:pipeline:file_commands:activefile_ui_dropdown.png?900|}}
+This command is primarily used in pipeline scripts and batch processing workflows to automate file selection.
+===== Examples =====
+The following examples will go through the use of the Select_Active_File command in the Visual3D application.
+=== Example 1: Select the Global Workspace ===
+Use this when working with signals that were computed across multiple trials. These signals are not associated with a specific file, and so they live in the Global Workspace.
+<code>
+Select_Active_File
+/FILE_NAME=GLOBAL
+! /QUERY=
+! /SUBJECT_TAGS=NO_SUBJECT
+;
+</code>
+=== Example 2: Select trials based on tags (OR condition) ===
+Say that you've tagged trials using WALK and RUN and you want to activate all trials that are either walking OR running:
+<code>
+Select_Active_File
+/FILE_NAME=ALL_FILES
+/QUERY=WALK + RUN
+! /SUBJECT_TAGS=NO_SUBJECT
+;
+</code>
+Or equivalently:
+<code>
+Select_Active_File
+/FILE_NAME=ALL_FILES
+/QUERY=WALK | RUN
+! /SUBJECT_TAGS=NO_SUBJECT
+;
+</code>
+=== Example 3: Select trials with one tag AND NOT another ===
+Suppose you want to select all running trials that are not tagged as "Fatigue":
+<code>
+Select_Active_File
+/FILE_NAME=ALL_FILES
+/QUERY=RUN & NOT(FATIGUE)
+! /SUBJECT_TAGS=NO_SUBJECT
+;
+</code>
+=== Example 4: Select trials based on subject-level tags ===
+Assuming you've tagged subjects as 'ELITE', and some are also tagged 'INJURED'. You can activate only the non-injured elite subjects:
+<code>
+Select_Active_File
+/FILE_NAME=ALL_FILES
+! /QUERY=
+/SUBJECT_TAGS=ELITE & NOT(INJURED)
+;
+</code>
+=== Example 5: Exclude specific filename patterns using tagging ===
+If you want to exclude trials with "run" in the name, you must first tag the files that should be kept, since wildcards cannot do negative matching directly.
+<code>
+! Tag only the files NOT containing "run"
+! Assign tag RUN to files with "run" in the pathname
+Assign_Tags_To_Files
+/MOTION_FILE_NAMES=*run*.c3d
+! /QUERY=
+/TAGS=RUN
+;
+! Assign tag NOT_RUN to files that are not tagged RUN
+Assign_Tags_To_Files
+/MOTION_FILE_NAMES=ALL_FILES
+/QUERY=NOT(RUN)
+/TAGS=NOT_RUN
+;
+! Select NOT_RUN as the active files
+Select_Active_File
+/FILE_NAME=NOT_RUN
+! /QUERY=
+</code>
+===== Notes =====
+  * Use this command any time your pipeline depends on file-specific operations in a multi-file workspace.
+  * Tags are assigned using the Assign_Tags_To_Files command and must be added before using '/QUERY='
+  * Use '/SUBJECT_TAGS=' only if your workspace includes subject-level metadata
+  * To select files by exclusion (e.g. "everything except..."), you must use tagging- direct wildcard exclusion is not supported.
+----
+[[Visual3D:Documentation:Pipeline:General_Information:Pipeline_Commands_Reference|Back to Pipeline Commands Reference]]