Differences

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

--- visual3d:documentation:pipeline:file_commands:select_active_file [2024/07/17 15:45] – created sgranger
+++ visual3d:documentation:pipeline:file_commands:select_active_file [2025/07/22 15:05] (current) – wikisysop
@@ Line 1: / Line 1: @@
 ====== Select Active File ======
-Many of the pipeline commands in Visual3D act on the active files only. Using this command the user can determine what files are active and therefore will be processed.
+===== 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.
-{{:Tutorial4_5.jpg}}
+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)
-==== Pipeline Command ====
-The pipeline command below is used to select the [[Visual3D:Documentation:Definitions:Active_Files|Active_Files]]
+==== Understanding the File Selection Methods ====
-<code>
+**/FILE_NAME=**: Lets you specify the actual filename or use wildcards:
-Select_Active_File
+  * "Trial01.c3d" - selects only one file exactly.
-! /FILE_NAME=
+  * "*.c3d" - wildcard, selects all C3D files
-! /QUERY=
-! /SUBJECT_TAGS=NO_SUBJECT
-;
-</code>
-=== File_Name ===
+**/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
-The parameter **/File_Name=** can be a single file, a TAG referring to all files with that TAG, or the keyword ALL_FILES, which makes all of the files in the Visual3D Workspace active.
+|Symbol|Meaning (Syntax)|Example|
+|**+**|OR|'TAG1' + 'TAG2'|
+|**|**|OR (Alternative)|'TAG1' **|** 'TAG2'|
+|**&**|AND|'TAG1' &  'TAG2'|
+|**NOT**|Negation|'TAG1' & NOT('TAG2')|
-**Note:** Visual3D defines files by their full pathname. For example, the following command will not be recognized
+**'/SUBJECT_TAGS='**- similar to /QUERY, but works at the subject level. Use this if you've applied subject-wide tags like 'ELITE' or 'CONTROL'
-<code>
+===== Pipeline Command =====
-Select_Active_File
-/FILE_NAME= file1.c3d
-;
-</code>
-To fix the example above, you define the full pathname:
+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= c:\data\session1\file1.c3d
+! /FILE_NAME=
-;
+! /QUERY=
+! /SUBJECT_TAGS=NO_SUBJECT
 </code>
-or you can use a wildcard:
+===== Command Parameters =====
-<code>
+The following table shows the command parameters and descriptions.
-Select_Active_File
-/FILE_NAME= *file1.c3d
-;
-</code>
-or you can specify a TAG:
+|**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|
-<code>
+===== Dialog =====
-Select_Active_File
-/FILE_NAME= TAG1
-;
-</code>
-=== Query ===
+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:
-The Query option (**Visual3D Professional Only**) allows you to select a subset of the files referred by to FILE_NAME. You can query using [[Visual3D:Documentation:Pipeline:Expressions:Expressions_Overview|expressions]]:
+{{:visual3d:documentation:pipeline:file_commands:activefile_ui_dropdown.png?900|}}
-/QUERY=METRIC::PROCESSED::MASS > 75
+This command is primarily used in pipeline scripts and batch processing workflows to automate file selection.
-=== Subject_Tags ===
+===== Examples =====
-Set the active subject tag - FOR MULTISUBJECT ONLY!
+The following examples will go through the use of the Select_Active_File command in the Visual3D application.
-==== Example 1: Global_Workspace ====
+=== Example 1: Select the Global Workspace ===
-This example shows how to make the [[Visual3D:Documentation:Definitions:Global_Workspace|Global Workspace]] active
+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>
@@ Line 71: / Line 69: @@
 /FILE_NAME=GLOBAL
 ! /QUERY=
+! /SUBJECT_TAGS=NO_SUBJECT
 ;
 </code>
-==== Example 2 - ALL_FILES and OR Query ====
+=== Example 2: Select trials based on tags (OR condition) ===
-From ALL_FILES select files that are tagged TAG1 or TAG2. Note there are multiple syntaxes for the "or". Two are shown below:
+Say that you've tagged trials using WALK and RUN and you want to activate all trials that are either walking OR running:
-Using the "+" as the "OR" operator
+<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=TAG1 + TAG2
+/QUERY=WALK | RUN
+! /SUBJECT_TAGS=NO_SUBJECT
 ;
 </code>
-Using "|" as the "OR" operator
+=== 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=TAG1 | TAG2
+/QUERY=RUN & NOT(FATIGUE)
+! /SUBJECT_TAGS=NO_SUBJECT
 ;
 </code>
-==== Example 3 - ALL_FILES AND and NOT Query ====
+=== Example 4: Select trials based on subject-level tags ===
-From ALL_FILES select files that are TAG1 AND NOT TAG2 using the operators "&" and "NOT"
+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=TAG1 & NOT(TAG2)
+! /QUERY=
+/SUBJECT_TAGS=ELITE & NOT(INJURED)
 ;
 </code>
-==== Example 4 - ALL_FILES and a wildcard ====
-From ALL_FILES select files that do not contain the wildcard *run*.c3d
+=== Example 5: Exclude specific filename patterns using tagging ===
-This cannot be done in one step. Command will be used to tag the files prior to using the Select_Active command.
+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
@@ Line 132: / Line 143: @@
 /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]]