Table of Contents

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:

  1. FILE_NAME- Target a file or files using full name or wildcard patterns
  2. QUERY- Select based on logical tag conditions (e.g., 'TAG1' & 'NOT(TAG2)')
  3. 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:

/QUERY=: Lets you use logic expressions to select based on file-level tags

SymbolMeaning (Syntax)Example
+OR'TAG1' + 'TAG2'
|OR (Alternative)'TAG1' | 'TAG2'
&AND'TAG1' & 'TAG2'
NOTNegation'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. 

Select_Active_File
! /FILE_NAME=
! /QUERY=
! /SUBJECT_TAGS=NO_SUBJECT

Command Parameters

The following table shows the command parameters and descriptions.

ParameterDescription
! /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:

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. 

Select_Active_File
/FILE_NAME=GLOBAL
! /QUERY=
! /SUBJECT_TAGS=NO_SUBJECT
;

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: 

Select_Active_File
/FILE_NAME=ALL_FILES
/QUERY=WALK + RUN
! /SUBJECT_TAGS=NO_SUBJECT
;

Or equivalently: 

Select_Active_File
/FILE_NAME=ALL_FILES
/QUERY=WALK | RUN
! /SUBJECT_TAGS=NO_SUBJECT
;

Example 3: Select trials with one tag AND NOT another

Suppose you want to select all running trials that are not tagged as “Fatigue”: 

Select_Active_File
/FILE_NAME=ALL_FILES
/QUERY=RUN & NOT(FATIGUE)
! /SUBJECT_TAGS=NO_SUBJECT
;

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: 

Select_Active_File
/FILE_NAME=ALL_FILES
! /QUERY=
/SUBJECT_TAGS=ELITE & NOT(INJURED)
;

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. 

! 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=

Notes

Back to Pipeline Commands Reference