readtimeseries

Arguments

filename

name of file to read. Accepted formats: ".xslx", ".csv", ".txt" and ".dat".

opts

file import options obtained by detectImportOptions

Optional pairs OptionName, Value are:

"VariableNames", vector of strings

extracts from the file only the data corresponding to the entered variable names.

"RowTimes", duration or datetime column vector

if the filename has no time, use this property to add a time index in the timeseries.

"StartTime", duration or datetime value

specifies the start time of the timeseries.

"TimeStep", duration or calendarDuration value

time step.

"SampleRate", real scalar

number of samples per second (Hz).

"ConvertTime", function

function to apply on the column specified with RowTimes. It converts the data. For example: to convert to seconds with seconds function.

"Sheet", a string (sheet_name) or positive integer (sheet_index)

specify which sheet to read. Available option only is for Excel files. Default value: first sheet (index 1).

"Range", string or double

A string or 2x2 matrix specifying the range of cells to read.

String formats: "A1:C10" (cell range), "A:C" (column range), "1:3" (row range), "B5" (first cell), "B" (first column), "3" (first row).

Matrix format: [row1 col1; row2 col2] where all values are positive integers >= 1.

Default value: "".

Available option only is for Excel files.

ts

output argument - timeseries object.

Description

The readtimeseries function creates a timeseries from a file. Each column of file is stored in variables. If however the columns have no name, then the default variable names are used (["Time", "Var1", ..., "VarN"]). Accepted file formats are .txt, .dat .csv, and .xlsx.

readtimeseries detects the format file thanks to detectImportOptions function. opts contains all information on the file.

To extract only the necessary variables (columns), use ts = readtimeseries(filename, "VariableNames", value).

Examples

dt = [datetime(2022,1,10):caldays(1):datetime(2022,1,21)]';
hc = [13574; 13169; 11999; 12146; 15456; 10545; 11091; 21657; 11393; 10283; 10924; 16208];
hp = [13593; 15306; 16766; 15941; 14558; 13722; 18401; 14632; 14571; 14925; 14284; 15028];
ts = timeseries(dt, hc, hp, "VariableNames", ["Time", "HC", "HP"]);
writetimeseries(ts, fullfile(TMPDIR, "data.txt"));

r = readtimeseries(fullfile(TMPDIR, "data.txt"));

t = readtimeseries(filename, "Sheet", value)

dt = datetime() + hours(0:4)';
double = [12.5; 8; 0.75; 53.26; 8.42];
bool = [%t; %f; %t; %f; %t];
str = "A" + string(0:4)';
ts = timeseries(dt, double, bool, str, "VariableNames", ["datetime", "double", "bool", "string"])

//           datetime           double   bool   string
//    _______________________   ______   ____   ______
//                                                        
//    2026-03-27 12:02:13.297   12.5     T      A0    
//    2026-03-27 13:02:13.297   8        F      A1    
//    2026-03-27 14:02:13.297   0.75     T      A2    
//    2026-03-27 15:02:13.297   53.26    F      A3    
//    2026-03-27 16:02:13.297   8.42     T      A4    

path = fullfile(TMPDIR, "timeseries.xlsx");
xlsxSheet(path, "create", "timeseriesSheet"); // create timeseriesSheet
writetimeseries(ts, path, "sheet", "timeseriesSheet"); // write timeseries in timeseriesSheet
ts2 = readtimeseries(path, "sheet", "timeseriesSheet")

// ts2 = [5x3 timeseries]

//          datetime           double   bool   string
//   _______________________   ______   ____   ______
//                                                   
//   2026-03-27 12:02:13.297   12.5     T      A0    
//   2026-03-27 13:02:13.297   8        F      A1    
//   2026-03-27 14:02:13.297   0.75     T      A2    
//   2026-03-27 15:02:13.297   53.26    F      A3    
//   2026-03-27 16:02:13.297   8.42     T      A4

See also

• writetimeseries — write a timeseries to file
• timeseries — create a timeseries - table with time as index
• detectImportOptions — structure containing all useful information to import the file

History