tireData.import
Description
This function requires Extended Tire Features for Vehicle Dynamics Blockset.
directly imports tire data from one or multiple data files to create a
obj
= tireData.import(filepath
)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.
specifies additional options when importing tire data from column-oriented text
files.obj
= tireData.import(___,Name=Value
)
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 |
|
---|---|
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:
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=";")
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
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 |
" " " | Space |
" " | Tab |
" " | Semicolon |
" " | 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
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
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
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
See Also
MATLAB Command
You clicked a link that corresponds to this MATLAB command:
Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list:
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)