1<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 3//EN"> 2<HTML><HEAD> 3 <TITLE>User's Reference - Import</TITLE> 4 <META HTTP-EQUIV="keywords" CONTENT="GRAPHICS VISUALIZATION VISUAL PROGRAM DATA 5MINING"> 6 <meta http-equiv="content-type" content="text/html;charset=ISO-8859-1"> 7</HEAD><BODY BGCOLOR="#FFFFFF" link="#00004b" vlink="#4b004b"> 8 <TABLE width=510 border=0 cellpadding=0 cellspacing=0> 9 <TR> 10 <TD><IMG src="../images/spacer.gif" width=80 height=1></TD> 11 <TD><IMG src="../images/spacer.gif" width=49 height=1></TD> 12 <TD><IMG src="../images/spacer.gif" width=24 height=1></TD> 13 <TD><IMG src="../images/spacer.gif" width=100 height=1></TD> 14 <TD><IMG src="../images/spacer.gif" width=3 height=1></TD> 15 <TD><IMG src="../images/spacer.gif" width=127 height=1></TD> 16 <TD><IMG src="../images/spacer.gif" width=6 height=1></TD> 17 <TD><IMG src="../images/spacer.gif" width=50 height=1></TD> 18 <TD><IMG src="../images/spacer.gif" width=71 height=1></TD> 19 </TR> 20 <TR> 21 <TD colspan=9><IMG src="../images/flcgh_01.gif" width=510 height=24 alt="OpenDX - Documentation"></TD> 22 </TR> 23 <TR> 24 <TD colspan=2><A href="../allguide.htm"><IMG src="../images/flcgh_02.gif" width=129 height=25 border="0" alt="Full Contents"></A></TD> 25 <TD colspan=3><A href="../qikguide.htm"><IMG src="../images/flcgh_03.gif" width=127 height=25 border="0" alt="QuickStart Guide"></A></TD> 26 <TD><A href="../usrguide.htm"><IMG src="../images/flcgh_04.gif" width=127 height=25 border="0" alt="User's Guide"></A></TD> 27 <TD colspan=3><B><A href="../refguide.htm"><IMG src="../images/flcgh_05d.gif" width=127 height=25 border="0" alt="User's Reference"></A></B></TD> 28 </TR> 29 <TR> 30 <TD><A href="refgu072.htm"><IMG src="../images/flcgh_06.gif" width=80 height=17 border="0" alt="Previous Page"></A></TD> 31 <TD colspan=2><A href="refgu074.htm"><IMG src="../images/flcgh_07.gif" width=73 height=17 border="0" alt="Next Page"></A></TD> 32 <TD><A href="../refguide.htm"><IMG src="../images/flcgh_08.gif" width=100 height=17 border="0" alt="Table of Contents"></A></TD> 33 <TD colspan=3><A href="refgu009.htm"><IMG src="../images/flcgh_09.gif" width=136 height=17 border="0" alt="Partial Table of Contents"></A></TD> 34 <TD><A href="refgu175.htm"><IMG src="../images/flcgh_10.gif" width=50 height=17 border="0" alt="Index"></A></TD> 35 <TD><A href="../srchindx.htm"><IMG src="../images/flcgh_11.gif" width=71 height=17 border="0" alt="Search"></A></TD> 36 </TR> 37 </TABLE> 38 <H3><A name="HDRIMPORT" ></A>Import</H3> 39 <A NAME="IDX545"></A><A NAME="IDX546"></A> 40<P><STRONG>Category</STRONG> 41<P> 42<A HREF="refgu008.htm#HDRCATIAE">Import and Export</A> 43<P><STRONG>Function</STRONG> 44<P> 45Reads an external data file. 46<P><STRONG>Syntax</STRONG> 47<PRE> 48<STRONG>data</STRONG> = Import(<STRONG>name, variable, format, start, end, delta</STRONG>); 49</PRE> 50<P><STRONG>Inputs</STRONG> 51<BR> 52<TABLE BORDER> 53<TR> 54<TH ALIGN="LEFT" VALIGN="TOP" WIDTH="20%">Name 55</TH><TH ALIGN="LEFT" VALIGN="TOP" WIDTH="20%">Type 56</TH><TH ALIGN="LEFT" VALIGN="TOP" WIDTH="20%">Default 57</TH><TH ALIGN="LEFT" VALIGN="TOP" WIDTH="40%">Description 58</TH></TR><TR> 59<TD ALIGN="LEFT" VALIGN="TOP" WIDTH="20%"><TT><STRONG>name</STRONG></TT> 60</TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="20%">string 61</TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="20%">none 62</TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="40%">name of file containing data to 63be read, or "!command" 64</TD></TR><TR> 65<TD ALIGN="LEFT" VALIGN="TOP" WIDTH="20%"><TT><STRONG>variable</STRONG></TT> 66</TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="20%">string or string list 67</TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="20%">format dependent 68</TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="40%">variable to be read 69</TD></TR><TR> 70<TD ALIGN="LEFT" VALIGN="TOP" WIDTH="20%"><TT><STRONG>format</STRONG></TT> 71</TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="20%">string 72</TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="20%">file extension or content 73</TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="40%">"dx," 74"general," 75"netcdf," 76"CDF," 77"hdf," 78"cm" 79</TD></TR><TR> 80<TD ALIGN="LEFT" VALIGN="TOP" WIDTH="20%"><TT><STRONG>start</STRONG></TT> 81</TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="20%">integer 82</TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="20%">first frame 83</TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="40%">first data frame to be imported 84</TD></TR><TR> 85<TD ALIGN="LEFT" VALIGN="TOP" WIDTH="20%"><TT><STRONG>end</STRONG></TT> 86</TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="20%">integer 87</TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="20%">last frame 88</TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="40%">last data frame to be imported 89</TD></TR><TR> 90<TD ALIGN="LEFT" VALIGN="TOP" WIDTH="20%"><TT><STRONG>delta</STRONG></TT> 91</TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="20%">integer 92</TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="20%">1 93</TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="40%">increment between frames 94</TD></TR></TABLE> 95<P><STRONG>Outputs</STRONG> 96<BR> 97<TABLE BORDER> 98<TR> 99<TH ALIGN="LEFT" VALIGN="TOP" WIDTH="25%">Name 100</TH><TH ALIGN="LEFT" VALIGN="TOP" WIDTH="25%">Type 101</TH><TH ALIGN="LEFT" VALIGN="TOP" WIDTH="50%">Description 102</TH></TR><TR> 103<TD ALIGN="LEFT" VALIGN="TOP" WIDTH="25%"><TT><STRONG>data</STRONG></TT> 104</TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="25%">object 105</TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="50%">object containing requested 106variables 107</TD></TR></TABLE> 108<P><STRONG>Functional Details</STRONG> 109<P> 110From an external data file this modules creates Data Explorer objects that can 111be processed by other modules. 112<TABLE CELLPADDING="3"> 113<TR VALIGN="TOP"><TD><P><B><TT><STRONG>name</STRONG></TT> 114</B></TD><TD><P>is the name of the data file being imported. 115If the parameter specifies an absolute path name, the system attempts 116to open the file. 117Otherwise, it first searches the current directory (i.e., the directory 118from which Data Explorer was invoked) and then, if necessary, the directories 119specified by the environment variable DXDATA (see <A 120HREF="usrgu073.htm#HDRENVVAR">C.1 , "Environment Variables"</A> 121in <I>IBM Visualization Data Explorer User's Guide</I>). 122<P><B>Note: </B>This parameter can also specify an external filter (see 123<A HREF="#SPTEXTFLT">External filters</A>). 124<P> 125If <TT><STRONG>name</STRONG></TT> contains a series, the parameters 126<TT><STRONG>start</STRONG></TT>, <TT><STRONG>end</STRONG></TT>, and 127<TT><STRONG>delta</STRONG></TT> can be used to import a 128portion of the data (see parameter 129descriptions below). 130</TD></TR><TR VALIGN="TOP"><TD><P><B><TT><STRONG>variable</STRONG></TT> 131</B></TD><TD><P>specifies the variable(s) to be imported. 132</TD></TR><TR VALIGN="TOP"><TD><P><B><TT><STRONG>format</STRONG></TT> 133</B></TD><TD><P>specifies the format of the data to be imported. 134Valid format names are: 135"dx," 136"general," 137"netcdf," 138"CDF," 139"hdf," and 140"cm." 141These keywords can also be used as extensions on 142file names. 143</TD></TR><TR VALIGN="TOP"><TD><P><B><TT><STRONG>start</STRONG></TT> 144 and 145<TT><STRONG>end</STRONG></TT> 146</B></TD><TD><P>specify the first and last data frame to be imported from a data 147file containing a series. 148</TD></TR><TR VALIGN="TOP"><TD><P><B><TT><STRONG>delta</STRONG></TT> 149</B></TD><TD><P>specifies the increment in counting the data frames in the range 150from <TT><STRONG>start</STRONG></TT> to <TT><STRONG>end</STRONG></TT>. 151For example, if the first and last frames are 10 and 20 respectively, 152and <TT><STRONG>delta</STRONG></TT> = 2, the output 153<TT><STRONG>data</STRONG></TT> 154is a series group with six members (frames 10, 12, 14,...). 155</TD></TR></TABLE> 156<TABLE BORDER WIDTH="100%"><TR><TH ALIGN="LEFT">For Future 157Reference</TH><TR><TD> 158<P> 159If the data set being imported is changed (e.g., by editing) during a 160Data Explorer session, and if the cache is enabled (the default condition), 161it may be necessary to reinitialize the Data Explorer executive to 162access the new data. 163To do so, select <TT><STRONG>Reset Server</STRONG></TT> in the 164<TT><STRONG>Connections</STRONG></TT> pull-down menu of 165the VPE window. 166<P> 167Resetting the server flushes the executive cache. 168The next time the visual program is invoked, the entire network executes 169(not just the portions affected by changes) and Import will 170reaccess the data set. 171<P> 172Specifying that the module's output not be cached has the same 173effect. 174Select the appropriate option in: 175<UL COMPACT> 176<LI>the "Cache" option menu of the module's configuration 177dialog box, <I>or</I> 178<LI>the "Set Output Cacheability" option menu in the 179<TT><STRONG>Edit</STRONG></TT> pull-down menu. 180<P> 181Note that it may be necessary to apply the same restriction to any 182module downstream from Import. 183<P> 184To specify that <I>no</I> outputs are to be cached, use the 185<TT><STRONG>-cache off</STRONG></TT> option when starting Data Explorer. 186</UL> 187</TD></TR></TABLE> 188<P> 189<TT><STRONG>Data Explorer format files.</STRONG></TT> A Data Explorer data file consists of one or more header and data sections that describe the structure and values of user data. The header section is a text description of one or more Data Explorer objects, and the data section is either a text or binary representation of the data values. Non-binary data in data files is limited to a 4K line limit. <P> 190If <TT><STRONG>variable</STRONG></TT> specifies more than one object, the 191module creates a group and each object is added to the group 192by name. 193If <TT><STRONG>variable</STRONG></TT> is not specified, the default object 194is imported. 195This object can be specified with the <TT><STRONG>default</STRONG></TT> 196keyword in the Data Explorer file format 197(see <A HREF="usrgu068.htm#HDREDF">B.2 , "Data Explorer Native Files"</A> in 198<I>IBM Visualization Data Explorer User's Guide</I>). 199If it is not specified, the default object is the last object defined in 200the data file. 201<P> 202Any Data Explorer object in a Data Explorer data file can be specified for 203import, 204including Lights, Cameras, and Transforms, as well as more 205common objects such as Series, Groups, and Fields. 206The data can be in a separate file from the header, and header and 207data sections can be interspersed. 208And the data can be specified in a variety of formats (see 209see <A HREF="usrgu068.htm#HDREDF">B.2 , "Data Explorer Native Files"</A> in 210<I>IBM Visualization Data Explorer User's Guide</I>). 211<P> 212<TT><STRONG>General array importer files.</STRONG></TT> 213You can use the general format described in <A HREF="qikgu027.htm#HDRGAI">5.1 , 214"General Array Importer"</A> in <I>IBM Visualization Data Explorer QuickStart 215Guide</I> 216to import data from various file formats and convert the data to objects. 217This format allows you to describe the structure of your data so that 218Data Explorer can create Data Explorer objects from it. 219If you do not specify a variable, then all variables are imported. 220<P> 221Normally, the <TT><STRONG>name</STRONG></TT> parameter in this case is the 222general array header file. 223However, the <TT><STRONG>name</STRONG></TT> parameter can be the data file if 224the extended form of the <TT><STRONG>format</STRONG></TT> parameter 225includes the header file as a template. 226The <TT><STRONG>format</STRONG></TT> parameter can also include any set of 227keyword-value pairs as a comma-separated list. 228The specified values are used instead of those in the 229header file. 230This format is useful for data files with similar header files where only the 231size of the data changes. 232An example for the <TT><STRONG>grid</STRONG></TT> keyword is: 233<P> 234<TT><STRONG>format</STRONG></TT> 235<TT>="general, template=headerfile, grid=num<SUB>x</SUB> 236x num<SUB>y</SUB> x num<SUB>z</SUB> ..."</TT> 237<P> 238An example parameter for the <TT><STRONG>points</STRONG></TT> keyword is: 239<P> 240<TT><STRONG>format</STRONG></TT> 241<TT>= "general, template=headerfile, points=n"</TT> 242<P> 243You may also omit <TT>template=headerfile</TT> if all the necessary 244information is specified by the keyword-value pairs. 245<P> 246<TT><STRONG>netCDF files.</STRONG></TT> 247When the netCDF file is opened, variables matching the 248<TT><STRONG>variable</STRONG></TT> parameter are read in 249as field objects. 250If you give no field name, all fields are read in and placed as 251separate fields in a group. 252Each group member is named using the name of the field in the netCDF 253file. 254If more than one variable has the same field name, a composite field is 255created. 256<P> 257You can import both regular and irregular data. 258If the data are regular, nonzero origins and non-unit spacing can be 259handled. 260You can also import scalar, vector, and tensor data. 261For irregular data, "positions" and "connections" are 262determined from information in the netCDF variable attributes 263associated with the field. 264Additional components can also be read in and added to the field, 265based on netCDF attribute information. 266<P> 267For a detailed description of the attributes required in a netCDF 268file, and an example of the correct format, 269see <A HREF="usrgu070.htm#HDRNETCDF">B.4 , "netCDF Files"</A> in <I>IBM 270Visualization Data Explorer User's Guide</I>. 271<P> 272<TT><STRONG>CDF files.</STRONG></TT> 273When the CDF is opened, variables matching the "variable" parameter 274are read in as fields. 275If "variable" is not specified, then all variables are imported 276and placed as fields in a group. 277Each group member is named using the name of the field (CDF variable) 278in the CDF. 279If the CDF contains records, then variable(s) are imported 280as a series. 281Some CDF variables become the "positions" component of the field, 282while others become the "data" component of the field. 283For a series, the values of the record-varying variable become the 284"series positions" attribute(s). 285Variable and global attributes present in the CDF are imported as 286object attributes. 287Only CDF r-variables are supported. 288See <I>IBM Visualization Data Explorer User's Guide</I> for more information 289on importing data from a CDF. 290<P> 291<TT><STRONG>HDF files.</STRONG></TT> 292Scientific DataSets are read in as fields. 293If there are more than one DataSet in the HDF file, you can specify the 294variable as a number corresponding to the position of the data set 295(0 corresponds to the first file). 296If no variable is specified, all fields are read in and placed as 297separate fields in a group. 298Each group member is named using the label (if it exists) from the HDF 299file. 300<P> 301If scales are present, they are interpreted as "positions" with 302regular "connections." 303Otherwise, the positions are a regular grid with regular 304connections. 305For more information on HDF, 306see <A HREF="usrgu072.htm#HDRHDF">B.6 , "HDF Files"</A> in <I>IBM Visualization 307Data Explorer User's Guide</I>. 308<P> 309<TT><STRONG>CM files.</STRONG></TT> 310Import will import saved color-map files. 311(To save a color map explicitly as a separate <TT><STRONG>.cm</STRONG></TT> 312file, choose <TT><STRONG>Save As...</STRONG></TT> in the 313<TT><STRONG>File</STRONG></TT> menu of the 314ColorMap Editor.) 315<P> 316The imported file will be a group containing the color map as the first 317field and the opacity map as the second field. 318(Alternatively, you can import just one of these maps by specifying 319the <TT><STRONG>variable</STRONG></TT> parameter to Import as 320"colormap" or "opacity" respectively.) 321<P> 322The color map is a field with a 1-dimensional "positions" component 323(the data values) and a 3-dimensional "data" component 324(the colors). 325Similarly the opacity map is a field with a 1-dimensional 326"positions" component (the data values) and a 3271-dimensional "data" component (the 328opacities). 329<P> 330You can pass the imported color and opacity maps to (1) the 331<TT><STRONG>color</STRONG></TT> and <TT><STRONG>opacity</STRONG></TT> tabs of 332the 333Color module or (2) the <TT><STRONG>color-map</STRONG></TT> and 334<TT><STRONG>opacity</STRONG></TT> parameters of the Colormap tool. 335<P> 336 337When a .cm file is imported, the result is 338not only information describing the color and 339opacity maps themselves, but also information specifically intended 340for the Colormap Editor regarding control points. Users are not 341expected to create their own .cm files (other than by writing them 342using the <TT><STRONG>Save As</STRONG></TT> command in the Colormap Editor), 343as the content of this file is not documented. 344However users can import any field which has the appropriate color 345or opacity map structure and use it as input to either the Color or 346the Colormap tools. For 347more information on the structure of 348color and opacity maps, see <A HREF="refgu033.htm#HDRCOLOR">Color</A>. 349 350<P> 351<TT><STRONG>External filters.</STRONG></TT> 352<A NAME="SPTEXTFLT"></A> 353If the first character of the <TT><STRONG>name</STRONG></TT> parameter is 354"!" (e.g., "!ext2dx mydata.ext mydata.dx"), the rest of 355the string following the exclamation point is interpreted as a 356shell command to be executed. 357The command should be the name of an external filter program with any 358required arguments. 359The filter program can be any <I>user-supplied</I> program that 360reads data from other file formats or generates data, but it must 361output "dx" or "general array" format as standard 362output. 363The Import module waits for the program to execute, reads the output of 364the program, and imports the objects with the same options as if 365reading directly from a file. 366<P><STRONG>Example Visual Programs</STRONG> 367<P> 368Nearly every example visual program uses the Import module. 369Most import Data Explorer format files. 370Two example programs that import general array format files are: 371<PRE> 372GeneralImport1.net 373GeneralImport2.net 374</PRE> 375<P> 376An example program that uses the external filter option is: 377<PRE> 378ImportExternalFilter.net 379</PRE> 380<P> 381An example program that uses the extended form of the 382<TT><STRONG>format</STRONG></TT> parameter is: 383<PRE> 384MRI_2.net 385</PRE> 386<P><STRONG>See Also</STRONG> 387<P> 388 <A HREF="refgu056.htm#HDREXPORT">Export</A>, 389 <A HREF="refgu102.htm#HDRPARTITI">Partition</A>, 390 <A HREF="refgu110.htm#HDRREADIMA">ReadImage</A>, 391 392 <A HREF="refgu074.htm#HDRIMPSPSH">ImportSpreadsheet</A> 393 <P> 394 <HR> 395 <DIV align="center"> 396 <P><A href="../allguide.htm"><IMG src="../images/foot-fc.gif" width="94" height="18" border="0" alt="Full Contents"></A> <A href="../qikguide.htm"><IMG src="../images/foot-qs.gif" width="94" height="18" border="0" alt="QuickStart Guide"></A> <A href="../usrguide.htm"><IMG src="../images/foot-ug.gif" width="94" height="18" border="0" alt="User's Guide"></A> <A href="../refguide.htm"><IMG src="../images/foot-ur.gif" width="94" height="18" border="0" alt="User's Reference"></A></P> 397 </DIV> 398 <DIV align="center"> 399 <P><FONT size="-1">[ <A href="http://www.research.ibm.com/dx">OpenDX Home at IBM</A> | <A href="http://www.opendx.org/">OpenDX.org</A> ] </FONT></P> 400 <P></P> 401 </DIV> 402 <P></P> 403 </BODY></HTML> 404
