iFit: Saving/exporting objects

Conversion to other Matlab types
Export to lossless formats
- text based lossless formats
- binary lossless formats
Export to lossy formats

Commands we use in this page: iData, save(iData, filename), methods
You may also refer to the Load and Loaders pages to learn about importable formats, as well as the Save Models help.

Once you have managed to actually do something, it is desirable to save your work for future use and communication (print, edit, send to friends...). We thus provide a general interface to save the iData objects.

Among the available formats, some retain the integrity of the object (or at least a significant portion of it) - labelled as lossless formats, and some degrade the object information - labelled as lossy formats.

The text based formats are usually easier to read and edit by humans, whereas the binary formats are much more compact in storage but require dedicated libraries for reading/editing.

The only method required for saving objects is saveas(object, filename, format). When the filename is not specified (left empty as ''), a default name is built from the object unique ID (tag). When the filename is set to 'gui', a file selector dialog pops-up. The filename extension defines the format to use, when this latter is not specified initially. Last, when the format is set to 'gui', a format selector dialog pops-up.The save method is equivalent to saveas.

>> a = iData([ ifitpath 'Data/ILL_IN6.dat'])
>> save(a,'','pdf')               % save object as a PDF and use object ID as file name
>> save(a,'MakeItSo','hdf5')      % save object as a HDF5 into specified filename. Extension is appended automatically
>> saveas(a,'MakeItSo','hdf5')        % 'save' is equivalent to 'saveas'

We recommend the following formats for storing data sets, our best choices being Matlab as binary, and HTML as text/printable document:

text formats: HTML, Matlab .m and DAT. HTML includes DAT as well as many others.
binary formats: HDF5 and Matlab .mat (for re-use from Matlab). HTML includes these.
for printing: PDF and SVG, HTML, FIG if you want to edit the plot with Matlab.

The Matlab MAT workspace format can be generated in two forms:

>> save(a,'','mat')             % save object as a serialized MAT (very fast)
>> save a			% save object as normal MAT file

The first form, using the dedicated 'save'/'saveas' iData methods, generates a MAT-file containing serialized data (much faster to read/write, smaller files by ~30%), but requires to re-import the file using the iFit/iData methods, e.g.

>> load(iData,'mat_file')
>> iData('mat_file')

The second variant, "save a", generates a normal MAT-file (slower to read/write, but portable).

A short list of available export formats is displayed with:

>> a = saveas(iData, 'formats');

Last, the getframe method generates a snapshot picture (thumbnail). The class2str function can more generally write any Matlab variable as a character string. And the str2struct function can read a character string and search for [name{=: }value] pairs in single lines, to set a return structure.

To load back an m or mat file into memory for re-use, type the m-file name without extension, or load(iData,'filename.mat') for MAT-files. Refer to the Load page for other ways to import data files and objects.

Last, you can also save the object history, that is all operations performed from creation to current status, as a Matlab script, by issuing the command:

>> commandhistory(a)

and selecting 'Save all to file...' button. A file selector will pop-up. Enter a filename to generate an m-file script. This script can be read back to reproduce the object. A warning is in place here: if the object was obtained using other objects, these must be available at the time the script is executed. Also, if large static arrays have been used in the process, as they can not be saved in the history the corresponding commands will fail. Last, if you compress the object with e.g. pack, some of the history may be lost.

Conversion to other Matlab types

Convert to	Description
cell(a)	Convert the iData content and field names to cell arrays
char(a)	Assemble Title/Label/Filename into a comprehensive description (does not actually export the data)
double(a)	Extracts the object Signal as a double float array, this is the same as double(a.Signal/a.Monitor)
single(a)	Extracts the object Signal as a single float array, this is the same as single(a.Signal/a.Monitor), and uses less memory than double.
struct(a)	Converts the object to a raw structure. iData methods can not apply on the structure itself. Use iData(structure) to come back to the initial object.
iData(a)	Import an array/structure/cell/file and check iData object structure

Export to lossless formats (retain object)

text based lossless formats

Text files have the advantage that any one can look inside files, and understand what it contains. However, files are usually large as no compression mechanism is applied, natively. The time needed to generate the file can then be substantially long. However, in some cases, a simple numerical representation can be very compact. And such files can be compressed afterwards with e.g. ZIP.

The last column indicates if the generated format for export can be re-used afterwards and re-imported with iFit (see the Loaders and Load page).

format (save)	Text/Binary	Lossless	Description	Read?
'm' Matlab M-file	text	Yes	The M-file format is a flat text file which reconstructs the whole initial object. It is not easily readable by humans, and does not have any compression mechanism, producing large files. Such files can be imported directly by typing their name from Matlab, even without iFit/iData installed. They can also be edited with any text editor.	Yes. Type the file name (without the .m extension) at the prompt
'dat' flat text file	text	Mostly	The DAT format is a flat text file with numerical blocks preceded with a header and readable comments. It can be edited with any text editor. Can be re-imported with iFit/iData, but axes/alias definitions are not re-generated.	Yes
'yaml','json' meta language configuration files	text	Mostly	The YAML/JSON format is a hierarchical indented text file for configuration serialization. It can be edited with any text editor. Can be re-imported with iFit/iData, but you may need to tune the final object.	Yes
'xml' XML description file xmlwrite(a)	text	Mostly	The XML format	Yes
'HTML' Hypertext Markup Language publish(a)	text with attached files	printable page. Data is exported into MAT PNG DAT SVG PDF FIG HDF5...	Hypertext Markup Language with images. Generates a full report, and also indicates any attached Model. The object is exported into a number of formats. Can be viewed with any modern Web browser such as Chrome and Firefox. Can be printed in a nice way. The new content is appended to any previous document. An 'img' folder contains exported files and images.

binary lossless formats

These file formats are usually fast to read/write.

format (save)	Text/Binary	Lossless	Description	Read?
'mat' Matlab Mat-file save(a,'f.mat')	binary	Yes	The Matlab workspace binary file is compact and fast to read/write. It carries the whole object information. Such files require Matlab (or iFit standalone or Octave) to be installed prior to importation. This file format contains serialized data, to be re-imported into an iData object. To save a file use: save(a,'mat_file','mat'). To load it use load(iData,'mat_file').	Yes, use load(iData, 'filename') to read back.
'hdf5' HDF 5	binary	Yes	The HDF5 format is a compact, compressed binary storage format. However, in its use here, it does not reconstruct the whole object, but only its main values and alias/axes names. Such files can be edited/viewed with e.g hdfview, OpenDX, Autoplot. Such files can of course also be imported into iData objects.	Yes
'nxs','n5','nx'	binary	Yes	This is a flavor of the HDF format. Specific support for saving into Mantid and LAMP workspaces by using the 'lamp' and 'mantid' lossy format (see below).	Yes
'nc' NetCDF	binary	Mostly (no Attributes nor structure kept)	The NetCDF format is a compact binary format. However, in its use here, it does not reconstruct the whole object, but only its main values and alias/axes names. Such files can be edited/viewed with e.g ncview or ncBrowse. OpenDX, hdfview, Panoply, Autoplot. Such files can of course also be imported into iData objects.	Yes
'cdf' CDF	binary	Mostly (no Attributes nor structure kept)	The CDF format is a compact binary format. Such files can be edited/viewed with e.g OpenDX, Autoplot. It is incompatible with NetCDF.	Yes

Export to lossy formats

The following formats are mainly intended to be used as object representations. They mostly display/export the object Signal usually weighted by the Monitor, and with axes. No other metadata nor alias is exported. Most of these formats are restricted to flat images (1D and 2D). We recommend binary formats, as they are more compact and the time needed to generate them is smaller.

format (save)	Text/Binary	Lossless	Description	Read?
'fig' Matlab figure	binary	signal/monitor, with axes	The Matlab figure contains the 'visible' part of the object, and can be re-opened/edited from Matlab.	Yes
'csv' Matlab comma separated values csvwrite(a)	text (beware large objects)	signal only	The comma separated value format is a single dump of the object Signal. The other information is lost. Such files can be imported by e.g. any spreadsheet software (OpenOffice, Excel, Gnumeric), or with iFit/iData.	Yes
'hdf4' HDF 4 image	binary	signal only	The HDF4 format is a compact, binary storage format. However, in its use here, it does not reconstruct the whole object, but only its Signal/Monitor values as an image. Such files can be edited/viewed with e.g hdfview. Such files can of course also be imported into iData objects. IDL and Matlab also have dedicated HDF 4 browsers (see hdftool).	Yes
'mantid' Mantid workspace 'lamp' LAMP workspace	binary	signal, axes and some other information	Specific support for saving into Mantid workspaces by using the 'mantid' format. Specific support for saving into LAMP workspaces by using the 'lamp' format.
'edf' EDF ESRF Data format	binary with 512-multiple length text header	signal plus limited metadata	The EDF format is mainly used at the ESRF and can be viewed with e.g. PyMCA, Zimg, GnuPlot, EDFExplorer, Fit2D. This format saves a single image/numeric block plus some metadata in its header.	Yes
'gif' 'bmp' 'png' 'tiff' 'jpeg' imwrite(a)	binary	signal only or signal/monitor	Standard image formats. Can be re-imported with iFit/iData, or used elsewhere (web, email, ...). View with e.g. GIMP, xv, ImageJ.	Yes
'ppm' 'pgm' 'pbm'	text	signal only or signal/monitor	Standard image formats. Can be re-imported with iFit/iData, or used elsewhere (web, email, ...). View with e.g. GIMP, xv, ImageJ.	Yes
'fits' FITS astronomical image format	binary	signal/monitor, only for 2D data.	The FITS format is a standard data format used in astronomy. Can be displayed with e.g. GIMP, xv, Autoplot.	Yes
'ps' 'eps' PostScript	text/binary	signal/monitor, with axes	Usual PostScript files. Can be directly printed. Edit/View with Adobe Illustrator, Acrobat Reader, Gnome/Evince, GIMP.
'pdf' Adobe PDF	binary	signal/monitor, with axes	A portable format for displaying/printing with e.g. Acrobat Reader or Google Chrome, Gnome/Evince, GIMP.
'ill' Adobe Illustrator	binary	signal/monitor, with axes	Similar to PostScript. Files are large. Edit/View with Adobe Illustrator.
'xls' Excel spreadsheet	binary	signal only	Exports as a single spreadsheet. Requires Excel to be installed. Can be re-imported with iFit/iData.	Yes
'svg' Scalable Vector Graphics	text/binary	signal/monitor, with axes	A portable editable vectorial representation of the object. Can be viewed with e.g. Inkscape, GIMP.
'wrl' Virtual Reality world (VRML 2.0)	text (beware large objects)	signal/monitor, with axes	A portable editable vectorial representation of the object similar to X3D. Can be viewed with e.g Freewrl, Octaga Player, WhiteDune, View3DScene, Chimera, ...
'vtk' Visual ToolKit	text/binary	signal/monitor, with some metadata	A portable vectorial representation of 1D/2D/3D objects. Can be viewed with ParaView and Mayavi2. Suitable for 3/4D data (volume).
'x3d' Virtual Reality world (X3D)	text (beware large objects)	signal/monitor, no axes	A portable editable vectorial representation of the object, similar to VRML. Can be viewed with e.g Freewrl, Octaga Player, WhiteDune, View3DScene, InstantPlayer Meshlab ...
'xhtml' Extensible Web page (XHTML/JavaScript/Flash)	text (beware large objects)	signal/monitor, no axes	A web page showing objects in 3D, that can be opened with any modern Web browser such as Chrome and Firefox.
'hdr'+'img' MRI 3D volume	binary (2 files)	signal/monitor, with some metadata	A MRI volume data format. The 'hdr' file requires an associated 'img' file. Format from the Analyze Biomedical Imaging Resource of the Mayo Clinic. For 3/4D data (volume).	Yes
'nii' NifTI MRI volume	binary	signal/monitor, with some metadata	A NifTI medical imaging volume data format (MRI). Such files can be obtained from DICOM files using e.g. DicomNifti, MiTools, MRIconvert, or the Matlab tool dicm2nii. You can view with MiView (MiTools), MRICron. For 3/4D data (volume).	Yes
'mrc' MRC electron density map	binary	signal/monitor	Electron density maps in MRC formats. Can be visualized with PyMol, VMD, Chimera, Yasara, VEDA. For 3/4D data (volume).	Yes
'STL', 'STLB' stereolithography	binary	XYZ points	The STL format is common in stereolithography CAD softwares. Meshlab	Yes
'STLA' 'PLY' 'OFF' stereolithography	text (beware large objects)	XYZ points	The STL SLP OFF and PLY formats are common in stereolithography CAD software. Meshlab	Yes
'ART' ASCII art	text	signal/monitor	The ASCII art is a representation of the object picture as printable characters. If the image is large, it is advisable to reduce its size with e.g. resize, reshape or reducevolume.
'NPY' numpy array	binary	signal/monitor	The NPY format is a binary to store python numpy arrays	yes
'AVI' Audio Video Interleave avifile(a)	binary	signal/monitor	The AVI movie format is a binary format holding a movie. It can be viewed with e.g. VLC
'DAE' and 'KML' Collada GoogleEarth model	binary	signal/monitor	The Keyhole Markup Language (KML) and Collaborative Design Activity (Collada DAE) are two well know formats used in architecture. You can use Meshlab for viewing.

E. Farhi - iFit/iData saving data - Aug. 22, 2017 1.10 - back to Main iFit Page