Skip to the navigation links
Last modified: December 2009

URL: http://cxc-newtest.cfa.harvard.edu/ciao4.2/write_columns.sl.html
AHELP for CIAO 4.2

write_columns

Context: sl.crates_contrib

Synopsis

Write out arrays (columns) to a file as a table (ASCII or FITS format).

Syntax

write_columns( filename, col1, ..., coln [; colnames=NULL,
format="text", sep=" ", comment="#"] );

Description

This routine provides a quick means of writing out a set of arrays to a file as a table, in ASCII or FITS binary format.

Loading the routine

The routine can be loaded into a ChIPS or Sherpa session by saying:

require ("crates_utils");

Column content

The data to write out is given as the col1 to coln arguments; they should be S-Lang arrays (e.g. [1,2,3]), they can be multi-dimensional (e.g. for vector columns), and can include string vectors. Each column should contain a single datatype, and all will be padded to the length of the longest array. The padding is 0 for numeric columns and "" or "IND" for string arrays.

Column names

If the optional colnames argument is not given then the output columns will be named "col1" to "coln", where n is the number of columns. To use your own names, supply an array of strings to the colnames argument. This array must contain at least as many values as there are columns (extra elements are ignored).

Output format

The default output format is ASCII, using the "TEXT/SIMPLE" flavor supported by the CIAO Data Model (see "ahelp dmascii" for more information on text formats). The output format can be changed using the format argument, using the values listed below.

The format argument

Value Description
"text" A simple ASCII format consisting of a header line containing the column names and then the data (TEXT/SIMPLE).
"fits" FITS binary table format.
"simple" The same as "text".
"raw" As "text" but without the column names (TEXT/RAW).
"dtf" Data Text Format, which is a FITS-like ASCII format (TEXT/DTF).

ASCII output options

The sep and comment arguments control the ASCII output versions (they are ignored when format is set to "fits"). The sep argument gives the column seperator - the default is " " - and the comment argument gives the character that starts a comment line, and it has a default of "#".

Adding extra metadata to the table

If you wish to add extra metadata to the table then you can use the make_table_crate() routine, which creates a Crate from a list of arrays, add the metadata using Crates routines, and then write the crate out using write_file().

Example 1

chips> a = [1:5];
chips> b = 2.3 * a^2;
chips> c = ["src a", "src b", "", "multiple sources", "x"];
chips> write_columns("src.dat", a, b, c);

The three columns are written to the file "src.dat" in text format. The output file will contain the following; note that the string column contains leading and trailing quote characters for elements that are empty or contain spaces.

chips> !cat src.dat
#TEXT/SIMPLE
# col1 col2 col3
1 2.300000000000 "src a"
2 9.200000000000 "src b"
3 20.70000000000 ""
4 36.80000000000 "multiple sources"
5 57.50000000000 x

Example 2

chips> write_columns("src.dat", a, b, c; colnames=["x", "y",
"comment"]);

The same data is written out as in the previous example but this time explicit column names are given. The output file now looks like:

chips> !cat src.dat
#TEXT/SIMPLE
# x y comment
1 2.300000000000 "src a"
2 9.200000000000 "src b"
3 20.70000000000 ""
4 36.80000000000 "multiple sources"
5 57.50000000000 x

Note that this call will overwrite the contents of the "src.dat" file without warning.

Example 3

chips> cnames = ["x", "y", "comment"];
chips> write_columns("src.fits", a, b, c; colnames=cnames,
format="fits");

The file is now written out as a FITS binary table:

chips> !dmlist src.fits cols
 
----------------------------------------------------------------------
Columns for Table Block TABLE
----------------------------------------------------------------------
 
ColNo  Name       Unit        Type             Range
   1   x                       Int4           -                    
   2   y                       Real8          -Inf:+Inf            
   3   comment                 String[16]                       

Example 4

chips> x = [1:4];
chips> y = _reshape([1:10], [5,2]);
chips> print (x);
1
2
3
4
chips> print (y);
1 2
3 4
5 6
7 8
9 10
chips> write_columns("cols.dat", x, y);
chips> write_columns("cols.fits", x, y; format="fits");

Here we highlight

  • handling multi-dimensional arrays (y),
  • and dealing with arrays of different length (x has 4 scalars and y has 5 pairs).

The ASCII output file contains a scalar column (col1) and a vector column of length 2, col2). The fifth element of col1 has been set to 0 since the input array (x) did not contain any data.

chips> !cat cols.dat
#TEXT/SIMPLE
# col1 col2[2]
1 1 2
2 3 4
3 5 6
4 7 8
0 9 10

The FITS format output is the same: a 0 for the fifth row of col1 and col2 is a vector of length 2.

chips> !dmlist cols.fits data
 
--------------------------------------------------
Data for Table Block TABLE
--------------------------------------------------
 
ROW    col1       col2[2]
 
     1          1                [1 2]
     2          2                [3 4]
     3          3                [5 6]
     4          4                [7 8]
     5          0               [9 10]

Bugs

See the bug pages on the CIAO website for an up-to-date listing of known bugs.

See Also

sl.crates
add_col, add_key, add_piximg, delete_col, delete_key, delete_piximg, read_arf, read_file, read_pha, read_rmf, write_arf, write_file, write_pha, write_rmf
sl.crates_contrib
make_table_crate, scale_image_crate

Last modified: December 2009