FileFormats.html
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>Chaste File Formats</title>
</head>
<body>
<h1>Chaste File Formats</h1>
<h2>General</h2>
<dl>
<dt>.cable</dt>
<dd>
File defining 1D elements that can be used in a MixedDimensionMesh. It has almost the same format as a .ele file.
The difference is that the attribute field (rightmost column) of the .cab file is a floating point number (rather than a
non-negative integer). This attribute represents the radius of the cable element.
</dd>
<dt>.dat</dt>
<dd>
This extension is used as a flexible format for several purposes.
<ul>
<li>Simulation statistics. The structure of each file varies depending on the data they contain. The structure should be described by comments in the methods which write these data.<br/>
An example is the <tt>CellAgesWriter</tt> class:
<ul>
<li>The output is a single value [current simulation time], followed by a tab, followed by a sequence of space-separated values.</li>
<li>This sequence has the form '...[location index] [x-pos] [y-pos] [z-pos] [cell age] ...' where [y-pos] and [z-pos] are included for 2 and 3 dimensional simulations, respectively.</li>
</ul>
</li>
<li>Also used for the fixed-width space-separated column data file format, written by the <tt>ColumnDataWriter</tt> class, and compatible with <a href="http://www.gnuplot.info/">Gnuplot</a>.
<ul>
<li>First line is a header, of the form <tt>Name1(units1) Name2(units2) ... NameN(unitsN)</tt>.</li>
<li>Subsequent lines give the data. Columns are padded with spaces to a fixed width, determined by the <tt>precision</tt> argument to the writer constructor.</li>
</ul>
</li>
</ul>
They are all, however, data files with a similar structure suitable for plotting with <a href="http://www.gnuplot.info/">Gnuplot</a>.
</dd>
<dt>.edge</dt>
<dd>
Edge file for <a href="http://www.cs.cmu.edu/~quake/triangle.html">Triangle</a> or <a href="http://tetgen.berlios.de/">Tetgen</a> format meshes.
<ul>
<li>First line: <tt><number of edges> <number of boundary markers (0 or 1)></tt></li>
<li>Optional marker <tt>BIN</tt> at the end of the first line indicates
that all following data are presented as raw binary data with no
whitespace (this is a Chaste modification of the Triangle format)</li>
<li>Following lines: <tt><edge number> <endpoint node> <endpoint node> [boundary marker]</tt></li>
<li>Lines starting with a hash (#) are comments</li>
</ul>
</dd>
<dt>.ele</dt>
<dd>
Element file for <a href="http://www.cs.cmu.edu/~quake/triangle.html">Triangle</a> or <a href="http://tetgen.berlios.de/">Tetgen</a> format meshes.
<ul>
<li>First line: <tt><number of elements> <nodes per element> <numer of attributes></tt></li>
<li>Optional marker <tt>BIN</tt> at the end of the first line indicates
that all following data are presented as raw binary data with no
whitespace (this is a Chaste modification of the Triangle format)</li>
<li>Remaining lines: <tt><element number> <node> <node> <node> ... [attributes]</tt></li>
<li>Lines starting with a hash (#) are comments</li>
</ul>
</dd>
<dt>.exnode</dt>
<dd>
CMGUI node format, see the <a href="http://www.cmiss.org/cmgui/wiki/TheCmguiEXFormatGuideExnodeAndExelemFiles">Cmgui guide</a>.
</dd>
<dt>.exelem</dt>
<dd>
CMGUI element format, see the <a href="http://www.cmiss.org/cmgui/wiki/TheCmguiEXFormatGuideExnodeAndExelemFiles">Cmgui guide</a>.
</dd>
<dt>.face</dt>
<dd>
Faces file for <a href="http://tetgen.berlios.de/">Tetgen</a> format meshes.
<ul>
<li>First line: <tt><number of faces> <boundary marker (0 or 1)></tt></li>
<li>Optional marker <tt>BIN</tt> at the end of the first line indicates
that all following data are presented as raw binary data with no
whitespace (this is a Chaste modification of the Triangle format)</li>
<li>Remaining lines: <tt><face number> <node> <node> <node> [boundary marker]</tt></li>
<li>Lines starting with a hash (#) are comments</li>
</ul>
</dd>
<dt>.h5</dt>
<dd>
<a href="http://www.hdfgroup.org/HDF5/doc/">HDF5</a> format used for cardiac simulation results. HDF5 represents data in a hierarchical way. Each file contains different datasets, with each dataset containing dataspaces and attributes. Every HDF5 file generated by Chaste defines two main datasets:
<ul>
<li> <i>Data</i>, containing:
<ul>
<li>A 3D array with the simulation results. First dimension being timestep number, second node number, and third variable index.</li>
<li><i>Variable Details</i>: attribute with the variable names and units. </li>
<li><i>IsDataComplete</i>: attribute to say whether the file contains information for all the nodes in the mesh or only for a subset.</li>
<li><i>Chaste Provenance</i>: attribute giving provenance information (Chaste release, time, OS and machine built on).</li>
</ul>
</li>
<li> <i>Time</i>, containing:
<ul>
<li>A 1D array with the time at the end of each timestep.</li>
<li><i>Unit</i>: attribute with the unit of time. </li>
</ul>
</li>
</ul>
The program <tt>h5dump</tt> (if installed) can be used to view the contents of small <tt>HDF5</tt> files. Larger datasets can be converted to Meshalyzer, CMGUI or VTK readable files using the classes <tt>Hdf5ToMeshalyzerConverter</tt>, <tt>Hdf5ToCmguiConverter</tt> or <tt>Hdf5ToVtkConverter</tt>. One of these is generally called at the end of a cardiac simulation that writes HDF5 data.
</dd>
<dt>.info</dt>
<dd>
There are 3 different sorts of .info file:
<ol>
<li>archive.info is read and written by the cardiac archiving code, and is not for user consumption.</li>
<li>The <tt>ColumnDataWriter</tt> also creates a .info file, to tell it how many variables of different types there are.</li>
<li>The final kind, named "<em>something</em>_times.info", is created by the cardiac post-processing code, to give a human readable summary of the timesteps used.</li>
</ol>
</dd>
<dt>.log</dt>
<dd>
Used for test output.
</dd>
<dt>.ncl</dt>
<dd>
Node connectivity file for <a
href="http://www.cs.cmu.edu/~quake/triangle.html">Triangle</a> or <a href="http://tetgen.berlios.de/">Tetgen</a> format meshes. For each mesh node, records which elements contain the node. Note that this file format is <em>not</em> part of the standard Triangle or Tetgen format, but can be created by Chaste and then used to make the mesh load faster in parallel.
<ul>
<li>First line: <tt><number of nodes> <maximum number of containing elements></tt></li>
<li>Marker <tt>BIN</tt> at the end of the first line indicates
that all following data are presented as raw binary data with no
whitespace (this is a Chaste modification of the Triangle format).
All .ncl files are binary.</li>
<li>Remaining lines: <tt><node number> <element> <element> <element> ... [padding to ensure all lines are equal length] </tt></li>
</ul>
</dd>
<dt>.node</dt>
<dd>
Nodes file for <a
href="http://www.cs.cmu.edu/~quake/triangle.html">Triangle</a> or <a href="http://tetgen.berlios.de/">Tetgen</a> format meshes.
<ul>
<li>First line: <tt><number of nodes> <space dimension> <number of attributes> <number of boundary markers (0 or 1)></tt></li>
<li>Optional marker <tt>BIN</tt> at the end of the first line indicates
that all following data are presented as raw binary data with no
whitespace (this is a Chaste modification of the Triangle format)</li>
<li>Remaining lines: <tt><node number> <x> [<y>] [<z>] [attributes] [boundary marker]</tt></li>
<li>Lines starting with a hash (#) are comments</li>
</ul>
</dd>
<dt>.vtu</dt>
<dd>
An XML file format used to visualize simulation results in a <a href="http://www.vtk.org">VTK</a> visualizer. The file format represents a Chaste mesh as a vtkUnstructuredGrid, with each variable represented as point data. The file consists of:
<ul>
<li>XML headers that define the data structure (vtkUnstructuredGrid), the number of nodes (called points in VTK) and elements (called cells in VTK) in the grid and the point data defined on it.</li>
<li>Data as a sequence of ASCII characters.</li>
</ul>
</dd>
</dl>
<h2>Cardiac</h2>
<dl>
<dt>.axi</dt>
<dd>
Defines the fibre direction for each element (used for setting up axisymmetric (transversely isotropic) conductivity tensors).
<ul>
<li>First line: <tt><number of elements></tt></li>
<li>Following lines give the primary (longitudinal) fibre direction vector for each element</li>
</ul>
For the binary version
<ul>
<li>First line: <tt><number of elements></tt> BIN</li>
<li>The following line gives the primary (longitudinal) fibre direction vector for each element as raw binary</li>
</ul>
</dd>
<dt>.epi</dt>
<dd>
Used to specify a list of node numbers (one column) of the nodes belonging to the epicardial surface.
</dd>
<dt>.endo</dt>
<dd>
Used to specify a list of node numbers (one column) of the nodes belonging to the endocardial surface.
</dd>
<dt>.mid</dt>
<dd>
Used to specify a list of node numbers (one column) of the nodes belonging to the midmyocardial surface.
</dd>
<dt>.ortho</dt>
<dd>
Defines the fibre, sheet and normal directions for each element (used for setting up orthotropic (anisotropic) conductivity tensors).
<ul>
<li>First line: <tt><number of elements></tt></li>
<li>Following lines give the fibre direction vectors for each element,
primary/longitudinal direction, then transverse/laminar direction, then normal, i.e. <tt>fibre1 fibre2 fibre3 sheet1 sheet2 sheet3 normal1 normal2 normal3</tt></li>
</ul>
For the binary version
<ul>
<li>First line: <tt><number of elements></tt> BIN</li>
<li>The following line gives the primary/longitudinal fibre direction, then transverse/laminar direction, then normal vector for each element as raw binary</li>
</ul>
</dd>
<dt>.pts</dt>
<dd>
Meshalyzer (used for visualisation) nodes format. First line is <tt><number of nodes></tt>. Following lines are the nodal coordinates.
</dd>
<dt>.tri</dt>
<dd>
Meshalyzer (used for visualisation) triangles format. Represents elements in 2D, and boundary elements in 3D.
</dd>
<dt>.tetra</dt>
<dd>
Meshalyzer (used for visualisation) elements format.
</dd>
</dl>
<h2>Cell-based</h2>
<dl>
<dt>*.arch</dt>
<dd>
File format for a saved (archived) simulation.
</dd>
<dt>build.info</dt>
<dd>
Details of computer setup for a particular <tt>cell_based</tt> chaste simulation. This contains information on versions of libraries used and the revision of the Chaste code.
</dd>
<dt>results.parameters</dt>
<dd>
Details of all the classes and parameters used in a <tt>cell_based</tt> chaste simulation.
</dd>
<dt>*.dat</dt>
<dd>
General format of results files written by cell writer classes, which include a range of different properties of cells at each printing timestep. These take different
formats but, as a representative example, the file <tt>cellages.dat</tt> (which is written using the class <tt>CellAgesWriter</tt>) consists of space-separated lines of the form
<tt>[time] [location index] [cell 0 x-pos] [cell 0 y-pos] [cell 0 z-pos] [cell 0 age] [cell 1 x-pos] [cell 1 y-pos] [cell 1 z-pos] [cell 1 age]...</tt>. Note that if
VTK output is switched on, then cell writer objects also output VTK data for the cell population at each printing timestep.
</dd>
<dt>.viz*</dt>
<dd>
General format of results files written by <tt>cell_based</tt> chaste for the <tt>Visualize2dCentreCells.java</tt> and <tt>Visualize2dVertexCells.java</tt> programs.
</dd>
<dt>.vizancestors</dt>
<dd>
The ancestor index of each cell at each timestep in a <tt>CellBasedSimulation</tt>. Each line has the form <tt>time ancestor_1 ancestor_2 ... ancestor_n</tt>.
</dd>
<dt>.vizbetacatenin</dt>
<dd>
The levels of membrane-bound, cytoplasmic and nuclear beta-catenin in each cell at each timestep in a <tt>CryptSimulation2d</tt>.
Each line has the form <tt> time location_index_1 x_1 y_1 b_cat_membrane_1 b_cat_cytoplasm_1 b_cat_nuclear_1 ...
location_index_n x_n y_n b_cat_membrane_n b_cat_cytoplasm_n b_cat_nuclear_n</tt>.
</dd>
<dt>.vizboundarynodes</dt>
<dd>
Whether each node at each timestep in a <tt>CellBasedSimulation</tt> is a boundary node. Each line has the form <tt>time bool_1 bool_2 ... bool_n</tt>.
</dd>
<dt>.vizcelltypes</dt>
<dd>
The cell type of each cell at each timestep in a <tt>CellBasedSimulation</tt>. Each line has the form <tt>time c_1 c_2 ... c_n</tt>.
</dd>
<dt>.vizcellphases</dt>
<dd>
The cell cycle phase that each cell is in at each timestep in a <tt>CellBasedSimulation</tt>. Each line has the form <tt>time p_1 p_2 ... p_n</tt>.
</dd>
<dt>.vizcoarsepdesolution</dt>
<dd>
The solution to a PDE, associated with a <tt>CellBasedSimulation</tt>, which is solved on a 'coarse' mesh for efficiency. In 2D, each line has the form <tt>time coarse_mesh_node_index_1 coarse_mesh_node_x_1 coarse_mesh_node_y_1 solution_at_coarse_mesh_node_1 ... coarse_mesh_node_index_n coarse_mesh_node_x_n coarse_mesh_node_y_n solution_at_coarse_mesh_node_n</tt>.
</dd>
<dt>.vizelements</dt>
<dd>
The nodes associated with each element at each timestep in
a <tt>CellBasedSimulation</tt>.
For a mesh-based simulation
(visualised with Visualize2dCentreCells) where elements have
exactly 3 nodes, each line has the form <tt>time element1_node1 element1_node2 element1_node3 ... elementn_node1 elementn_node2 elementn_node3</tt>.
For a vertex or Potts simulation
(visualised with Visualize2dVertexCells) where elements have varying
numbers of node, each line has the form <tt>time element1_size
element1_node1 element1_node2 element1_node3 element1_node4 ... elementn_size elementn_node1 elementn_node2 elementn_node3</tt>.
</dd>
<dt>.vizlocationindices</dt>
<dd>
The location of each cell each timestep in a <tt>CaBasedCellPopulation</tt>, which allows for multiple occupancy of lattice sites. Each line has the form <tt>time location_index_1 ... location_index_n</tt>
Also used in <tt>MeshBasedCellPopulationWithGhostNodes</tt> to indicate which nodes have cells attached.
</dd>
<dt>.viznodes</dt>
<dd>
The position of each node at each timestep in a <tt>CellBasedSimulation</tt>. Each line has the form <tt>time x_1 ... x_n</tt> in 1D, <tt>time x_1 y_1 ... x_n y_n</tt> in 2D and <tt>time x_1 y_1 z_1... x_n y_n z_n</tt> in 3D.
</dd>
<dt>.vizpdesolution</dt>
<dd>
The solution to a PDE, associated with a <tt>CellBasedSimulation</tt>, which is solved on a 'coarse' mesh for efficiency. In 2D, each line has the form <tt>time location_index_1 x_1 y_1 solution_1 ... location_index_n x_n y_n solution_n</tt>.
</dd>
<dt>.vizsetup</dt>
<dd>
The <tt>cell_based</tt> visualiser setup file. This contains such things as <tt>mesh_width</tt> for periodic simulations.
</dd>
<dt>.vizstress</dt>
<dd>
The stress distribution in a <tt>MeshBasedCellPopulation</tt>, measured by the extremal normal forces on each cell. Each line has the form <tt>time location_index_1 x_1 y_1 minimum_normal_force_1 maximum_normal_force_1 ... location_index_n x_n y_n minimum_normal_force_n maximum_normal_force_n</tt>.
</dd>
</dl>
</body>
</html>
