From 723f9bb500d32e1170d4e513efc2f2ac994506dc Mon Sep 17 00:00:00 2001 From: Hani Andreas Ibrahim Date: Thu, 5 May 2022 23:38:23 +0200 Subject: [PATCH 1/4] DI_show & DI_writedat added --- macros/DI_show.sci | 326 +++++++++++++++++++++++++++++++++++++++++ macros/DI_writedat.sci | 212 +++++++++++++++++++++++++++ 2 files changed, 538 insertions(+) create mode 100644 macros/DI_show.sci create mode 100644 macros/DI_writedat.sci diff --git a/macros/DI_show.sci b/macros/DI_show.sci new file mode 100644 index 0000000..9cd7911 --- /dev/null +++ b/macros/DI_show.sci @@ -0,0 +1,326 @@ +// Copyright (C) 2019 Hani Andreas Ibrahim +// +// This program is free software; you can redistribute it and/or modify it under +// the terms of the GNU General Public License as published by the Free Software +// Foundation; either version 3 of the License, or (at your option) any later +// version. +// +// This program is distributed in the hope that it will be useful, but WITHOUT +// ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or +// FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more +// details. +// +// You should have received a copy of the GNU General Public License along with +// this program; if not, see . + +function [dataMat, exitID] = DI_show(path, n) + // Read the first 25 or an arbitary number of lines of a text data file, + // displays them in the console and invoke a reading procedure, if desired. + // + // + // Calling Sequence + // [dataMat] = DI_show() + // [dataMat] = DI_show(path) + // [dataMat] = DI_show(path, n) + // [dataMat] = DI_show(,n) + // [dataMat, exitID] = DI_show() + // [dataMat, exitID] = DI_show(path) + // [dataMat, exitID] = DI_show(path, n) + // [dataMat, exitID] = DI_show(, n) + // + // Parameters + // path: string, target path for the file selector (OPTIONAL) + // n: integer, Number of lines to display (OPTINAL), default: 25 + // dataMat: string, name of the matrix which stores the imported data, if confirmed, default: ans, IMPORTANT: See note below. + // exitID: integer, exit codes, 0=OK, -1, -2, -3, -4=error codes, if data reading was confirmed. IMPORTANT: See note below. + // + // + // Output args, dataMat und exidID, are only available when reading procedure was confirmed in the GUI. It will + // call DI_read() in the background. + // + // + // Description + // Read the first 25 or an arbitary number of lines of a text-based data file and + // displays them in the console for reviewing data, determine delimiter signs, + // comment lines etc. This makes it easier to fill in the right paramezters for + // reading procedures, as DI_read(). + // + // In the GUI the user will be prompted whether he or she wants to load the data + // into a matrix variable after the preview was displayed. If the user committed + // the question the reading procedure DI_read() will be called in the background. + // + // + // + // path: + // + // You can commit an optional target path to the function. This is used to + // open the file selector at the committed target path. If you omit it your home + // directory is set as the target path. + // + // + // + // n: + // + // You can commit an optional number of lines to display. If you do not specify N + // 25 lines will be displayed by default. + // + // + // + // dataMat: + // + // This is the name of the matrix variable which will contain the imported data + // for further processing in Scilab's console or in a script. It is available + // when you confirm data reading in the GUI only. + // + // + // + // exitID: + // + // The exitID gives a feedback what happened inside the function. If + // something went wrong dataMat is always [] (empty). To handle errors in a + // script you can evaluate exitID's error codes (negative numbers): + // + // + // 0: Everything is OK. Matrix dataMat was created + // -1: User canceled file selection + // -2: User canceled parameter dialog box + // -3: Cannot read or interpret data file + // -4: Cannot interpret file correctly - maybe header present (only CSV/TXT data files) + // + // + // They will be available when you confirm data reading in the GUI only. + // + // + // + // + // + // Comma-Separated-Value-, Text-Based Data Files + // + // + // Only available if reading was confirmed in the GUI. + // + // + // Read text-based data files which contains numerical data. The following + // field delimiters are accepted: Comma, semicolon, space(s), tabular(s). + // The decimal delimiter can be point or comma. + // + // + // Note that the file has to be correctly formated. All rows have to have the + // same number of columns. + // + // + // Import Parameter: + // + // + // + // + // + // + // + // + // + // Field Separator: + // + // This is the character which separates the fields and + // numbers, resp. + // In general CSV-files it is the comma (,), in European ones it is + // often the semicolon (;). Sometimes it is a tabulator (tab). Text-based + // data files has a space or spaces as delimiters. + // E.g. to specify a tabulator as separator, type in the word + // "tab", for a space separator the word "space" without quotes. + // + // + // + // Decimal separator: + // + // The character which indentifies the decimal place. In + // general CSV files it is the point (.), in most European ones it is + // the comma (,). + // + // + // + // Number of Header Lines to Skip: + // + // The number of lines to be ignored at the + // beginning of the file. This is useful to skip table headers. + // + // + // + // Row/Columns Range Start: + // + // The row/column at which the import is going to start. Type a number. 1 means + // import starts at row/column 1 inclusively. + // + // + // + // Row/Columns Range End: + // + // The row at which the import is going to end. Type a number or $ (dollar- + // sign). 12 means the import stops at row 12 inclusively, $ means that all + // rows/columns are read to the end. + // + // + // + // + // For CSV and text-based data files there are different prerequisites to + // consider. + // + // + // + // Comma-separated-value (*.csv): + // + // All rows have to have the same number of columns. That does not mean that + // every cell has to be occupied by a number. Only the separator has to be + // present: + // + // + // 2.3 , 4.4 , 7.6 , 9.5 + // 5.6 , 6.9 , , + // + // Strings or missing data (see above) are represented as Nan (not-a-number) + // in the matrix. E.g.: + // + // + // 2.3 4.4 7.6 9.5 + // 5.6 6.9 Nan Nan + // + // + // + // + // Text-based data (*.dat, *.txt): + // + // All rows have to have the same number of columns and should not contain + // strings (text). Otherwise the data will be imported as a string matrix and + // not a number matrix. + // + // + // | 2.3 4.4 7.6 9.5 | + // |  | + // | 5.6 6.9 | + // + // + // + // + // + // Examples + // [mat, id] = DI_show(fullfile(DI_getpath(), "demos"),10); + // if id == 0 & mat ~= [] then // Plot data if import was successful + // plot(mat(:,1),mat(:,14),"-") + // xtitle("Central England Temperature","Year","Mean Temperature [°C]") + // else + // mprintf("Reading of data not confirmed\n") + // end + // abort; + // // Further examples (will not be executed by "play") + // DI_show(fullfile(DI_getpath(), "demos")); + // DI_show(pwd()); // Opens current directory and read 25 lines (default) + // DI_show(,10); // Opens home directory (default) and reads 10 lines + // DI_show(); // Opens home directory (default) and reads 25 lines (default) + // + // See also + // DI_read + // DI_writedat + // csvRead + // fscanfMat + // + // Authors + // Hani A. Ibrahim - hani.ibrahim@gmx.de + + // Load Internals lib + libpath = DI_getpath() + di_internallib = lib(fullfile(libpath,"macros","internals")) + + // Support functions -------------------------------------------------------- + + // File handling clean up + function errorCleanUp() + mclose("all"); + endfunction + + // Check for integer > 0 + function i = isInt(n) + if pmodulo(n,1) == 0 & n==0 then + i = %T; + else + i = %F; + end + endfunction + + // ------------------------------------------------------------------------- + + // Check for input and output options + [lhs,rhs]=argn() + apifun_checkrhs("DI_show", rhs, 0:2); // Input args => 0 to 2 + apifun_checklhs("DI_show", lhs, 0:2); // Output args => 0 to 2 + + // Platform-dependent HOME path if "path" was not commited + if ~exists("path") then + if getos() == "Windows" then + path = getenv("USERPROFILE"); + else // Unix, GNU/Linux, macOS + path = getenv("HOME"); + end + end + + + // Set default number of diplayed lines, if n ist not committed + if ~exists("n") then + n = 25; + elseif isInt(n) then + messagebox("n is not a number or <= 0. Type in number, e.g. 30. Try again", "Error", "error", "modal"); + end + + // Init values + exitID = 0; // All OK + rows = []; // No. of rows read + dataMat = []; // Matrx von Data if reading data was desired + + // Get file name + fn=uigetfile(["*.csv|*.txt|*.dat","Data files (*.csv, *.txt, *.dat)"],path,"Choose a Text-Data File"); + if fn == "" then +// exitID = -1; // Canceled file selector + messagebox("Canceled file selector", "Canceled", "error", "modal"); + return; + end + + // Read first lines of the data file + try + fid1 = mopen(fn, "r"); + rows = mgetl(fid1, n); // Read n lines of the file in a matrix of strings + mclose(fid1); + catch +// exitID = -3; // Error while interpreting CSV file + messagebox("Error while reading file", "Error", "error", "modal"); + errorCleanUp(); + return; + end + + // Display rows of the file ------------------------------------------------ + + // Prevent the display loop from overflowing if n > rows + lrows = size(rows)(1); // No. of rows + if n > lrows then + n = lrows + end + + mprintf( .. + " First %i rows of the file: %s\n\n", .. + n, fn) + + mprintf(.. + " No.| Data\n" + .. + "--------------------------------------------------------------------------\n" .. + ) + for i=1:n + mprintf("%3i | %s\n", i, rows(i)); + end + + // Go to DI_read directly? + aw = messagebox("Do you want to read data now?", "Read data?", "question", ["Yes" "No"], "modal") + if aw == 1 then // yes + [dataMat, exitID] = DI_int_readcsv(fn); + end + + return + +endfunction diff --git a/macros/DI_writedat.sci b/macros/DI_writedat.sci new file mode 100644 index 0000000..6d708a3 --- /dev/null +++ b/macros/DI_writedat.sci @@ -0,0 +1,212 @@ +// Copyright (C) 2022 Hani Andreas Ibrahim +// +// This program is free software; you can redistribute it and/or modify it under +// the terms of the GNU General Public License as published by the Free Software +// Foundation; either version 3 of the License, or (at your option) any later +// version. +// +// This program is distributed in the hope that it will be useful, but WITHOUT +// ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or +// FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more +// details. +// +// You should have received a copy of the GNU General Public License along with +// this program; if not, see . + +function [exitID] = DI_writedat(datMat, path) + // Exports numerical data stored in a matrix variable to a text data file interactively + // + // Calling Sequence + // [exitID] = DI_writedat(datMat) + // [exitID] = DI_writedat(datMat, path) + // + // Parameters + // datMat: name of the matrix variable you want to store in a file + // path: a string, target path for the file selector (OPTIONAL) + // exitID: an integer, exit codes, 0=OK, -1, -2, -3, -4=error codes, see below. + // + // Description + // Write a Scilab matrix of doubles to a CSV or other text-based file interactively. + // If you do not specify a file-extention explicitely, ".txt" is added automatically. + // + // + // + // path: + // + // You can commit an optional path to the function. This is used to open + // the file selector at the committed target path. If you omit it your home + // directory is set as the target path. + // + // + // + // datMat: + // + // This is the name of the matrix variable which contents the data you want + // to export. + // + // + // + // exitID: + // + // The exitID gives a feedback what happened inside the function. If + // something went wrong datMat is always [] (empty). To handle errors in a + // script you can evaluate exitID's error codes (negative numbers): + // + // + // 0: Everything is OK. Matrix datMat was created + // -1: User canceled file selection + // -2: User canceled parameter dialog box + // -3: Cannot write CSV file + // -4: No matrix variable name specified + // + // + // + // + // + // Export Parameter: + // + // + // + // + // + // + // + // + // + // Field Separator: + // + // This is the character which separates the fields and + // numbers, resp. + // In general CSV-files it is the comma (,), in European ones it is + // often the semicolon (;). Sometimes it is a tabulator (tab) or a space + // (space). E.g. to specify a tabulator as the separator, type in the word + // "tab" without quotes. + // + // If you select space just ONE space character delimits the data. + // + // + // + // Decimal separator: + // + // The character which indentifies the decimal place. In + // general CSV files it is the point (.), in most European ones it is + // the comma (,). + // + // + // + // Comment header: + // + // Place a comment in the first line/row of the file. This is useful to + // describe your data. Just one line is supported (OPTIONAL). + // + // + // + // + // Examples + // dat = [32.4 34.6 36.5 32.6 ; 102.4 105.0 104.8 102.6]; + // // Open the file selector at the currend directory + // // and write matrix "dat" to the specified csv-file + // [exitID] = DI_writedat(dat, pwd()); + // disp("Exit-ID: " + string(exitID)) // Displays exit code + // + // See also + // DI_readcsv + // DI_readxls + // DI_read + // csvWrite + // csvRead + // fscanfMat + // + // Authors + // Hani A. Ibrahim - hani.ibrahim@gmx.de + + [lhs,rhs]=argn() + apifun_checkrhs("DI_writedat", rhs, 1:2); // Input args + apifun_checklhs("DI_writedat", lhs, 1); // Output args + apifun_checktype("DI_writedat", datMat, "datMat", 1, "constant") + if rhs == 2 then + apifun_checktype("DI_writedat", path, "path", 2,"string"); + end + + + // init values + exitID = 0; // All OK + + // Platform-dependent HOME path if "path" was not commited + if ~exists("path") then + if getos() == "Windows" then + path = getenv("USERPROFILE"); + else // Unix, GNU/Linux, macOS + path = getenv("HOME"); + end + end + + // Get filename incl. path of an CSV file + fn=uiputfile(["*.csv|*.dat|*txt","Text data files (*.csv,*.dat,*.txt)"],path,"Choose a filename to store numerical data") + if fn == "" then + exitID = -1; // Canceled file selector + return; + end + + // Checking data input + if datMat == "" then + exitID = -4; // no matrix name specified => error + return; + end + + // Extension check + [fnp, fnn, fne] = fileparts(fn); + if fne == "" then + fn = fullfile(fnp, fnn + ".txt"); // Add .txt-Extention to a filename if no extension specified + end + + // Get some parameters for interpreting the csv file and the name of the output matrix + // Initial standard values. + fld_sep = ","; + dec = "."; + com = ""; + + while %t do + labels=["Field separator: , | ; | tab | space"; "Decimal separator: . | ,";"Comment header"]; + datlist=list("str", 1, "str", 1, "str", 1); + values=[fld_sep; dec; com]; + [ok, fld_sep, dec, com] = getvalue("CSV and Scilab parameters", labels, datlist, values); + + if ok == %F then + exitID = -2; // canceled parameter box + return; + end + + // Checking input values + if fld_sep ~= "," & fld_sep ~= ";" & fld_sep ~= "tab" & fld_sep ~= "space" then // field separator + messagebox("Field sparator is empty or wrong. Try again", "Error", "error", "modal") + //fld_sep = ","; + continue; + elseif dec ~= "," & dec ~= "." then// decimal separator + messagebox("Decimal separator the wrong format. Try again", "Error", "error", "modal") + continue; + else + break; + end + end + + // Field separator + if fld_sep == "tab" then + fld_sep = ascii(9); // tabulator as separator + elseif fld_sep == "space" then + fld_sep = ascii(32); // space as separator + end + + // Write CSV file in datMat + try + if com == "" then // No comment committed + csvWrite(datMat, fn, fld_sep, dec); + else + csvWrite(datMat, fn, fld_sep, dec, [], com); + end + catch + exitID = -3; // Error while writing CSV file + return; + end + +endfunction From 6d42efa8f59c98a8c3f4f6e0126e3c60905c1647 Mon Sep 17 00:00:00 2001 From: Hani Andreas Ibrahim Date: Fri, 6 May 2022 00:31:37 +0200 Subject: [PATCH 2/4] Overview page updated --- help/en_US/0dataint-overview.xml | 41 ++++++++++++++++++++++++-------- macros/DI_show.sci | 6 ++--- 2 files changed, 34 insertions(+), 13 deletions(-) diff --git a/help/en_US/0dataint-overview.xml b/help/en_US/0dataint-overview.xml index 09ce4d1..3148a6d 100644 --- a/help/en_US/0dataint-overview.xml +++ b/help/en_US/0dataint-overview.xml @@ -13,7 +13,7 @@ Introduction and Purpose - This toolbox provides functions for importing and exporting numeric tabular data (*.csv, *.dat, *.txt, *.xls) without hassle. It is based on Scilab's in-built functions csvRead(), xlsRead(), and cvsWrite(). The purpose of this toolbox is to make the use of these functions more convenient by introducing a GUI for selecting the files and specifying the im- or export parameters. + This toolbox provides functions for importing and exporting numeric tabular data (*.csv, *.dat, *.txt, *.xls) without hassle. It is based on Scilab's in-built functions csvRead(), xlsRead(), fscanfMat() and cvsWrite(). The purpose of this toolbox is to make the use of these functions more convenient by introducing a GUI for selecting the files and specifying the im- or export parameters. Choose data file: @@ -72,7 +72,7 @@ - dataINT cannot import XML-based Excel files (Excel 2007 and higher)! + dataINT cannot import XML-based Excel files (Excel 2007 and higher) yet! But the toolbox "XLreadwrite" will be called in future versions to offer this feature, too. @@ -81,31 +81,52 @@ Functions - DI_readcsv: + DI_read: - Read data from a comma-separated-value or another text-based data file and stores it into a matrix variable interactively. + Read data from a comma-separated-value, text-based data file or a binary Excel 95-2003 file and stores it into a matrix variable interactively. - DI_readxls: + DI_show: - Read data from a binary Excel 95-2003 file and stores it into a matrix variable interactively. + Read the first 25 or an arbitrary number of lines of a text data file, displays them in the console and invoke the reading procedure "DI_read" after, if desired. - DI_read: + DI_writedat: - Combines functionality of DI_readcsv and DI_readxls in one function. + Write a Scilab matrix of doubles to a comma-separated value or other text-based file interactively. + + Type "demo_gui()" in Scilab's console and search for "dataINT" to get started. + + + Functions (deprecated) + The following functions are obsolete. To avoid breaking legal scripts, the code will stay in the toolbox but will be removed from the documentation. + - DI_writecsv: + DI_readcsv: + + Read data from a comma-separated-value or another text-based data file and stores it into a matrix variable interactively. + The successor is DI_read. + + + + DI_readxls: + + Read data from a binary Excel 95-2003 file and stores it into a matrix variable interactively. + The successor is DI_read. + + + + DI_writecsv: Write a Scilab matrix of doubles to a comma-separated value or other text-based file interactively. + The successor is DI_writedat. - Type "demo_gui()" in Scilab's console and search for "dataINT" to get started. Authors diff --git a/macros/DI_show.sci b/macros/DI_show.sci index 9cd7911..6f2978a 100644 --- a/macros/DI_show.sci +++ b/macros/DI_show.sci @@ -14,8 +14,8 @@ // this program; if not, see . function [dataMat, exitID] = DI_show(path, n) - // Read the first 25 or an arbitary number of lines of a text data file, - // displays them in the console and invoke a reading procedure, if desired. + // Read the first 25 or an arbitrary number of lines of a text data file, + // displays them in the console and invoke a reading procedure after, if desired. // // // Calling Sequence @@ -40,7 +40,7 @@ function [dataMat, exitID] = DI_show(path, n) // // // Description - // Read the first 25 or an arbitary number of lines of a text-based data file and + // Read the first 25 or an arbitrary number of lines of a text-based data file and // displays them in the console for reviewing data, determine delimiter signs, // comment lines etc. This makes it easier to fill in the right paramezters for // reading procedures, as DI_read(). From 5db90219451ef95ab7f1864987b2e1c7a437a49d Mon Sep 17 00:00:00 2001 From: Hani Andreas Ibrahim Date: Fri, 6 May 2022 00:48:03 +0200 Subject: [PATCH 3/4] Demos added & updated --- demos/dataint.dem.gateway.sce | 2 +- demos/read.dem.sce | 2 +- demos/{dataint.dem.sce => show.dem.sce} | 38 ++++++++----------------- 3 files changed, 14 insertions(+), 28 deletions(-) rename demos/{dataint.dem.sce => show.dem.sce} (57%) diff --git a/demos/dataint.dem.gateway.sce b/demos/dataint.dem.gateway.sce index 00f6ade..e0730ac 100644 --- a/demos/dataint.dem.gateway.sce +++ b/demos/dataint.dem.gateway.sce @@ -5,7 +5,7 @@ function subdemolist = demo_gateway() demopath = get_absolute_file_path("dataint.dem.gateway.sce"); subdemolist = [ - "DI_readcsv and DI_readxls-Demo", "dataint.dem.sce"; .. + "DI_show-Demo", "show.dem.sce"; .. "DI_read-Demo", "read.dem.sce"; .. ]; diff --git a/demos/read.dem.sce b/demos/read.dem.sce index 0a40ec8..981f7f8 100644 --- a/demos/read.dem.sce +++ b/demos/read.dem.sce @@ -32,7 +32,7 @@ function read_demo() disp(dat) // Plot data - plot(dat(:,1),dat(:,14),".-") + plot(dat(:,1),dat(:,14),"-") xtitle("Central England Temperature","Year","Mean Temperature [°C]") // diff --git a/demos/dataint.dem.sce b/demos/show.dem.sce similarity index 57% rename from demos/dataint.dem.sce rename to demos/show.dem.sce index 66f3c43..7a510ff 100644 --- a/demos/dataint.dem.sce +++ b/demos/show.dem.sce @@ -13,13 +13,11 @@ // You should have received a copy of the GNU General Public License along with // this program; if not, see . -function dataint_demo() +function show_demo() - messagebox("Central England Temperature", "modal","info","Ok"); - aw = messagebox("Import from CSV or XLS-file?", "Data source", "question", ["CSV" "XLS"], "modal") + messagebox(["Central England Temperature";"DI_show Demo, preview text-based data and read data"], "modal","info","Ok"); - if aw == 1 then // CSV import - [dat,id] = DI_readcsv(fullfile(DI_getpath(), "demos")); + [dat,id] = DI_show(get_absolute_file_path("show.dem.sce"),10); if (id == -1 | id == -2) then // Check for abortion by the user messagebox("Aborted by user") disp("Aborted by user"); @@ -29,30 +27,18 @@ function dataint_demo() disp("Cannot read file"); abort; end - else // XLS import - [dat,id] = DI_readxls(fullfile(DI_getpath(), "demos")); - if (id == -1 | id == -2) then - messagebox("Aborted by user") - disp("Aborted by user"); - abort; - elseif id < -2 then - messagebox("Cannot read file") - disp("Cannot read file"); - abort; - end - end - - // Display data - disp(dat) - // Plot data - plot(dat(:,1),dat(:,14),".-") - xtitle("Central England Temperature","Year","Mean Temperature [°C]") + // Display and plot data if available + if dat ~= [] then + disp(dat) + plot(dat(:,1),dat(:,14),"-") + xtitle("Central England Temperature","Year","Mean Temperature [°C]") + end // // Load this script into the editor // - filename = "dataint.dem.sce"; + filename = "show.dem.sce"; dname = get_absolute_file_path(filename); editor ( fullfile(dname,filename) ); @@ -60,5 +46,5 @@ endfunction // Main -dataint_demo(); -clear dataint_demo; +show_demo(); +clear show_demo; From d80a6a2b56a83e613376e6d160b848b55a9ef9bf Mon Sep 17 00:00:00 2001 From: Hani Andreas Ibrahim Date: Mon, 9 May 2022 00:52:23 +0200 Subject: [PATCH 4/4] A lot of updates and reviews --- DESCRIPTION | 38 +- demos/show.dem.sce | 2 +- help/en_US/DI_read.xml | 13 +- help/en_US/DI_show.xml | 263 +++++++++++ help/en_US/DI_writedat.xml | 161 +++++++ help/en_US/deprecated/CHAPTER | 1 + help/en_US/{ => deprecated}/DI_readcsv.xml | 461 ++++++++++---------- help/en_US/{ => deprecated}/DI_readxls.xml | 337 +++++++------- help/en_US/{ => deprecated}/DI_writecsv.xml | 330 +++++++------- help/en_US/update_help.sce | 19 +- macros/DI_read.sci | 13 +- macros/DI_readcsv.sci | 20 +- macros/DI_readxls.sci | 13 +- macros/DI_show.sci | 16 +- macros/DI_writecsv.sci | 23 +- macros/DI_writedat.sci | 11 +- readme.txt | 38 +- 17 files changed, 1115 insertions(+), 644 deletions(-) create mode 100644 help/en_US/DI_show.xml create mode 100644 help/en_US/DI_writedat.xml create mode 100644 help/en_US/deprecated/CHAPTER rename help/en_US/{ => deprecated}/DI_readcsv.xml (90%) rename help/en_US/{ => deprecated}/DI_readxls.xml (89%) rename help/en_US/{ => deprecated}/DI_writecsv.xml (85%) diff --git a/DESCRIPTION b/DESCRIPTION index 4a75927..3951220 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -26,7 +26,7 @@ Summary: dataINT provides userfriendly INTERACTIVE reading and writing of csv- a // 'major.minor.patch', where all fields are numbers. // If you are just starting your toolbox, you should use '0.1' or '0.1.0'. // Use '1.0' or '1.0.0' for a tested, good quality first version. -Version: 1.1.1 +Version: 1.2.0 // Name(s) of the author(s) of this toolbox. // They are usually the original copyright holders @@ -66,25 +66,25 @@ ScilabVersion: >= 5.5 Depends: >= apifun 0.4.0 // Creation date, e.g. 2019-05-05 -Date: 2019-09-03 +Date: 2022-05-06 Description: Toolbox for easy and interactive reading and writing of data files - dataINT offers functions for convienient interactice im-/export of data files, - as comma-separated-value- (*.csv, *.dat, *.txt) and binary Excel files (*.xls) - to or from a Scilab matrix. + dataINT offers functions for convenient, interactive im-/export of test-based + data files (*.csv, *.dat, *.txt) to or from a Scilab matrix or from a binary + Excel files (*.xls), respectively. - Parameters, to specify the im-/export, can convieniently entered in a dialog + Parameters, to specify the im-/export, can conveniently entered in a dialog box and the file selection is done by the platform-specific file selection dialog. You can specify the following im-/export parameters: - Field separator (comma, semicolon, tab, space) - Decimal separator (comma, point) - - Rows and Colums you want to import (DI_readcsv, DI_readxls only) - - Sheet you want to import (DI_readxls only) - - Number of lines to skip, e.g. header line(s) (DI_readcsv, DI_readxls only) - - Comment header line to describe your data (DI_writecsv only) + - Rows and columns you want to import + - Sheet you want to import + - Number of lines to skip, e.g. header line(s) + - Comment header line to describe your data IMPORTANT: dataINT does not handle data from XML-based Excel files (.xlsx)! NOTE: dataINT handles doubles only. @@ -95,21 +95,27 @@ Description: Toolbox for easy and interactive reading and writing of data files FUNCTIONS: - * DI_readcsv - Read comma-separated value files (*.csv, *.dat, *.txt) interactively. - * DI_readxls - Read binary Excel files (*.xls) interactively. * DI_read Combines functionality of DI_readcsv and DI_readxls in one function - * DI_writecsv + * DI_show + Read the first 25 or an arbitrary number of lines of a text data file, + displays them in the console and invoke the reading procedure after, if + desired. + * DI_writedat Write comma-separated value files (*.csv, *.dat, *.txt) interactively. - dataINT is available for Scilab 5.5.x and Scilab 6.0.x and cross-platform. + dataINT is available for Scilab 5.5.x, 6.0.x and 6.1.x. Furthermore + dataINT is cross-platform. --------------------------------------------------------------------- CHANGELOG: + 1.2.0 + - DI_show function added + - DI_writedat replaces DI_writecsv + - Deprecation of DI_readcsv and DI_readxls. Successor of both is DI_read + 1.1.1 - Fix decimal-comma-bug when reading/parsing space separated text files with decimal commas diff --git a/demos/show.dem.sce b/demos/show.dem.sce index 7a510ff..a330933 100644 --- a/demos/show.dem.sce +++ b/demos/show.dem.sce @@ -17,7 +17,7 @@ function show_demo() messagebox(["Central England Temperature";"DI_show Demo, preview text-based data and read data"], "modal","info","Ok"); - [dat,id] = DI_show(get_absolute_file_path("show.dem.sce"),10); + [dat,id] = DI_show(get_absolute_file_path("show.dem.sce"),10); // Show the first 10 lines of the data file if (id == -1 | id == -2) then // Check for abortion by the user messagebox("Aborted by user") disp("Aborted by user"); diff --git a/help/en_US/DI_read.xml b/help/en_US/DI_read.xml index d1c1c52..54ac486 100644 --- a/help/en_US/DI_read.xml +++ b/help/en_US/DI_read.xml @@ -17,7 +17,7 @@ DI_read - Imports a data file (comma-separated-value, Excel-xls, text-based) in a matrix variable interactively. Combined functionality of DI_readcsv() and DI_readxls(). + Imports a data file (comma-separated-value, Excel-xls, text-based) in a matrix variable interactively. @@ -131,7 +131,7 @@ E.g. to specify a tabulator as separator, type in the word Decimal separator: -The character which indentifies the decimal place. In +The character which identifies the decimal place. In general CSV files it is the point (.), in most European ones it is the comma (,). @@ -264,8 +264,8 @@ rows/columns are read to the end. See also - DI_readxls - DI_readcsv - DI_writecsv + DI_show + DI_writedat csvRead readxls fscanfMat diff --git a/help/en_US/DI_show.xml b/help/en_US/DI_show.xml new file mode 100644 index 0000000..78d4b6c --- /dev/null +++ b/help/en_US/DI_show.xml @@ -0,0 +1,263 @@ + + + + + + + + DI_show + Read and display the first 25 or an arbitrary number of lines of a text data file. + + + + + Calling Sequence + + [dataMat] = DI_show() + [dataMat] = DI_show(path) + [dataMat] = DI_show(path, n) + [dataMat] = DI_show(,n) + [dataMat, exitID] = DI_show() + [dataMat, exitID] = DI_show(path) + [dataMat, exitID] = DI_show(path, n) + [dataMat, exitID] = DI_show(, n) + + + + + + Parameters + + path: + string, target path for the file selector (OPTIONAL) + n: + integer, Number of lines to display (OPTINAL), default: 25 + dataMat: + string, name of the matrix which stores the imported data, if confirmed, default: ans, IMPORTANT: See note below. + exitID: + integer, exit codes, 0=OK, -1, -2, -3, -4=error codes, if data reading was confirmed. IMPORTANT: See note below. + + + + + Description + +Read the first 25 or an arbitrary number of lines of a text-based data file and +displays them in the console for reviewing data, determine delimiter signs, +comment lines etc. This makes it easier to fill in the right paramezters for +reading procedures, as DI_read(). + + +In the GUI the user will be prompted whether he or she wants to load the data +into a matrix variable after the preview was displayed. If the user committed +the question the reading procedure DI_read() will be called in the background. + + + + +path: + +You can commit an optional target path to the function. This is used to +open the file selector at the committed target path. If you omit it your home +directory is set as the target path. + + + +n: + +You can commit an optional number of lines to display. If you do not specify N +25 lines will be displayed by default. + + + +dataMat: + +This is the name of the matrix variable which will contain the imported data +for further processing in Scilab's console or in a script. It is available +when you confirm data reading in the GUI only. + + + +exitID: + +The exitID gives a feedback what happened inside the function. If +something went wrong dataMat is always [] (empty). To handle errors in a +script you can evaluate exitID's error codes (negative numbers): + + + 0: Everything is OK. Matrix dataMat was created +-1: User canceled file selection +-2: User canceled parameter dialog box +-3: Cannot read or interpret data file +-4: Cannot interpret file correctly - maybe header present (only CSV/TXT data files) + + +They will be available when you confirm data reading in the GUI only. + + + + + + +Comma-Separated-Value-, Text-Based Data Files + + + +Only available if reading was confirmed in the GUI. + + + +Read text-based data files which contains numerical data. The following +field delimiters are accepted: Comma, semicolon, space(s), tabular(s). +The decimal delimiter can be point or comma. + + + +Note that the file has to be correctly formated. All rows have to have the +same number of columns. + + + +Import Parameter: + + + + + + + + + + + +Field Separator: + +This is the character which separates the fields and +numbers, resp. +In general CSV-files it is the comma (,), in European ones it is +often the semicolon (;). Sometimes it is a tabulator (tab). Text-based +data files has a space or spaces as delimiters. +E.g. to specify a tabulator as separator, type in the word +"tab", for a space separator the word "space" without quotes. + + + +Decimal separator: + +The character which identifies the decimal place. In +general CSV files it is the point (.), in most European ones it is +the comma (,). + + + +Number of Header Lines to Skip: + +The number of lines to be ignored at the +beginning of the file. This is useful to skip table headers. + + + +Row/Columns Range Start: + +The row/column at which the import is going to start. Type a number. 1 means +import starts at row/column 1 inclusively. + + + +Row/Columns Range End: + +The row at which the import is going to end. Type a number or $ (dollar- +sign). 12 means the import stops at row 12 inclusively, $ means that all +rows/columns are read to the end. + + + + + +For CSV and text-based data files there are different prerequisites to +consider. + + + + +Comma-separated-value (*.csv): + +All rows have to have the same number of columns. That does not mean that +every cell has to be occupied by a number. Only the separator has to be +present: + + +2.3 , 4.4 , 7.6 , 9.5 +5.6 , 6.9 , , + +Strings or missing data (see above) are represented as Nan (not-a-number) +in the matrix. E.g.: + + +2.3 4.4 7.6 9.5 +5.6 6.9 Nan Nan + + + + +Text-based data (*.dat, *.txt): + +All rows have to have the same number of columns and should not contain +strings (text). Otherwise the data will be imported as a string matrix and +not a number matrix. + + +| 2.3 4.4 7.6 9.5 | +|  | +| 5.6 6.9 | + + + + + + + + + + + Examples + + + + + See also + + DI_read + DI_writedat + csvRead + fscanfMat + + + + + Authors + + Hani A. Ibrahim - hani.ibrahim@gmx.de + + + diff --git a/help/en_US/DI_writedat.xml b/help/en_US/DI_writedat.xml new file mode 100644 index 0000000..debdcc7 --- /dev/null +++ b/help/en_US/DI_writedat.xml @@ -0,0 +1,161 @@ + + + + + + + + DI_writedat + Exports numerical data stored in a matrix variable to a text data file interactively. + + + + + Calling Sequence + + [exitID] = DI_writedat(datMat) + [exitID] = DI_writedat(datMat, path) + + + + + + Parameters + + datMat: + name of the matrix variable you want to store in a file + path: + a string, target path for the file selector (OPTIONAL) + exitID: + an integer, exit codes, 0=OK, -1, -2, -3, -4=error codes, see below. + + + + + Description + +Write a Scilab matrix of doubles to a CSV or other text-based file interactively. +If you do not specify a file-extension explicitly, ".txt" is added automatically. + + + + +path: + +You can commit an optional path to the function. This is used to open +the file selector at the committed target path. If you omit it your home +directory is set as the target path. + + + +datMat: + +This is the name of the matrix variable which contents the data you want +to export. + + + +exitID: + +The exitID gives a feedback what happened inside the function. If +something went wrong datMat is always [] (empty). To handle errors in a +script you can evaluate exitID's error codes (negative numbers): + + + 0: Everything is OK. Matrix datMat was created +-1: User canceled file selection +-2: User canceled parameter dialog box +-3: Cannot write CSV file +-4: No matrix variable name specified + + + + + + +Export Parameter: + + + + + + + + + + + +Field Separator: + +This is the character which separates the fields and +numbers, resp. +In general CSV-files it is the comma (,), in European ones it is +often the semicolon (;). Sometimes it is a tabulator (tab) or a space +(space). E.g. to specify a tabulator as the separator, type in the word +"tab" without quotes. + +If you select space just ONE space character delimits the data. + + + +Decimal separator: + +The character which identifies the decimal place. In +general CSV files it is the point (.), in most European ones it is +the comma (,). + + + +Comment header: + +Place a comment in the first line/row of the file. This is useful to +describe your data. Just one line is supported (OPTIONAL). + + + + + + + + + + Examples + + + + + See also + + DI_show + DI_read + csvWrite + csvRead + fscanfMat + + + + + Authors + + Hani A. Ibrahim - hani.ibrahim@gmx.de + + + diff --git a/help/en_US/deprecated/CHAPTER b/help/en_US/deprecated/CHAPTER new file mode 100644 index 0000000..0eb8bea --- /dev/null +++ b/help/en_US/deprecated/CHAPTER @@ -0,0 +1 @@ +title = Deprecated \ No newline at end of file diff --git a/help/en_US/DI_readcsv.xml b/help/en_US/deprecated/DI_readcsv.xml similarity index 90% rename from help/en_US/DI_readcsv.xml rename to help/en_US/deprecated/DI_readcsv.xml index ad0f596..5fb4ace 100644 --- a/help/en_US/DI_readcsv.xml +++ b/help/en_US/deprecated/DI_readcsv.xml @@ -1,226 +1,235 @@ - - - - - - - - DI_readcsv - Imports a CSV file (comma-separated-value) in a matrix variable interactively - - - - - Calling Sequence - - [csvMat] = DI_readcsv() - [csvMat] = DI_readcsv(path) - [csvMat, exitID] = DI_readcsv() - [csvMat, exitID] = DI_readcsv(path) - - - - - - Parameters - - path: - a string, target path for the file selector (OPTIONAL) - csvMat: - a string, name of the matrix which stores the imported data - exitID: - an integer, exit codes, 0=OK, -1, -2, -3, -4=error codes, see below. - - - - - Description - -Read numerical data from a comma-separated-value (*.csv) or another text-based -data file (*.dat, *.txt) and stores it into a matrix variable interactively. - - -The following field delimiters are accepted: Comma, semicolon, space(s), -tabular(s). The decimal delimiter can be point or comma. - - - -Note that the file has to be correctly formated. All rows have to have the -same number of columns. - - - - - -path: - -You can commit an optional path to the function. This is used to open -the file selector at the committed target path. If you omit it your home -directory is set as the target path. - - - -csvMat: - -This is the name of the matrix variable which will content the imported data -for further processing in Scilab's console or in a script. - - - -exitID: - -The exitID gives a feedback what happened inside the function. If -something went wrong csvMat is always [] (empty). To handle errors in a -script you can evaluate exitID's error codes (negative numbers): - - - 0: Everything is OK. Matrix csvMat was created --1: User canceled file selection --2: User canceled parameter dialog box --3: Cannot read or interpret CSV file --4: Cannot interpret file correctly - maybe header present - - - - - - -Import Parameter: - - - - - - - - - - - -Field Separator: - -This is the character which separates the fields and -numbers, resp. -In general CSV-files it is the comma (,), in European ones it is -often the semicolon (;). Sometimes it is a tabulator (tab). Text-based -data files has a space or spaces as delimiters. -E.g. to specify a tabulator as separator, type in the word -"tab", for a space separator the word "space" without quotes. - - - -Decimal separator: - -The character which indentifies the decimal place. In -general CSV files it is the point (.), in most European ones it is -the comma (,). - - - -Number of Header Lines to Skip: - -The number of lines to be ignored at the -beginning of the file. This is useful to skip table headers. - - - -Row/Columns Range Start: - -The row/column at which the import is going to start. Type a number. 1 means -import starts at row/column 1 inclusively. - - - -Row/Columns Range End: - -The row at which the import is going to end. Type a number or $ (dollar- -sign). 12 means the import stops at row 12 inclusively, $ means that all -rows/columns are read to the end. - - - - - -Prerequisites to consider - - -Comma-separated-value (*.csv): - -All rows have to have the same number of columns. That does not mean that -every cell has to be occupied by a number. Only the separator has to be -present: - - -2.3 , 4.4 , 7.6 , 9.5 -5.6 , 6.9 , , - -Strings or missing data (see above) are represented as Nan (not-a-number) -in the matrix. E.g.: - - -2.3 4.4 7.6 9.5 -5.6 6.9 Nan Nan - - - - -Text-based data (*.dat, *.txt): - -All rows have to have the same number of columns and should not contain -strings (text). Otherwise the data will be imported as a string matrix and -not a number matrix. - - -| 2.3 4.4 7.6 9.5 | -|  | -| 5.6 6.9 | - - - - - - - - - - - Examples - - - - - See also - - DI_readxls - DI_writecsv - csvRead - fscanfMat - - - - - Authors - - Hani A. Ibrahim - hani.ibrahim@gmx.de - - - + + + + + + + + DI_readcsv + DEPRECATED: Imports a CSV file (comma-separated-value) in a matrix variable interactively. + + + + + Calling Sequence + + [csvMat] = DI_readcsv() + [csvMat] = DI_readcsv(path) + [csvMat, exitID] = DI_readcsv() + [csvMat, exitID] = DI_readcsv(path) + + + + + + Parameters + + path: + a string, target path for the file selector (OPTIONAL) + csvMat: + a string, name of the matrix which stores the imported data + exitID: + an integer, exit codes, 0=OK, -1, -2, -3, -4=error codes, see below. + + + + + Description + +Read numerical data from a comma-separated-value (*.csv) or another text-based +data file (*.dat, *.txt) and stores it into a matrix variable interactively. + + +The following field delimiters are accepted: Comma, semicolon, space(s), +tabular(s). The decimal delimiter can be point or comma. + + + +Note that the file has to be correctly formated. All rows have to have the +same number of columns. + + + + +This function is DEPRECATED. Use DI_read instead! +To avoid breaking legal scripts, the code will +stay in the toolbox but will be removed from the documentation. + + + + + + +path: + +You can commit an optional path to the function. This is used to open +the file selector at the committed target path. If you omit it your home +directory is set as the target path. + + + +csvMat: + +This is the name of the matrix variable which will content the imported data +for further processing in Scilab's console or in a script. + + + +exitID: + +The exitID gives a feedback what happened inside the function. If +something went wrong csvMat is always [] (empty). To handle errors in a +script you can evaluate exitID's error codes (negative numbers): + + + 0: Everything is OK. Matrix csvMat was created +-1: User canceled file selection +-2: User canceled parameter dialog box +-3: Cannot read or interpret CSV file +-4: Cannot interpret file correctly - maybe header present + + + + + + +Import Parameter: + + + + + + + + + + + +Field Separator: + +This is the character which separates the fields and +numbers, resp. +In general CSV-files it is the comma (,), in European ones it is +often the semicolon (;). Sometimes it is a tabulator (tab). Text-based +data files has a space or spaces as delimiters. +E.g. to specify a tabulator as separator, type in the word +"tab", for a space separator the word "space" without quotes. + + + +Decimal separator: + +The character which indentifies the decimal place. In +general CSV files it is the point (.), in most European ones it is +the comma (,). + + + +Number of Header Lines to Skip: + +The number of lines to be ignored at the +beginning of the file. This is useful to skip table headers. + + + +Row/Columns Range Start: + +The row/column at which the import is going to start. Type a number. 1 means +import starts at row/column 1 inclusively. + + + +Row/Columns Range End: + +The row at which the import is going to end. Type a number or $ (dollar- +sign). 12 means the import stops at row 12 inclusively, $ means that all +rows/columns are read to the end. + + + + + +Prerequisites to consider + + +Comma-separated-value (*.csv): + +All rows have to have the same number of columns. That does not mean that +every cell has to be occupied by a number. Only the separator has to be +present: + + +2.3 , 4.4 , 7.6 , 9.5 +5.6 , 6.9 , , + +Strings or missing data (see above) are represented as Nan (not-a-number) +in the matrix. E.g.: + + +2.3 4.4 7.6 9.5 +5.6 6.9 Nan Nan + + + + +Text-based data (*.dat, *.txt): + +All rows have to have the same number of columns and should not contain +strings (text). Otherwise the data will be imported as a string matrix and +not a number matrix. + + +| 2.3 4.4 7.6 9.5 | +|  | +| 5.6 6.9 | + + + + + + + + + + + Examples + + + + + See also + + DI_read + DI_show + DI_writedat + csvRead + fscanfMat + + + + + Authors + + Hani A. Ibrahim - hani.ibrahim@gmx.de + + + diff --git a/help/en_US/DI_readxls.xml b/help/en_US/deprecated/DI_readxls.xml similarity index 89% rename from help/en_US/DI_readxls.xml rename to help/en_US/deprecated/DI_readxls.xml index 98aa0a6..c44e0df 100644 --- a/help/en_US/DI_readxls.xml +++ b/help/en_US/deprecated/DI_readxls.xml @@ -1,168 +1,169 @@ - - - - - - - - DI_readxls - Imports a binary Excel file (xls) in a matrix variable interactively - - - - - Calling Sequence - - [xlsMat] = DI_readxls() - [xlsMat] = DI_readxls(path) - [xlsMat, exitID] = DI_readxls() - [xlsMat, exitID] = DI_readxls(path) - - - - - - Parameters - - path: - a string, target path for the file selector (OPTIONAL) - xlsMat: - a string, name of the matrix which stores the imported data - exitID: - an integer, exit codes, 0=OK, -1, -2, -3=error codes, see below. - - - - - Description - -Read data from a binary Excel 95-2003 file (*.xls) and stores it into -a matrix variable interactively. - - - -DI_readxls does not handle data from XML-based Excel files (*.xlsx) of -Excel 2007 and higher! - - - - -DI_readxls handles numerical data only. Strings or missing data are imported -as Nan (Not-a-number, %nan). - - - - - -path: - -You can commit an optional path to the function. This is used to open -the file selector at the committed target path. If you omit it your home -directory is set as the target path. - - - -xlsMat: - -This is the name of the matrix variable which contents the imported data -for further processing in Scilab's console or in a script. - - - -exitID: - -The exitID gives a feedback what happened inside the function. If -something went wrong xlsMat is always [] (empty). To handle errors in a -script you can evaluate exitID's error codes (negative numbers): - - - 0: Everything is OK. Matrix xlsMat was created --1: User canceled file selection --2: User canceled parameter dialog box --3: Cannot read or interpret XLS file - - - - - - -Import Parameter: - - - - - - - - - - - -Sheet#: - -The number of the sheet of the Excel file you want to import from. The -names of the sheets are not evaluated. The 1st sheet is 1 the 2nd is 2 -independent of their names in Excel. - - - -Row/Columns Range Start: - -The row/column at which the import is going to start. Type a number. 1 means -import starts at row/column 1 inclusively. - - - -Row/Columns Range End: - -The row at which the import is going to end. Type a number or $ (dollar- -sign). 12 means the import stops at row 12 inclusively, $ means that all -rows/columns are read to the end. - - - - - - - - - - Examples - - - - - See also - - DI_readcsv - DI_writecsv - readxls - - - - - Authors - - Hani A. Ibrahim - hani.ibrahim@gmx.de - - - + + + + + + + + DI_readxls + DEPRECATED: Imports a binary Excel file (xls) in a matrix variable interactively. + + + + + Calling Sequence + + [xlsMat] = DI_readxls() + [xlsMat] = DI_readxls(path) + [xlsMat, exitID] = DI_readxls() + [xlsMat, exitID] = DI_readxls(path) + + + + + + Parameters + + path: + a string, target path for the file selector (OPTIONAL) + xlsMat: + a string, name of the matrix which stores the imported data + exitID: + an integer, exit codes, 0=OK, -1, -2, -3=error codes, see below. + + + + + Description + +Read data from a binary Excel 95-2003 file (*.xls) and stores it into +a matrix variable interactively. + + + +DI_readxls does not handle data from XML-based Excel files (*.xlsx) of +Excel 2007 and higher! + + + + +DI_readxls handles numerical data only. Strings or missing data are imported +as Nan (Not-a-number, %nan). + + + + + +path: + +You can commit an optional path to the function. This is used to open +the file selector at the committed target path. If you omit it your home +directory is set as the target path. + + + +xlsMat: + +This is the name of the matrix variable which contents the imported data +for further processing in Scilab's console or in a script. + + + +exitID: + +The exitID gives a feedback what happened inside the function. If +something went wrong xlsMat is always [] (empty). To handle errors in a +script you can evaluate exitID's error codes (negative numbers): + + + 0: Everything is OK. Matrix xlsMat was created +-1: User canceled file selection +-2: User canceled parameter dialog box +-3: Cannot read or interpret XLS file + + + + + + +Import Parameter: + + + + + + + + + + + +Sheet#: + +The number of the sheet of the Excel file you want to import from. The +names of the sheets are not evaluated. The 1st sheet is 1 the 2nd is 2 +independent of their names in Excel. + + + +Row/Columns Range Start: + +The row/column at which the import is going to start. Type a number. 1 means +import starts at row/column 1 inclusively. + + + +Row/Columns Range End: + +The row at which the import is going to end. Type a number or $ (dollar- +sign). 12 means the import stops at row 12 inclusively, $ means that all +rows/columns are read to the end. + + + + + + + + + + Examples + + + + + See also + + DI_read + DI_show + DI_writedat + readxls + + + + + Authors + + Hani A. Ibrahim - hani.ibrahim@gmx.de + + + diff --git a/help/en_US/DI_writecsv.xml b/help/en_US/deprecated/DI_writecsv.xml similarity index 85% rename from help/en_US/DI_writecsv.xml rename to help/en_US/deprecated/DI_writecsv.xml index 4cb5151..60cc7cc 100644 --- a/help/en_US/DI_writecsv.xml +++ b/help/en_US/deprecated/DI_writecsv.xml @@ -1,161 +1,169 @@ - - - - - - - - DI_writecsv - Exports numerical data stored in a matrix variable to a CSV file interactively - - - - - Calling Sequence - - [exitID] = DI_writecsv(csvMat) - [exitID] = DI_writecsv(csvMat, path) - - - - - - Parameters - - csvMat: - a string, name of the matrix variable you want to store in a file - path: - a string, target path for the file selector (OPTIONAL) - exitID: - an integer, exit codes, 0=OK, -1, -2, -3, -4=error codes, see below. - - - - - Description - -Write a Scilab matrix of doubles to a CSV or other text-based file interactively. - - - - -path: - -You can commit an optional path to the function. This is used to open -the file selector at the committed target path. If you omit it your home -directory is set as the target path. - - - -csvMat: - -This is the name of the matrix variable which contents the data you want -to export. - - - -exitID: - -The exitID gives a feedback what happened inside the function. If -something went wrong csvMat is always [] (empty). To handle errors in a -script you can evaluate exitID's error codes (negative numbers): - - - 0: Everything is OK. Matrix csvMat was created --1: User canceled file selection --2: User canceled parameter dialog box --3: Cannot write CSV file --4: No matrix variable name specified - - - - - - -Export Parameter: - - - - - - - - - - - -Field Separator: - -This is the character which separates the fields and -numbers, resp. -In general CSV-files it is the comma (,), in European ones it is -often the semicolon (;). Sometimes it is a tabulator (tab) or a space -(space). E.g. to specify a tabulator as the separator, type in the word -"tab" without quotes. - -If you select space just ONE space character delimits the data. - - - -Decimal separator: - -The character which indentifies the decimal place. In -general CSV files it is the point (.), in most European ones it is -the comma (,). - - - -Comment header: - -Place a comment in the first line/row of the file. This is useful to -describe your data. Just one line is supported (OPTIONAL). - - - - - - - - - - Examples - - - - - See also - - DI_readcsv - DI_readxls - DI_read - csvwrite - csvRead - fscanfMat - - - - - Authors - - Hani A. Ibrahim - hani.ibrahim@gmx.de - - - + + + + + + + + DI_writecsv + DEPRECATED: Exports numerical data stored in a matrix variable to a CSV file interactively. + + + + + Calling Sequence + + [exitID] = DI_writecsv(csvMat) + [exitID] = DI_writecsv(csvMat, path) + + + + + + Parameters + + csvMat: + a string, name of the matrix variable you want to store in a file + path: + a string, target path for the file selector (OPTIONAL) + exitID: + an integer, exit codes, 0=OK, -1, -2, -3, -4=error codes, see below. + + + + + Description + +Write a Scilab matrix of doubles to a CSV or other text-based file interactively. + + + +This function is DEPRECATED. Use DI_writedat instead! +To avoid breaking legal scripts, the code will +stay in the toolbox but will be removed from the documentation. + + + + + + +path: + +You can commit an optional path to the function. This is used to open +the file selector at the committed target path. If you omit it your home +directory is set as the target path. + + + +csvMat: + +This is the name of the matrix variable which contents the data you want +to export. + + + +exitID: + +The exitID gives a feedback what happened inside the function. If +something went wrong csvMat is always [] (empty). To handle errors in a +script you can evaluate exitID's error codes (negative numbers): + + + 0: Everything is OK. Matrix csvMat was created +-1: User canceled file selection +-2: User canceled parameter dialog box +-3: Cannot write CSV file +-4: No matrix variable name specified + + + + + + +Export Parameter: + + + + + + + + + + + +Field Separator: + +This is the character which separates the fields and +numbers, resp. +In general CSV-files it is the comma (,), in European ones it is +often the semicolon (;). Sometimes it is a tabulator (tab) or a space +(space). E.g. to specify a tabulator as the separator, type in the word +"tab" without quotes. + +If you select space just ONE space character delimits the data. + + + +Decimal separator: + +The character which identifies the decimal place. In +general CSV files it is the point (.), in most European ones it is +the comma (,). + + + +Comment header: + +Place a comment in the first line/row of the file. This is useful to +describe your data. Just one line is supported (OPTIONAL). + + + + + + + + + + Examples + + + + + See also + + DI_writedat + DI_show + DI_read + csvWrite + csvRead + fscanfMat + + + + + Authors + + Hani A. Ibrahim - hani.ibrahim@gmx.de + + + diff --git a/help/en_US/update_help.sce b/help/en_US/update_help.sce index 1465481..394679d 100644 --- a/help/en_US/update_help.sce +++ b/help/en_US/update_help.sce @@ -5,10 +5,9 @@ mprintf("Working dir = %s\n",cwd); mprintf("Updating root\n"); helpdir = fullfile(cwd); funmat = [ - "DI_readcsv" - "DI_readxls" - "DI_writecsv" "DI_read" + "DI_show" + "DI_writedat" ]; macrosdir = cwd +"../../macros"; demosdir = []; @@ -25,4 +24,16 @@ macrosdir = cwd +"../../macros"; demosdir = []; modulename = "dataint"; helptbx_helpupdate ( funmat , helpdir , macrosdir , demosdir , modulename , %t ); - +// ======================================================================================== +// Generate the deprecated help +mprintf("Updating deprecated\n"); +helpdir = fullfile(cwd,"deprecated"); +funmat = [ + "DI_readcsv" + "DI_readxls" + "DI_writecsv" + ]; +macrosdir = cwd +"../../macros"; +demosdir = []; +modulename = "dataint"; +helptbx_helpupdate ( funmat , helpdir , macrosdir , demosdir , modulename , %t ); diff --git a/macros/DI_read.sci b/macros/DI_read.sci index 71ca8ef..0a2429e 100644 --- a/macros/DI_read.sci +++ b/macros/DI_read.sci @@ -14,7 +14,7 @@ // this program; if not, see . function [dataMat, exitID] = DI_read(path) - // Imports a data file (comma-separated-value, Excel-xls, text-based) in a matrix variable interactively. Combined functionality of DI_readcsv() and DI_readxls(). + // Imports a data file (comma-separated-value, Excel-xls, text-based) in a matrix variable interactively. // // Calling Sequence // [dataMat] = DI_read() @@ -104,7 +104,7 @@ function [dataMat, exitID] = DI_read(path) // // Decimal separator: // - // The character which indentifies the decimal place. In + // The character which identifies the decimal place. In // general CSV files it is the point (.), in most European ones it is // the comma (,). // @@ -223,15 +223,14 @@ function [dataMat, exitID] = DI_read(path) // Examples // [mat, id] = DI_read(fullfile(DI_getpath(), "demos")); // Read CSV file // disp("Exit-Code: "+string(id),mat,"data:") // Displays imported data "mat" and exit code "id" - // if id == 0 then // Plot data if import was sucessful - // plot(mat(:,1),mat(:,14),".-") + // if id == 0 then // Plot data if import was successful + // plot(mat(:,1),mat(:,14),"-") // xtitle("Central England Temperature","Year","Mean Temperature [°C]") // end // // See also - // DI_readxls - // DI_readcsv - // DI_writecsv + // DI_show + // DI_writedat // csvRead // readxls // fscanfMat diff --git a/macros/DI_readcsv.sci b/macros/DI_readcsv.sci index 901aef5..eb0fa10 100644 --- a/macros/DI_readcsv.sci +++ b/macros/DI_readcsv.sci @@ -14,7 +14,7 @@ // this program; if not, see . function [csvMat, exitID] = DI_readcsv(path) - // Imports a CSV file (comma-separated-value) in a matrix variable interactively + // DEPRECATED: Imports a CSV file (comma-separated-value) in a matrix variable interactively. // // Calling Sequence // [csvMat] = DI_readcsv() @@ -39,6 +39,13 @@ function [csvMat, exitID] = DI_readcsv(path) // same number of columns. // // + // + // This function is DEPRECATED. Use DI_read instead! + // To avoid breaking legal scripts, the code will + // stay in the toolbox but will be removed from the documentation. + // + // + // // // // path: @@ -77,7 +84,7 @@ function [csvMat, exitID] = DI_readcsv(path) // // // - // + // // // // @@ -167,14 +174,15 @@ function [csvMat, exitID] = DI_readcsv(path) // Examples // [mat, id] = DI_readcsv(fullfile(DI_getpath(), "demos")); // Read CSV file // disp("Exit-ID: "+string(id),mat,"data:") // Displays imported data "mat" and exit code "id" - // if id == 0 then // Plot data if import was sucessful - // plot(mat(:,1),mat(:,14),".-") + // if id == 0 then // Plot data if import was successful + // plot(mat(:,1),mat(:,14),"-") // xtitle("Central England Temperature","Year","Mean Temperature [°C]") // end // // See also - // DI_readxls - // DI_writecsv + // DI_read + // DI_show + // DI_writedat // csvRead // fscanfMat // diff --git a/macros/DI_readxls.sci b/macros/DI_readxls.sci index 123a67d..9649dda 100644 --- a/macros/DI_readxls.sci +++ b/macros/DI_readxls.sci @@ -14,7 +14,7 @@ // this program; if not, see . function [xlsMat, exitID] = DI_readxls(path) - // Imports a binary Excel file (xls) in a matrix variable interactively + // DEPRECATED: Imports a binary Excel file (xls) in a matrix variable interactively. // // Calling Sequence // [xlsMat] = DI_readxls() @@ -78,7 +78,7 @@ function [xlsMat, exitID] = DI_readxls(path) // // // - // + // // // // @@ -111,14 +111,15 @@ function [xlsMat, exitID] = DI_readxls(path) // Examples // [mat, id] = DI_readxls(fullfile(DI_getpath(), "demos")) // Read XLS file // disp("Exit-ID: "+string(id),mat,"data:") // Displays imported data "mat" and exit code "id" - // if id == 0 then // Plot data if import was sucessful - // plot(mat(:,1),mat(:,14),".-") + // if id == 0 then // Plot data if import was successful + // plot(mat(:,1),mat(:,14),"-") // xtitle("Central England Temperature","Year","Mean Temperature [°C]") // end // // See also - // DI_readcsv - // DI_writecsv + // DI_read + // DI_show + // DI_writedat // readxls // // Authors diff --git a/macros/DI_show.sci b/macros/DI_show.sci index 6f2978a..c3aef79 100644 --- a/macros/DI_show.sci +++ b/macros/DI_show.sci @@ -1,4 +1,4 @@ -// Copyright (C) 2019 Hani Andreas Ibrahim +2// Copyright (C) 2019 Hani Andreas Ibrahim // // This program is free software; you can redistribute it and/or modify it under // the terms of the GNU General Public License as published by the Free Software @@ -14,9 +14,7 @@ // this program; if not, see . function [dataMat, exitID] = DI_show(path, n) - // Read the first 25 or an arbitrary number of lines of a text data file, - // displays them in the console and invoke a reading procedure after, if desired. - // + // Read and display the first 25 or an arbitrary number of lines of a text data file. // // Calling Sequence // [dataMat] = DI_show() @@ -133,7 +131,7 @@ function [dataMat, exitID] = DI_show(path, n) // // Decimal separator: // - // The character which indentifies the decimal place. In + // The character which identifies the decimal place. In // general CSV files it is the point (.), in most European ones it is // the comma (,). // @@ -210,12 +208,6 @@ function [dataMat, exitID] = DI_show(path, n) // else // mprintf("Reading of data not confirmed\n") // end - // abort; - // // Further examples (will not be executed by "play") - // DI_show(fullfile(DI_getpath(), "demos")); - // DI_show(pwd()); // Opens current directory and read 25 lines (default) - // DI_show(,10); // Opens home directory (default) and reads 10 lines - // DI_show(); // Opens home directory (default) and reads 25 lines (default) // // See also // DI_read @@ -298,7 +290,7 @@ function [dataMat, exitID] = DI_show(path, n) // Display rows of the file ------------------------------------------------ // Prevent the display loop from overflowing if n > rows - lrows = size(rows)(1); // No. of rows + lrows = size(rows,1); // No. of rows if n > lrows then n = lrows end diff --git a/macros/DI_writecsv.sci b/macros/DI_writecsv.sci index 2d1813d..f307b89 100644 --- a/macros/DI_writecsv.sci +++ b/macros/DI_writecsv.sci @@ -14,7 +14,7 @@ // this program; if not, see . function [exitID] = DI_writecsv(csvMat, path) - // Exports numerical data stored in a matrix variable to a CSV file interactively + // DEPRECATED: Exports numerical data stored in a matrix variable to a CSV file interactively. // // Calling Sequence // [exitID] = DI_writecsv(csvMat) @@ -27,7 +27,14 @@ function [exitID] = DI_writecsv(csvMat, path) // // Description // Write a Scilab matrix of doubles to a CSV or other text-based file interactively. - // + // + // + // This function is DEPRECATED. Use DI_writedat instead! + // To avoid breaking legal scripts, the code will + // stay in the toolbox but will be removed from the documentation. + // + // + // // // // path: @@ -66,7 +73,7 @@ function [exitID] = DI_writecsv(csvMat, path) // // // - // + // // // // @@ -87,7 +94,7 @@ function [exitID] = DI_writecsv(csvMat, path) // // Decimal separator: // - // The character which indentifies the decimal place. In + // The character which identifies the decimal place. In // general CSV files it is the point (.), in most European ones it is // the comma (,). // @@ -103,16 +110,16 @@ function [exitID] = DI_writecsv(csvMat, path) // // Examples // dat = [32.4 34.6 36.5 32.6 ; 102.4 105.0 104.8 102.6]; - // // Open the file selector at the currend directory + // // Open the file selector at the current directory // // and write matrix "dat" to the specified csv-file // [exitID] = DI_writecsv("dat", pwd()); // disp("Exit-ID: " + string(exitID)) // Displays exit code // // See also - // DI_readcsv - // DI_readxls + // DI_writedat + // DI_show // DI_read - // csvwrite + // csvWrite // csvRead // fscanfMat // diff --git a/macros/DI_writedat.sci b/macros/DI_writedat.sci index 6d708a3..bdf20af 100644 --- a/macros/DI_writedat.sci +++ b/macros/DI_writedat.sci @@ -14,7 +14,7 @@ // this program; if not, see . function [exitID] = DI_writedat(datMat, path) - // Exports numerical data stored in a matrix variable to a text data file interactively + // Exports numerical data stored in a matrix variable to a text data file interactively. // // Calling Sequence // [exitID] = DI_writedat(datMat) @@ -27,7 +27,7 @@ function [exitID] = DI_writedat(datMat, path) // // Description // Write a Scilab matrix of doubles to a CSV or other text-based file interactively. - // If you do not specify a file-extention explicitely, ".txt" is added automatically. + // If you do not specify a file-extension explicitly, ".txt" is added automatically. // // // @@ -88,7 +88,7 @@ function [exitID] = DI_writedat(datMat, path) // // Decimal separator: // - // The character which indentifies the decimal place. In + // The character which identifies the decimal place. In // general CSV files it is the point (.), in most European ones it is // the comma (,). // @@ -104,14 +104,13 @@ function [exitID] = DI_writedat(datMat, path) // // Examples // dat = [32.4 34.6 36.5 32.6 ; 102.4 105.0 104.8 102.6]; - // // Open the file selector at the currend directory + // // Open the file selector at the current directory // // and write matrix "dat" to the specified csv-file // [exitID] = DI_writedat(dat, pwd()); // disp("Exit-ID: " + string(exitID)) // Displays exit code // // See also - // DI_readcsv - // DI_readxls + // DI_show // DI_read // csvWrite // csvRead diff --git a/readme.txt b/readme.txt index f5225be..f62259d 100644 --- a/readme.txt +++ b/readme.txt @@ -1,21 +1,21 @@ dataINT - Toolbox for INTERACTIVE reading and writing of csv- and xls-datafiles ============================================================================== -dataINT offers functions for convienient interactice im-/export of data files, -as comma-separated-value- (*.csv, *.dat, *.txt) and binary Excel files (*.xls) -to or from a Scilab matrix. +dataINT offers functions for convenient, interactive im-/export of test-based +data files (*.csv, *.dat, *.txt) to or from a Scilab matrix or from a binary +Excel files (*.xls), respectively. -Parameters, to specify the im-/export, can convieniently entered in a dialog +Parameters, to specify the im-/export, can conveniently entered in a dialog box and the file selection is done by the platform-specific file selection dialog. You can specify the following im-/export parameters: - Field separator (comma, semicolon, tab, space) - Decimal separator (comma, point) -- Rows and Colums you want to import (DI_readcsv, DI_readxls only) -- Sheet you want to import (DI_readxls only) -- Number of lines to skip, e.g. header line(s) (DI_readcsv, DI_readxls only) -- Comment header line to describe your data (DI_writecsv only) +- Rows and columns you want to import +- Sheet you want to import +- Number of lines to skip, e.g. header line(s) +- Comment header line to describe your data IMPORTANT: dataINT does not handle data from XML-based Excel files (.xlsx)! NOTE: dataINT handles doubles only. @@ -26,21 +26,27 @@ Scilab's console. FUNCTIONS: -* DI_readcsv - Read comma-separated value files (*.csv, *.dat, *.txt) interactively. -* DI_readxls - Read binary Excel files (*.xls) interactively. * DI_read Combines functionality of DI_readcsv and DI_readxls in one function -* DI_writecsv +* DI_show + Read the first 25 or an arbitrary number of lines of a text data file, + displays them in the console and invoke the reading procedure after, if + desired. +* DI_writedat Write comma-separated value files (*.csv, *.dat, *.txt) interactively. -dataINT is available for Scilab 5.5.x and Scilab 6.0.x and cross-platform. +dataINT is available for Scilab 5.5.x, 6.0.x and 6.1.x. Furthermore +dataINT is cross-platform. ------------------------------------------------------------------------------- CHANGELOG: +1.2.0 +- DI_show function added +- DI_writedat replaces DI_writecsv +- Deprecation of DI_readcsv and DI_readxls. Successor of both is DI_read + 1.1.1 - Fix decimal-comma-bug when reading/parsing space separated text files with decimal commas @@ -58,10 +64,10 @@ CHANGELOG: ------------------------------------------------------------------------------- COMPATIBILITY -Can be build, installed and run with Scilab 5.5.x and 6.0.x, cross-platform. +Can be build, installed and run with Scilab 5.5.x, 6.0.x and 6.1.x, cross-platform. BUILD: - * Decompress the source distribution file: dataint-x.x.x_5.5_6.0_src.zip + * Decompress the source distribution file: dataint-x.x.x_5.5_6.0_6.1_src.zip * Start Scilab and move to the folder where "builder.sce" resides * Execute builder.sce: exec("builder.sce",-1) * For temporary use, execute loader.sce. (Does not resist "clear" command)