.\" Copyright (c) 1999-2009 Massachusetts Institute of Technology
.\" 
.\" Permission is hereby granted, free of charge, to any person obtaining
.\" a copy of this software and associated documentation files (the
.\" "Software"), to deal in the Software without restriction, including
.\" without limitation the rights to use, copy, modify, merge, publish,
.\" distribute, sublicense, and/or sell copies of the Software, and to
.\" permit persons to whom the Software is furnished to do so, subject to
.\" the following conditions:
.\" 
.\" The above copyright notice and this permission notice shall be
.\" included in all copies or substantial portions of the Software.
.\" 
.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
.\" EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
.\" IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
.\" CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
.\" TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
.\" SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
.\"
.TH H5FROMTXT 1 "March 9, 2002" "h5utils" "h5utils"
.SH NAME
h5fromtxt \- convert text input to an HDF5 file
.SH SYNOPSIS
.B h5fromtxt
[\fIOPTION\fR]... [\fIHDF5FILE\fR]
.SH DESCRIPTION
.PP
.\" Add any additional description here
h5fromtxt takes a series of numbers from standard input and outputs a
multi-dimensional numeric dataset in an HDF5 file.

HDF5 is a free, portable binary format and supporting library developed
by the National Center for Supercomputing Applications at the University
of Illinois in Urbana-Champaign.  A single
.I h5
file can contain multiple data sets; by default,
.I h5fromtxt
creates a dataset called "data", but this can be changed via the
.B -d
option, or by using the syntax \fIHDF5FILE:DATASET\fR.  The
.B -a
option can be used to append new datasets to an existing HDF5 file.

All characters besides the numbers (and associated decimal points,
etcetera) in the input are ignored.  By default, the data is assumed
to be a two-dimensional MxN dataset where M is the number of rows
(delimited by newlines) and N is the number of columns.  In this case,
it is an error for the number of columns to vary between rows.  If M
or N is 1 then the data is written as a one-dimensional dataset.

Alternatively, you can specify the dimensions of the data explicitly
via the
.B -n
.I size
option, where
.I size
is e.g. "2x2x2".  In this case, newlines are ignored and the data is
taken as an array of the given size stored in row-major ("C") order
(where the last index varies most quickly as you step through the
data).  e.g. a 2x2x2 array would be have the elements listed in the
order: (0,0,0), (0,0,1), (0,1,0), (0,1,1), (1,0,0), (1,0,1), (1,1,0),
(1,1,1).

A simple example is:
.IP "" 4
h5fromtxt foo.h5 <<EOF
.br
1 2 3 4
.br
5 6 7 8
.br
EOF
.PP
which reads in a 2x4 space-delimited array from standard input.
.SH OPTIONS
.TP
.B -h
Display help on the command-line options and usage.
.TP
.B -V
Print the version number and copyright info for h5fromtxt.
.TP
.B -v
Verbose output.
.TP
.B -a
If the HDF5 output file already exists, append the data as a new
dataset rather than overwriting the file (the default behavior).  An
existing dataset of the same name within the file is overwritten,
however.
.TP
\fB\-n\fR \fIsize\fR
Instead of trying to infer the dimensions of the array from the rows
and columns of the input, treat the data as a sequence of numbers in
row-major order forming an array of dimensions \fIsize\fR.  \fIsize\fR
is of the form MxNxLx... (with M, N, L being numbers) and may be of
any dimensionality.
.TP
.B -T
Transpose the input when it is written, reversing the dimensions.
.TP
\fB\-d\fR \fIname\fR
Write to dataset
.I name
in the output; otherwise, the output dataset is called "data" by default.
Alternatively, use the syntax \fIHDF5FILE:DATASET\fR.
.SH BUGS
Send bug reports to S. G. Johnson, stevenj@alum.mit.edu.
.SH AUTHORS
Written by Steven G. Johnson.  Copyright (c) 2005 by the Massachusetts
Institute of Technology.