iFit: Saving/exporting objects




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:
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
text
Mostly
The XML format Yes
'HTML'
Hypertext Markup Language

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

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. OpenDXhdfview, 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

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'

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 ...
'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. Yes
'STLA' 'PLY' 'OFF' stereolithography text (beware large objects) XYZ points The  STL SLP OFF and PLY formats are common in  stereolithography CAD software. 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.




E. Farhi - iFit/iData saving data -  Mar. 22, 2017 1.9 - back to Main iFit Page ILL,
          Grenoble, France <www.ill.eu>