%++++++++
%.IDENTIFICATION fits2a.tex
%.PURPOSE        Man page of fits2a, can be edited in LaTeX
%.AUTHOR         Francois Ochsenbein
%.VERSION   1.0	 20-Jan-2006
%----------

\def\pgm{{\bf fits2a}\ }
\def\file{{\em file}}
\def\br{\\}
%\def\fg#1{\bf\bf}

\begin{manpage} {1}{fits2a}{Ascii output from a FITS file}
	{Apr-2016}{FITS}
\syntax{ \pgm [{\bf--D}|{\bf--toc}|{\bf--TOC}]
   	[{\bf--b}]
   	[{\bf--d}{\em sep}]
	[{\bf--head}]
	[{\bf--max} {\em lines}|{\bf--}{\em lines}]
	[{\bf--meta}|{--meta2}]	
	[{\bf--skip}{\em lines}]
	[{\bf--start}{\em first\_line}]
	[{\bf--top}{\em lines}]
	[{\bf--a} {\em additional_header}]
	[{\bf--akey} {\em FITSkey}={\em value}]
	[{\bf--axis[1|2]}[{\bf=}{\em list}]]
       	[{\bf--c} {\em list\_of\_cols}|{\em=a}]
	[{\bf--q} {\em column}{\bf=}{\em min,max}]
	[{\bf--nodata}|{\bf--tdisp}]
	[{\bf--p1}]
	[{\bf--par}]
	[{\bf--valign}]	
	[{\bf--vmax}  {\em upper\_array\_elements}]
	[{\bf--vskip} {\em array\_elements\_to\_skip}]
	[{\bf--xten} {\em extension\_list}]
	[{\bf  [$n$]\%}{\em fmt}]...
	[{\em input\_fits\_file...}] }

\mansec{ Description }
The \pgm command can be used to edit a FITS file as ascii tables;
the FITS file can contain one or several multidimensional arrays,
ascii or binary FITS tables. For instance a spectrum (1-D) is edited
as a  2-column table, or a cube (3-D) is edited as 4-column
table.

\pgm prints the {\em input\_file}'s  specified as argument(s);
when no file si specified, the standard intput is assumed to
delive an ASCII file.

\mansec{Options}
Without any option, \pgm gives a short help and exits.

%Usage: fits2a -[mf1] [-s maxbytes] [file...]
%   -f: Just test if the file exists and can be read
%   -1: List all the files making up the catalog
%   -m: Add a message before starting each file
%   -v: verbose option
%   -s: stop after maxbytes

\option{--version}
	prints out the version number and exit

\option{--v}
	is a verbose option.

\option{--D}
	Just issue the dimension(s) of the FITS data,
	as {\bf $n$D} followed by the actual size of the FITS array,
	as e.g. {\bf\fg{blue3} 1D 1024} or {\bf\fg{blue3} 3D 512x512x24}.

\option{--toc}
	Just issue the {\em table of contents} of the FITS file.
	A typical example of the result:
\begin{verbatim}
#ext xtension bpx (dim)              x2880 extname
#000     main   8 ()                    1b
#001 BINTABLE   8 (400x0/1f)            1b MASKS
#002 BINTABLE   8 (32x3334/4f)         39b FILTER
#003 BINTABLE   8 (376x503/69f)        73b OBJECTS
#004 BINTABLE   8 (1127x1/109f)         8b FIELDS
\end{verbatim}
	for a FITS file made of 4 binary tables. The fourth column
	lists the number of columns in the number preceded by a {\bf f},
	and the fifth column lists the size of the FITS extension in
	blocks of 2880 bytes.

\option{--TOC}
	In addition to the {\bf--toc} option, \pgm lists the full
	FITS headers.

\option{--b}
	removes the useless blanks (trailing blanks in strings,
	heading blanks in numbers). This option is useful to generate
	a smaller output, especially when a delimiter is given
	(option {\bf--d})

\option{--d {\em sep}}
	defines the delimiter between columns; by default the separator
	is a blank. The option {\bf--d} alone stands for a {\em tab} delimiter.
	It is possible to use the standard escapes, e.g. {\bf\b n} for the
	newline.

\option{--head}
	print column headers -- by default only the data are edited.

\option{--max} {\em lines}
	asks to stop after having examined the specified number of lines.
	A shorter form to limit the examined number of lines is
	a minus ({\bf--}) followed by the maximal number of lines.

\option{--skip}{\em lines}
	asks to ignore the first data lines specified in the argument.

\option{--start}{\em first\_line}
	asks to ignore the first {\em first\_line - 1} lines.
	({\fg{blue3}\em--start n} is therefore equivalent to 
	{\fg{blue3}\em--skip n-1})

\option{--top} {\em lines}
	asks to stop after having found the given number of lines.
	This arguments differs from {\bf --max} when a query is asked
	({\bf--q} option)

\option{--a {\em file}}
	specifies a file which contains additional or replacement
	FITS header metadata,
	like table headers, units, etc.
	For instance, a file could look like:
	\begin{verbatim}
  TTYPE2 = 'RA(J2000)'   / Name of column#2
  TTYPE3 = 'Dec(J2000)'  / Name of column#3
  TDISP2 = 'F8.4'        / Fortran-like format. Note that C-like format can be
  TDISP3 = 'F8.4'        / used if starting by %, e.g. '%+08.4f' for a latitude
	\end{verbatim}
	Notice that each keyword defined in this ooptional file is
	{\em only used once}.

\option{--akey {\em key=value}}
	specifies an additional key (with the FITS conventions).
	For instance, if there is just one additional FITS key to
	use, e.g. {\tt\fg{blue3}TDISP2='F8.4'}, instead of putting 
	it in a file and use the {\bf--a} option, it can be used
	on the command line directly (but beware the interpretation by
	the shell!). For instance:\\
	{\tt fits2a -akey "TDISP2='F8.4'" myfile.fits}

\option{--axis1[{\bf=}{\em list}]}
	asks to edit the values along $x-$axis as the components of
	a vector (on a single line).
	This is useful when 2-D arrays are used to represent table data,
	e.g. spectra frequently stored in 3 columns where the first column 
	contains the wavelengths, the second the flux, and the third the
	error on the flux.
	The optional {\em list} can be used to restrict the edition
	to specified components aling the $x-$-axis, with the following
	conventions:
	\begin{itemize}
	\item	the comma ({\bf,}) and dashes ({\bf--}) indicate
		a series or a range of components, e.g.
	     	{\tt -axis1=1,8-} edits elements \#1, and from \#8 to last.
	\item	the slash ({\bf/}) indicates to start a new list of
		vectors, e.g.
		{\tt -axis1=1,2/3,4} lists the elements \#1 and \#2
		(as a 2-column table), 
		a blank line, and then the elements \#3 and \#4.
	\item	the percent ({\bf\%}) between a lower and an upper
		element number indicates to edit as 1'element vectors, e.g.
		{\tt -axis1=1\%5} lists the values of element \#1,
		a blank line, the values of element \#2, a blank line, 
		etc... until the values of element \#5.
	\end{itemize}

	{\em Note}: if the option {\tt-par} is specified, the
	values are preceded by the value of the axis, e.g.
	{\tt -par -axis1=1-3} edits a 4-column table containing
	the value along the axis (which in a spectrum typically represents the
	wavelength), followed by the values of elements 1, 2 and 3.

\option{--axis2[{\bf=}{\em list}]}
	asks to edit the values along $y-$axis in a single line.
	This is useful when 2-D arrays are used to represent table data,
	e.g. spectra frequently stored in 3 rows where the first row
	contains the wavelengths, the second the flux, and the third row
	theerror on the flux.
	The optional {\em list} can be used to restrict the edition
	to some pixels of the $y-$-axis, e.g.
	{\tt -axis2=4,1} for elements \#4 followed by \#1.

	{\em Note}: the same conventions as {\tt-axis1} apply
	(use of the {\tt -par} option, meaning of {\bf\tt , - / \%}
	[comma, dash, slash, percent] in the list)
\iffalse
	Note: this edition requires more memory (the array has to be
	loaded into memory).\fi

\option{--c =a}
	restricts the output to the columns quoted in the additional
	file specified in the {\bf--a} option

\option{--c {\em list_of_cols}}
	gives a selection of columns to output.
	The list can be given
	\begin{itemize}
	\item	either as numbers, e.g. {\tt\fg{blue3}1-9,12}
	for a selection of columns 1 through 9 and 12;
	\item	or as a comma- or blank-separated list of columns, e.g.
		{\tt\fg{blue3}RA,Dec,Flux}
	\item	as a list of patterns (using wild cards {\bf *} {\bf ?})
		if the first item of the list is an asterisk ({\bf*})
	\end{itemize}
	The list may also be a list of {\em columns to exclude}, if the
	first item of the list is a minus sign ({\bf--}).

	The columns can also be {\em combined} when the column names
	or numbers are separated by the ampersand ({\bf&}) 
	{\em e.g.} {\tt\fg{blue3}RA\&Dec  lambda\&Flux }.
	The plus ({\bf+}) can also be accepted when the columns are
	designated by their number, e.g. {\tt\fg{blue3}1+2+3}.
	A list of columns can be combined as {\tt\fg{blue3}&1-3},
	which has the same meaning as {\tt\fg{blue3}1&2&3} 
	(or {\tt\fg{blue3}1+2+3}). The following remarks apply to
	the combined columns:
	\begin{itemize}
	\item	no column separator between {\em combined columns}:
	 	{\tt\fg{blue3}RA} and {\tt\fg{blue3}Dec} are 
		separated with a blank (not the column separator);
		a newline may be added between each row of combined
		values, see the {\bf--valign} option below
	\item	for array columns, the values are combined before increasing
		the index: if {\tt\fg{blue3}lambda} and {\tt\fg{blue3}Flux}
		are arrays, the values listed are 
		{\tt\fg{blue3}lambda[1]}, {\tt\fg{blue3}Flux[1]}, 
		{\tt\fg{blue3}lambda[2]}, {\tt\fg{blue3}Flux[2]}, etc...
		Note that it is possible limit the range of indices
		with the {\bf--vskip} and {\bf--vmax} options (see below)
	\end{itemize}

\option{--nodata}
	asks to {\em not} edit the data -- by default all data are edited.

\option{--tdisp}
	(for a {\em table}) asks to evaluate the best TDISP formats from the
	data contents. Associated to the -v option, this option computes
	the domain of each column (min, max, and existence of {\em null}
	values). For compatibility with {\em anafile}, {\em--ccg} is
	an equivalent of the {\em--tdisp} option.

\option{--meta}
	asks to present the metadata in a form suitable for the
	creation of a ReadMe file, with lines like
	\begin{verbatim}
	1X  I7      ---   SRCNUM    [1/4.32936e+06]?=- Column#4
	                  Source number in this catalogue  (SRCNUM)
	\end{verbatim}

\option{--p1}
	asks to edit also the constant columns (those with {\tt AXIS}$i$ = 1.
	By default the constant columns are printed in lines starting by
	a {\bf\#} (comment)

\option{--par}
	asks to edit the output as a {\em parfile} (in the case of
	FITS tables): each row becomes a paragraph composed of lines,
	one line representing a column. There is an introductory header.

	Each line of output is written {\em column\_name}{\bf=}{\em value};
	an empty line separates one record from the next one.

	To force the insertion of a blank after the {\bf=} sign, 
	it is possible to use {\bf--par1} instead of {\bf--par}.
	{\bf--par2} would add 2 blanks ater the {\bf=} sign, etc.
	This addition is useful to facilitate the use of scripts
	like {\em perl} or {\em awk}

\option{--q}
	asks to select rows by a selection on columns {\em(a query)}.
	For example {\tt\fg{blue3}-q Bmag=9/12} for a restriction of
	the column {\tt\fg{blue3}Bmag} in the range to 12.
	The {\em negation} can be specified with the exclamation mark,
	for isntance {\tt\fg{blue3}REF!=myWork}

\option{--valign} 
	In the case of the edition of a BINTABLE with vectors, this option
 	asks to align (write on consecutive lines) the rows of combined
	arrays (see the {\bf--c} option obove to combine arrays).
	For example, with {\tt\fg{blue3}-c RA\&Dec} (combination of first
	and second columns) the output is:
	\begin{itemize}
	\item	without the {\bf--valign} option:\\
		RA[1] Dec[1] RA[2] Dec[2] RA[3] Dec[3] ...
	\item	with the {\bf--valign} option:\\
		RA[1] Dec[1] \\
		RA[2] Dec[2] \\
		RA[3] Dec[3]\\
		...
	\end{itemize}

\option{--vmax} {\em upmost\_element}
	limits the number of elements edited for BINTABLE array.
	(the print-out stops with element \#{\em upmost\_element})

\option{--vskip} {\em elements\_to\_skip}
	asks to skip the specified number of elements in BINTABLE arrays;
	for example with {\tt\fg{blue3}-vskip 2}, the edition of
	arrays stars with the element \#3. 

\option{--vstart} {\em first\_element}
	specifies the first element to edit in BINTABLE arrays (default
	is 1). This option is similar to {\bf--vskip}: \\
	{\tt\fg{blue3}-vstart 3} \quad
	has the same effect as {\tt\fg{blue3}-vskip 2}

\option{--xten} {\em extension\_range}
	choose the FITS extension number(s). Note that the main FITS header
	is numbered {\bf0}. For example, {\bf--xten 1-8} asks to process
	the extensions 1 through 8; or {\bf--xten 3--} asks to process
	all extension above 3. The {\em extension\_range} may be replaced
	by the asterisk ({\bf*}), a dot({\bf.} or colon ({\bf:}) to specify
	{\em all} extensions (i.e. is equivalent to {\bf--xten 0--}).
	It is also possible to specifu an extension by its {\em EXTNAME},
	i.e. the extension having the specified
	value of the the {\tt EXTNAME} keyword.
	Note that the {\em EXTNAME} starts by a letter (e.g. {\tt IMAGE}
	or {\tt OI_WAVELENGTH}). A comma-separated list of {\tt EXTNAME}s 
	is also possible; the extensions are then delivered in their
	order in the FITS file, and not in the order they are specified
	in the {\bf--xten} argument.

\option{$n$\%}{\em fmt}...
	C-format to use for the edition of the successive output columns.
	By convention, a {\bf\fg{blue3}\%} alone means that the
	corresponding column is not edited, and a {\bf\fg{blue3}\%.}
	(percent-dot)
	asks to use the standard format (derived from the column
	definitions). The {\bf $n$} number preceding the {\bf\%}
	sign is an optional repetition factor.

\option{ input\_fits\_file...}
	gives the name of the input FITS file(s) to be processed;
	from version 2.6, 
	compressed files (with gzip or bzip2) are accepted, as well
	as files starting by {\bf http://} which are downloaded
	from the web.
	The file may be followed by {\bf\#}{\em extension}, i.e.
	{\tt myfile.fits\#1,3} asks for extensions 1 and 3 of the
	{\tt myfile.fits} file. The extension may alternatively be specified
	by the {\tt EXTNAME}, as e.g.
	{\tt myfile.fits\#MASKS}.
	\br{\bf Note}: the {\bf|} ({\em``pipe''} character) may replace the
	{\bf\#} ({\em``hash''} character).

\mansec{Returned Status}
The \pgm command returns 0 in case of success,
1 in case of errors, and 2 if the output was truncated
(from the {\bf--max} or {\bf--top} option)

\mansec{Examples}

\begin{itemize}
\item	{\tt fits2a -toc myfile.fits}\\
	lists on the standard output the contents of {\tt myfile.fits}.

\item	{\tt fits2a http://cdsarc.u-strasbg.fr/ftp/cats/III/217/sp/s208.fit}\\
	lists on the standard input the spectrum contained in this FITS file

\item	{\tt fits2a -par -axis2=2/3 http://cdsarc.u-strasbg.fr/ftp/cats/J/A+A/553/A99/sp/NGC1132.fit}
         edits the 2 spectra \#2 and \#3 extracted from this FITS file 
	 containing several spectra; the result is ready to be ingested
	 by the {\em graph} application (2 2-column tables separated by
	 a blank line).

\end{itemize}

\seealso{http://fits.gsfc.nasa.gov/fits_documentation.html}
\end{manpage}
