Customizing Export Formatting

Overview

Mobility Lab offers a number of different export formats. Additionally, it provides a number of options for customizing the formatting of these exports. These customizations are numerous, however, and not commonly needed. Because of this, a user interface for specifying these customizations has not been given a high priority. Instead, exporting can be customized by creating an override file named "ExportOptions.json" and placing this file in your workspace directory.

Descriptions of the customization options

Behavioral options
"interactive" : whether to display confirmation dialogs while performing the export
"compressData" : whether to compress the export into a single zip file
"exportParentFolder" : the folder that the exported folder will be saved to

What is to be exported
"includeRecordingData" : whether to include the H5 recordings
"includeMetadataXml" : whether to include the metadata in XML format
"includeMetadataJson" : whether to include the metadata in JSON format
"includeAuditLogJson" : whether to include the audit log in JSON format
"includeAuditLogCsv" : whether to include the audit log in CSV format
"includeCompactMetricsCsv" : whether to include the metrics in compact CSV format
"includeVerboseMetricsCsv" : whether to include the metrics in verbose CSV format
"includeMetricsInMetadata" : whether to include metric values in the XML metadata file
"includeDataTransferSpecification" : whether to include the DTS documentation
"includeCompactDataTransfer" : whether to include the compact data transfer format
"includeVerboseDataTransfer" : whether to include the verbose data transfer format
"includeAsymmetryMetrics" : whether to include asymmetry metrics (CSV metric output only)
"includeInvisibleTrials" : whether to include trials that were skipped or deleted but maintained for informational purposes (e.g., to track why a trial was skipped)

Date formatting options
"nowDateFormat" : how to format dates corresponding to "now"
"trialDateFormat" : how to format dates corresponding to trial times"
"filenameDateFormat" : how to format dates when naming files"
"nowDateFormatUTC" : whether to export now dates in UTC (if not the local timezone)
"trialDateFormatUTC" : whether to export trial dates in UTC (if not the trial's timezone)
"filenameDateFormatUTC" : whether to export filename dates in UTC

Folder name formatting options
"exportFolderNameFormat" : the format of the folder name for the export
"recordingDataFolderName" : the format of the subfolder name for recording files
"metadataFolderName" : the format of the subfolder name for metadata files
"metricCsvFolderName" : the format of the subfolder name for metric CSV files
"dataTransferFolderName" : the format of the subfolder name for data transfer files
"auditLogFolderName" : the format of the subfolder name for audit log files

File name formatting options
"recordingDataFileNameFormat" : the format of the recording file names
"xmlFileNameFormat" : the format of the XML metadata file names
"jsonFileNameFormat" : the format of the JSON metadata file names
"compactCsvFileNameFormat" : the format of the compact metric CSV file names
"verboseCsvFileNameFormat" : the format of the verbose metric CSV file names
"compactDataTransferFileNameFormat" : the format of the compact data transfer file names
"verboseDataTransferFileNameFormat" : the format of the verbose data transfer file names
"dataTransferSpecificationFileNameFormat" : the format of the DTS file names
"dataTransferSpecificationVersion" : The version of the data transfer format to be exported

File and Folder Name Customization Options

To specify a custom file or folder name, you specify the name with optional, embedded variables. These variables include:

%D: Date/time formatting for trial dates
%N: Date/time formatting for "now"
%X: Export scope (all, study, subject, trial)
%U: Study name
%S: Subject ID
%T: Test type
%C: Condition name
%I: Site name
%P: Product name
%V: Data Transfer Specification Version

The lower case version of any of these identifiers (e.g., %t) results in an all lower-case string.

Default Values

Below is an example of the contents of an ExportOptions.json file, along with their default values:

{
"interactive" : true,
"compressData" : false,
"exportParentFolder" : "",
"includeIncompleteTrials" : false,
"includeRecordingData" : false,
"includeMetadataXml" : false,
"includeMetadataJson" : false,
"includeAuditLogJson" : false,
"includeAuditLogCsv" : false,
"includeCompactMetricsCsv" : false,
"includeVerboseMetricsCsv" : false,
"includeMetricsInMetadata" : false,
"includeDataTransferSpecification" : false,
"includeCompactDataTransfer" : false,
"includeVerboseDataTransfer" : false,
"includeAsymmetryMetrics" : false,
"includeInvisibleTrials" : false,
"nowDateFormat" : "yyyyMMdd-HHmmssz",
"trialDateFormat" : "yyyyMMdd-HHmmssz",
"nowDateFormatUTC" : false,
"trialDateFormatUTC" : false,
"recordingDataFolderName" : "rawData",
"metadataFolderName" : "",
"metricCsvFolderName" : "",
"dataTransferFolderName" : "",
"auditLogFolderName" : "",
"recordingDataFileNameFormat" : "",
"xmlFileNameFormat" : "%XMetadata",
"jsonFileNameFormat" : "%XMetadata",
"compactCsvFileNameFormat" : "%T_Trials",
"verboseCsvFileNameFormat" : "%D_%T_Trial",
"compactDataTransferFileNameFormat" : "%T_Trials.DTSv%V.compact",
"verboseDataTransferFileNameFormat" : "%T_Trials.DTSv%V.verbose",
"dataTransferSpecificationFileNameFormat" : "%T_DTSv%V",
"dataTransferSpecificationVersion" : 3,
"exportFolderNameFormat" : "%P_%X_Export_%N"
}
  • By default, the format of the raw recording (*.h5) file name matches how it was saved to your file system. You can customize this using the Tools->"Set File Name Format" option within Mobility Lab.
  • If you customize your raw recording (*.h5) file name formatting through the "recordingDataFileNameFormat" parameter, references to this new file name will be updated within other exported files (e.g., the metric CSV or metadata XML file formats will reference the exported file names, not the ones saved in your Mobility Lab workspace).
  • Only boolean values that specify "true" will be used as overrides for the export options specified in the Export dialog in Mobility Lab. As an example:
    • If you specify that you wish to export the XML metadata in the Export dialog, but your ExportOptions.json file specifies ["includeMetadataXml" : false], the metadata will be exported.
    • If you don't specify that you wish to export the XML metadata in the Export dialog, but your ExportOptions.json file specifies ["includeMetadataXml" : true], the metadata will be exported.
  • You should make sure you include a unique value (e.g., the date) when specifying the file name formats for export types that generate multiple files. For example, exporting the recording files or the detailed metric CSV files.
  • Some export formats generate at most one file, such as the metadata file formats, or one file per test type, like the compact metric CSV or data transfer formats. You should be careful not to specify dynamic variables such as %D (trial date) or %C (test condition) for these formats, as these variables do not make sense in these contexts.

Example

The following ExportOptions.json file specifies a custom file name for verbose CSV files and recording data. They will have a format similar to:

{
"verboseCsvFileNameFormat":"%D_%S_%T_%C",
"metadataFolderName" : "metadata",
"recordingDataFileNameFormat":"%D_%S_%T_%C"
}

This would have the following behaviors:

  • Whenever the verbose CSV file format is exported, filenames such as "20140206-105643PST_S01_Sway_Feet_Apart__Eyes_Open__Firm_Surface.csv" will be generated
  • These files will be placed in a subfolder named "metadata". If this hadn't been overridden, they would have gone into the main export folder (since the default metadataFolderName is empty)
  • Whenever the recording data is exported, filenames such as "20140206-105643PST_S01_Sway_Feet_Apart__Eyes_Open__Firm_Surface.h5" will be generated
  • These files will be placed in a subfolder named "rawdata", because this is the default

 

 

Have more questions? Submit a request

0 Comments

Article is closed for comments.