1.10.1 Importing Data


The Worksheet and MatrixLayer classes are derived from the Datasheet class. The Datasheet class has a method named ImportASCII. The ImportASCII method is used for importing ASCII data files. There are also ImportExcel and ImportSPC methods for importing Microsoft Excel and spectroscopic data files, respectively.

Import ASCII Data File into Worksheet

The first example will import an ASCII data file into the active worksheet of the active workbook. It will first call the AscImpReadFileStruct global function to detect the file's format. The format information is stored in an ASCIMP structure. The structure will then be passed to the ImportASCII method to do the actual importing.

string strFile = "D:\\data.dat"; // some data file name
ASCIMP	ai;
if(0 == AscImpReadFileStruct(strFile, &ai) )
{
    // In this example we will disable the ASCII import progress
    // bar by setting the LabTalk System Variable @NPO to zero.
    // This is optional and is done here to show it is possible.
    // The LTVarTempChange class makes setting and restoring a
    // LabTalk variable easy.  See the Accessing LabTalk section
    // for more details about the LTVarTempChange class.
    LTVarTempChange progressBar("@NPO", 0); // 0 = disable progress bar

    // Get active worksheet from active work book.
    Worksheet wks = Project.ActiveLayer();

    if(0 == wks.ImportASCII(strFile, ai))
        out_str("Import data successful.");
}

The next example will also import an ASCII data file into a worksheet but it will also obtain additional information about each column from the file, and set up the worksheet columns.

// Prompt user with a File Open dialog to choose a file to import.
string 	strFile = GetOpenBox("*.dat");
if( strFile.IsEmpty() )
    return; // User canceled or error

ASCIMP	ai;
if( 0 == AscImpReadFileStruct(strFile, &ai) )
{
    ai.iAutoSubHeaderLines = 0; // Disable auto detect sub header 

    // 1, LongName 
    // 2. Units	
    // 3. Expanded Description(User defined)	
    // 4. Type Indication(User defined)
    ai.iSubHeaderLines = 4; 

    // When iAutoSubHeaderLines is false(0), the beginning index of ai.nLongName, 
    // ai.nUnits and ai.nFirstUserParams are from main header
    ai.nLongNames = ai.iHeaderLines; 
    ai.nUnits = ai.iHeaderLines + 1;  

    // Set the index for the first user params
    ai.nFirstUserParams = ai.iHeaderLines + 2; 
    ai.nNumUserParams = 2; // Set the number of user params		

    // Not set any header to Comments label
    ai.iMaxLabels = 0; 

    // Get active worksheet from active work book.
    Worksheet wks = Project.ActiveLayer();

    if( 0 == wks.ImportASCII(strFile, ai) ) // Return 0 for no error
    {
        // The names of the user parameter labels
        vector<string> vsUserLabels = {"Expanded Description", "Type Indication"};

        // Set user parameter labels to specified names
        Grid grid;
        grid.Attach(wks);
        grid.SetUserDefinedLabelNames(vsUserLabels);

        wks.AutoSize(); // Resize column widths to best fit their contents.
    }
}

Import ASCII Data File into Matrix Sheet

Importing data into a matrix sheet is very similar to importing into a worksheet. This example is almost identical to the first worksheet example. The only difference is we get the active matrix sheet from the active matrix book using the MatrixLayer class instead of the Worksheet class.

string strFile = "D:\\someData.dat";
ASCIMP ai;
if( 0 == AscImpReadFileStruct(strFile, &ai) )
{
    MatrixLayer ml = Project.ActiveLayer();	
    if( 0 == ml.ImportASCII(strFile, ai) )
        out_str("Data imported successfully.");
}

Import Data Using an Import Filter

Functions for importing files are declared in the OriginC\Originlab\FileImport.h file. These functions are also documented in the Origin C Language Reference help file.

Prior to calling the import file functions, you need to first programmatically load and compile FileImport.c. This can be done from script using the command:

run.LoadOC(Originlab\FileImport.c, 16);
// Option 16 ensures that all dependent Origin C files are loaded,
// by scanning for the corresponding .h in FileImport.c

The following example shows importing data with a filter file.

#include <..\Originlab\FileImport.h>
void import_with_filter_file()
{
    Page pg = Project.Pages(); // Active Page
 
    // Get page book name
    string strPageName = pg.GetName();
 
    // Get page active layer index
    int nIndexLayer = pg.Layers().GetIndex();
 
    // Get Origin sample folder
    string strPath = GetAppPath(TRUE) + "Samples\\Signal Processing\\";
 
    // specify .oif filter name
    string strFilterName = "TR Data Files";
 
    import_file(strPageName, nIndexLayer, strPath + "TR2MM.dat", strFilterName);
}

Sometimes the existing filter might need to be modified to meet the requirements of the data format, so you need to load the filter from the file and configure it. See the following case:

#include <..\Originlab\FileImport.h>
void    config_filter_tree()
{
    string strFile = GetAppPath(1) + "Samples\\Curve Fitting\\Step01.dat";
    if( !strFile.IsFile() )
        return;  
 
    // load filter to tree
    Tree trFilter;    
    string strFilterName = "ASCII";
    int nLocation = 1; // build-in Filters folder
    Worksheet wks;
    wks.Create("origin");
    WorksheetPage wp = wks.GetPage();
    string strPageName = wp.GetName();
    int nRet = load_import_filter(strFilterName, strFile,
                                strPageName, nLocation, trFilter);
    if( 0 != nRet )
        out_str("Failed to load import filter"); 
    
    // update filter tree
    trFilter.iRenameCols.nVal = 0; // 0 to keep default column name, 1 to rename column 
    
    // import data file with filter tree. 
    // import_files function supports import multiple files one time.
    vector<string> vsDataFileName;
    vsDataFileName.Add(strFile);    
    nRet = import_files(vsDataFileName, strPageName, wks.GetIndex(), trFilter);	
    if( 0 != nRet )
        out_str("Failed to import file");
}

Import Files with Import Wizard

There are times when the data files are neither ASCII nor simple binary files or there is no existing filter for importing a data file, in these cases you can use Origin C and impFile X-Functions to import the files with the Import Wizard.

The Origin C function should have either of the following prototypes:

int YourFunctionName(Page& pgTarget, TreeNode& trFilter, LPCSTR lpcszFile, int nFile)

where:

  • pgTarget: A reference to a Page object of type worksheet or Matrix. This would be what you defined in your filter or on the Source page of the Import Wizard, as the target window.
  • trFilter: A reference to a TreeNode object that holds all the filter settings from your filter file, or from your wizard specifications, in a tree structure.
  • lpcszFile: The full path and name of the file that is being imported.
  • nFile: The file index number in an ordered sequence of imported files (e.g. If you import n files, your function gets called n times, and nFile is the file count for the file being processed).

Or

int YourFunctionName(Layer& lyTarget, TreeNode& trFilter, LPCSTR lpcszFile, int nFile)

where:

  • lyTarget: A reference to a Layer object of type worksheet or Matrix. This would be what you defined in your filter or on the Source page of the Import Wizard, as the target window.
  • trFilter: A reference to a TreeNode object that holds all the filter settings from your filter file, or from your wizard specifications, in a tree structure.
  • lpcszFile: The full path and name of the file that is being imported.
  • nFile: The file index number in an ordered sequence of imported files (e.g. If you import n files, your function gets called n times, and nFile is the file count for the file being processed).

See an example in the \Samples\Import and Export\User Defined folder, found in the Origin installation folder.

Note: The target window template named on the first page of the Import Wizard (Source page) is only used when creating new windows (as would happen under some conditions during drag-and-drop importing). When choosing File: Import, if your active window is consistent with your import filter's Target Window specification, no new window is created and a reference to the page object for the active window is passed to your function. If the active window is of a different type, a new window is created using the specified template, and the page reference to this new window is passed.


Variable Extraction in Import Wizard

When importing ASCII files with the Import Wizard, you can extract variables from the file headers using user-defined Origin C functions.

Your custom Origin C function should have the following prototype:

int FuncName(StringArray& saVarNames, StringArray& saVarValues, const StringArray& saHdrLines, const TreeNode &trFilter);

where:

  • saVarNames: An string array where the user should put the variable names.
  • saVarValues: An string array where the user should put the variable values.
  • saHdrLines: A reference to an string array that contains the header lines. Note that the Origin C function does not need to read the data file because the header lines are automatically passed into the function.
  • trFilter: A reference to a TreeNode object that holds all the filter settings from your filter file, or from your wizard specifications, in a tree structure.