Main Content

tireData.import

Create tireData object from file

Since R2024b

collapse all in page

    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.

    example

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

    example

    Examples

    collapse all

    This example uses:

    Open Live Script

    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

    This example uses:

    Open Live Script

    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:

    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

    collapse all

    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

    collapse all

    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

    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

    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

    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

    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

    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

    collapse all

    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.

    SpecifierField 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

    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

    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

    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

    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

    collapse all

    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

    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

    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

    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

    collapse all

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

    LocaleLanguageCountry
    "de_DE"GermanGermany
    "en_GB"EnglishUnited Kingdom
    "en_US"EnglishUnited States
    "es_ES"SpanishSpain
    "fr_FR"FrenchFrance
    "it_IT"ItalianItaly
    "ja_JP"JapaneseJapan
    "ko_KR"KoreanKorea
    "nl_NL"DutchNetherlands
    "zh_CN"Chinese (simplified)China

    Example: Locale="ja_JP"

    Data Types: string

    Coordinate Information

    collapse all

    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

    collapse all

    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