tireData

Import and store tire measurement data

Since R2023b

Description

Add-On Required: This feature requires the Extended Tire Features for Vehicle Dynamics Blockset add-on.

This object requires Extended Tire Features for Vehicle Dynamics Blockset.

Use a tireData object to store tire measurement data from one of these file types:

• Tyre Data Exchange Format (TYDEX) v1.3 files

• Calspan® DAT data files

• Column-oriented text files

Creation

Syntax

d = tireData()

d = tireData(filepath)

d = tireData(___,Name=Value)

Description

d = tireData() creates an empty tireData object.

d = tireData(filepath) directly imports tire data from one or multiple data files to create a tireData object.

Specify the filepath argument without additional options when importing data directly from TYDEX v1.3 or Calspan files.

d = tireData(___,Name=Value) specifies additional options when importing tire data from column-oriented text files. You can import text files that use varying formats for variable, unit, and header information.

Alternatively, you can use the tireData.import function to import tire data from a file.

Input Arguments

filepath — File path to tire data file

array of strings | array of character vectors | cell array of character vectors

File path to the tire data file, specified as an array of strings, an array of character vectors, or a cell array of character vectors.

These data files are supported:

• Tyre Data Exchange Format (TYDEX) v1.3 files

• Calspan DAT files

• Column-oriented text files

Specify the filepath argument without additional options when importing data directly from TYDEX v1.3 or Calspan files.

Data variables in TYDEX v1.3 files are assigned to the tireData object properties in accordance to the TYDEX v1.3^[1] standard.

For more information on Calspan Tire Testing and Research, visit Calspan Tire Performance Testing.

The software automatically converts units when data files are imported. The data is returned in the coordinate system defined in the Calspan file. To transform the imported tire data to a different coordinate system, see coordinateTransform.

Data Types: char | string

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Example: td = tireData(dataFiles, VariableNames=["et","seget","segment","Fx","Fy"], VariableUnitsLine=2, Delimiter=";")

Variable Information

VariableNames — Tire data variable names

vector of strings | cell vector of character vectors

Tire data variable names, specified as a vector of strings or a cell vector of character vectors. VariableNames is required when the data file does not contain column names. If a variable name is specified for a column that already has a name, the column name is ignored.

The input vector must satisfy these requirements:

• Number of elements in the vector must match the number of columns in the data file.

• Variable names should be arranged in the order in which the data is presented within the data file.

Note

VariableNames must be a tireData data channel property. If you specify both VariableNames and VariableAlias, the VariableAlias argument is ignored.

Example: VariableNames=["et","seget","segment","Fx","Fy"]

Data Types: char | string

VariableAlias — Tire data variable aliases

dictionary object

Tire data variable aliases, specified as a dictionary object. Specify VariableAlias when the variable names in the tire data file do not match the tireData data channel property names. Set the variable from the tire data file as the dictionary key and the associated tireData data channel property as the value.

Note

If you specify both VariableNames and VariableAlias, the VariableAlias argument is ignored.

Example: VariableAlias=dictionary("lonforce","Fx","latforce","Fy")

Data Types: dictionary

VariableUnitsLine — Units line in tire data file

positive scalar integer

Units line in tire data file, specified as a positive scalar integer. If the units in the tire data file differ from the default units associated with the tireData properties, and a units line is specified, a conversion is performed to match the default units. The units in the tire data file must be recognized by MATLAB^® and be convertible to the default units of the tireData property.

Note

If you specify both VariableUnitsLine and VariableUnits, the VariableUnits value is prioritized over the units in the file for any conflicts.

Example: VariableUnitsLine=2

Data Types: single | double | uint8 | uint16 | uint32 | uint64

VariableUnits — Tire data variable units

dictionary object

Tire data variable units, specified as a dictionary object. Specify VariableUnits when variables do not have units specified in the data file and units are different from the default units of the tireData property. The dictionary created must satisfy these requirements:

• Keys must be defined as the tire data variables in the file.

• Values must be defined as the units corresponding to those used in the data. Units specified must be recognized by MATLAB and convertible to the default units of the tireData properties.

• Values must be a string or numeric. If the value is numeric or is a string value that is numeric, the value is applied as a multiplier to the data pertaining to the key channel.

• Dictionary values must be the same data type. If specifying units and multipliers, both must be strings.

Note

If you specify both VariableUnitsLine and VariableUnits, the VariableUnits value is prioritized over the units in the file for any conflicts.

Example: VariableUnits=dictionary("Fz","lbf","sa","deg")

Data Types: dictionary

KeepVariables — Variables to import from tire data file

row vector of strings | cell vector of character vectors

Variables to import from the tire data file, specified as a row vector of strings or a cell vector of character vectors.

Note

If you specify KeepVariables and IgnoreVariables, the IgnoreVariables argument is ignored.

Example: KeepVariables=["Fz","Fx","Fy"]

Data Types: char | string

IgnoreVariables — Variables to ignore when importing from tire data file

row vector of strings | cell vector of character vectors

Variables to ignore when importing from the tire data file, specified as a row vector of strings or a cell vector of character vectors.

Note

If you specify KeepVariables and IgnoreVariables, the IgnoreVariables argument is ignored.

Example: IgnoreVariables=["NFx","NFy","NFz"]

Data Types: char | string

File Format

Delimiter — Field delimiter character

character vector | cell array of character vectors | string

Field delimiter character, specified as a character vector, a cell array of character vectors, or a string. Specify Delimiter using any valid character, such as a comma "," or a period ".".

This table lists some commonly used field delimiter characters.

Specifier	Field Delimiter
"," "comma"	Comma
" " "space"	Space
"\t" "tab"	Tab
";" "semi"	Semicolon
"|" "bar"	Vertical bar
unspecified	If unspecified, the delimiter is automatically detected.

Example: Delimiter=","

Data Types: char | string

DecimalSeparator — Characters indicating decimal separator

character vector | string scalar

Characters indicating the decimal separator in numeric variables, specified as a character vector or string scalar. The tireData object uses the characters specified in the DecimalSeparator argument to distinguish the integer part of a number from the decimal part.

Note

The DecimalSeparator and ThousandsSeparator values must be different.

Example: DecimalSeparator=","

Data Types: char | string

ThousandsSeparator — Characters indicating thousands grouping

character vector | string scalar

Characters indicating thousands grouping, specified as a character vector or string scalar. The thousands' grouping characters act as visual separators, grouping the number at every three place values. The tireData object uses the characters specified in the ThousandsSeparator argument to interpret the numbers being imported.

Note

The DecimalSeparator and ThousandsSeparator values must be different.

Example: ThousandsSeperator=","

Data Types: char | string

HeaderDelimiter — Header field delimiter character

character vector | cell array of character vectors | string

Header field delimiter character, specified as a character vector, a cell array of character vectors, or a string. Specify HeaderDelimiter when the header delimiter is different from the delimiter for the rest of the file. Use any valid character, such as a comma "," or a period ".".

Example: HeaderDelimiter=":"

Data Types: char | string

CommentStyle — Symbols designating text to ignore

character vector | cell array of character vectors | string scalar | string array

Symbols designating text to ignore, specified as a character vector, cell array of character vectors, string scalar, or string array.

For example, specify a character such as "%" to ignore text following the symbol on the same line. Specify a cell array of two character vectors, such as {'/*','*/'}, to ignore any text between those sequences.

Example: CommentStyle={'/*','*/'}

Data Types: char | string

Header Information

IgnoreHeaders — Header information to ignore

true (default) | false | vector of strings | cell vector of character vectors

Header information to ignore from the tire data file, specified as false, true, vector of strings, or a cell array of character vectors. Specify a vector of strings to ignore a subset of the header information.

Example: IgnoreHeaders=["tire size","tire line"]

Data Types: logical | string

HeaderAlias — Header aliases

dictionary object

Header aliases, specified as a dictionary object. Specify HeaderAlias when header names in the file do not match tireData non-data channel property names. Set the header name as the dictionary key and the associated tireData non-data channel property name as the value.

Example: HeaderAlias=dictionary("tire size","TireSize","tire line","TireLine")

Data Types: dictionary

HeaderUnits — Tire data file header variable units

dictionary object

Tire data file header variable units, specified as a dictionary object. Specify HeaderUnits when header variables have units that differ from the default tireData property units. The dictionary created must satisfy these requirements:

• Keys must be defined as the header variables.

• Values must be defined as the units corresponding to units used in the data. Units must be recognized by MATLAB and convertible to the default units of the tireData properties.

• Values must be a string or numeric. If the value is numeric or is a string value that is numeric, the value is applied as a multiplier to the data pertaining to the key channel.

• Dictionary values must be the same data type. If specifying units and multipliers, both must be strings.

Example: HeaderUnits=dictionary("aspectratio","100","RimWidth","mm")

Data Types: dictionary

NumHeaderLines — Number of header lines

0 | positive scalar integer

Number of header lines to skip at the beginning of the tire data file, specified as either 0 or a positive scalar integer. If unspecified, the tireData object automatically detects the number of lines to skip.

Example: NumHeaderLines=2

Data Types: single | double

Date and Time Format

DatetimeFormat — Date and time data format

character vector | string scalar

Date and time data format, specified as a character vector or string scalar that contains letter identifiers. Specify DatetimeFormat when the TestDate header is included in the tire data file. For a complete list of letter identifiers, see the Format property for datetime arrays.

Example: DatetimeFormat="MM/dd/uuuu"

Data Types: char | string

Locale — Locale for reading dates

character vector | string scalar

Locale for reading dates, specified as a character vector or a string scalar of the form xx_YY, where:

• YY is an uppercase ISO 3166-1 alpha-2 code indicating a country.

• xx is a lowercase ISO 639-1 two-letter code indicating a language.

This table lists some common values for the locale.

Locale	Language	Country
"de_DE"	German	Germany
"en_GB"	English	United Kingdom
"en_US"	English	United States
"es_ES"	Spanish	Spain
"fr_FR"	French	France
"it_IT"	Italian	Italy
"ja_JP"	Japanese	Japan
"ko_KR"	Korean	Korea
"nl_NL"	Dutch	Netherlands
"zh_CN"	Chinese (simplified)	China

Example: Locale="ja_JP"

Data Types: string

Coordinate Information

CoordinateSystem — Tire data coordinate system

"ISO" (default) | "SAE" | "H"

Tire data coordinate system, specified as "ISO", "SAE", or "H". Specify CoordinateSystem when the data in the file is not defined in the default coordinate system, ISO. To transform the imported data to a different coordinate system, see coordinateTransform.

Example: CoordinateSystem="SAE"

Data Types: char | string

Object Functions

coordinateTransform	Perform coordinate transformation on tire data channels
crop	Remove data from tireData object
downsample	Decrease sample rate of tireData object by integer factor
export	Export tire data to external file
filter	Apply filter to tireData object data channels
mean	Assign mean value of tire data channel in tireData object to entire tire data channel array
median	Assign median value of tire data channel in tireData objects to entire tire data channel array
plot	Plot tire data
split	Split single tireData object into array of tireData objects
struct	Convert tire data to structure
summaryTable	Applies statistical measure to each data channel in tire data
table	Create table from tire data
tireData.generate	Create tireData objects with synthetic data
tireData.import	Create tireData object from file
violinplot	Plot tire data in tiled violin plot

Version History

Introduced in R2023b

R2024b: Additional data file types supported for tireData objects

In addition to creating a tireData object from a TYDEX file, you can now create a tireData object from Calspan DAT data files or specify additional name-value arguments to use column-oriented text files.