tireData.import

Create tireData object from file

Since R2024b

Syntax

obj = tireData.import(filepath)

obj = tireData.import(___,Name=Value)

Description

This function requires Extended Tire Features for Vehicle Dynamics Blockset.

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

You can use the tireData.import function to import text files that use varying formats for variable, unit, and header information. These data file types are supported:

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

• Calspan® DAT data files

• Column-oriented text files

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

obj = tireData.import(___,Name=Value) specifies additional options when importing tire data from column-oriented text files.

Examples

Import Tire Data from Calspan File to tireData Object

Use the tireData.import function to create the tireData object td and import tire data from the Calspan data file calspan_file.dat.

td = tireData.import('calspan_file.dat');

The output tireData object td uses the same coordinate system as defined in the Calspan file. Use the coordinateTransform function to convert to another coordinate system.

Calspan Variable to tireData Object Properties Mapping

The variables from the Calspan data file are assigned to the tireData object properties as shown in the table.

Calspan File Variable	tireData Object Property
ET	et
RL	RL
RE	Re
FX	Fx
FY	Fy
FZ	Fz
MX	Mx
MY	My
MZ	Mz
SEGMENT	segment
V	V
N	omega
SA	alpha
IA	gamma
P	IP
SL	kappa
TSTC	TtreadC
TSTI	TtreadI
TSTO	TtreadO
TSTS	Tsidewall
TLTC	Tinnerlinner
RST	Tsurface
CAT	Tcavity
T	Tw
AMBTMP	Ta

Import Tire Data from CSV to Create tireData Object

Create a tireData object by importing tire data from a CSV file using the tireData.import function. First, define the file to import. Next, create variables using information from the file header, variables, and comments. Then, use these variables to specify the name-value arguments for the tireData.import function. Finally, create the tireData object using the tireData.import function.

Define File to Import

Define the tire data file to import.

importFile="example_tire_data.csv";

The example file contains semicolon-delimited header information and comma-separated data values.

Inspect lines 1 through 21 of the file to view headers, variables, units, comments, and data.

dbtype example_tire_data.csv 1:21

1     $ Tire and test information
2     CoordinateSystem;SAE
3     Size;235/45R18
4     SectionWidth;235
5     AspectRatio;45
6     RimDiameter;18
7     OD;0.66909
8     LoadIndex;94
9     SpeedSymbol;V
10    TestDate;24-Apr-2020 14:55:29
11    Lab;National Tire Research Center - NTRC
12    Machine;MTS Flat-Trac LTRe
13    TestMethod;Lateral
14    RimWidth;8
15    Grit;120 3Mite
16    SurfaceCondition;Dry
17    SurfaceCurvature;0
18    $ Test data
19    time,segment,Fx,Fy,Fz,Mx,My,Mz,IP,SA,IA,SR,phit,Vx,w,NormFx,NormFy
20    s,-,N,N,N,Nm,Nm,Nm,Pa,degr,degr,-,1/m,m/s,rad/s,-,-
21    0.015625,1,-35.1886,461.2821,-2161.5626,19.3236,11.3525,-3.2858,262000,-0.3488,0.0011,0,0,27.7778,84.4857,0.016,-0.213

Define File Format and Information

Define variables using details about the file format and information contained within the CSV file. You will use these variables to specify arguments of the tireData.import function.

Define Header Information

By default, the software ignores header information. To import header information, create the variable ignoreHeaders and set the value to false.

ignoreHeaders = false;

The header delimiter uses a semicolon to separate header information. Create the variable headerDelimiter and set the value to ";".

headerDelimiter = ";";

Some of the header names in the file do not map directly to the names used in the tireData object properties. Create a dictionary that maps the unrecognized header names to the appropriate tireData properties. Define the tireData property as the value and the header name in the file as the key.

headerAlias = dictionary("Size","TireSize",...
                            "OD","OverallDiameter",...
                            "Lab","TestFacility",...
                            "Machine","TestMachine",...
                            "Grit","Surface");

Define Variable Information

The file contains the variables NormFx and NormFy, which the tireData object does not support. Create the variable ignoreVariables and set the value to NormFx and NormFy.

ignoreVariables = ["NormFx","NormFy"];

Some of the variable names in the file do not map directly to the names in tireData object properties. Create a dictionary that maps the unrecognized variable names to the appropriate tireData properties. Define the tireData property as the value and the variable name in the file as the key.

variableAlias = dictionary("time","et",...
                            "IA","gamma",...
                            "SA","alpha",...
                            "SR","kappa",...
                            "w","omega");

Define Unit Information

Create the variable variableUnitsLine and set the value to 20, indicating the line number that contains the units for each variable.

variableUnitsLine = 20;

The file defines the units for slip angle and inclination angle as degr, which MATLAB does not recognize. Create a dictionary that maps the variables with unrecognized units to units recognized by MATLAB. Define the unit recognized by MATLAB as the value and the variable name in the file as the key.

variableUnits = dictionary("SA","deg","IA","deg");

The tireData.import function utilizes information from both the specified units line and the units dictionary to execute necessary unit conversions. Within the tireData object, the default units for slip angle and inclination angle are in radians. Therefore, the data imported in degrees is transformed into radians.

Define Comment Information

Create the variable commentStyle and set the value to "$", to identify which lines contain comments.

commentStyle = "$";

Import Tire Data

Use the tireData.import function to create the tireData object td. Specify these name-value arguments with the variables you previously created:

• IgnoreHeaders = ignoreHeaders

• HeaderDelimiter = headerDelimiter

• HeaderAlias = headerAlias

• IgnoreVariables = ignoreVariables

• VariableAlias = variableAlias

• VariableUnitsLine = variableUnitsLine

• VariableUnits = variableUnits

• CommentStyle = commentStyle

td = tireData.import(importFile,VariableAlias=variableAlias,...
                               HeaderAlias=headerAlias,...
                               VariableUnitsLine=variableUnitsLine,...
                               VariableUnits=variableUnits,...
                               IgnoreVariables=ignoreVariables,...
                               IgnoreHeaders=ignoreHeaders,...
                               HeaderDelimiter=headerDelimiter,...
                               CommentStyle=commentStyle);

Preprocess Imported Tire Data

Once you create a tireData object with tire data populated, you can utilize these functions to preprocess the data before performing tire data analysis and modeling:

• split

• filter

• coordinateTransform

• crop

• downsample

• mean

• median

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.import(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, the tireData.import function performs a conversion 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 tireData.import function automatically detects the delimiter.

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.import function 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.import function 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.import function 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

Output Arguments

obj — Imported tire data

tireData object | array of tireData objects

Imported tire data, returned as a tireData object or an array of tireData objects the same size as the filepath input argument string array.

References

[1] Unrau, Hans-Joachim, and Jürgen Zamow. TYDEX-Format: Description and Reference Manual. Release 1.3, 1997.

Version History

Introduced in R2024b