Next: About this document ... Up: AstroAsciiData 1.1 User Manual Previous: 3 All in one Contents

Subsections

4 The detailed description

The AstroAsciiData module was developed in Python using an Object Oriented (OO) approach with classes and methods. This can not be hidden in the usage of the AstroAsciiData module. Working with AstroAsciiData means creating its class objects, accessing the class data and executing class methods. This might be confusing for users who are not familiar with this terminology and its meaning.

However this manual makes no attempt to introduce the OO terminology, and its complete understanding is not really necessary in order to use the AstroAsciiData module . The user can simply stick to a strictly phenomenological approach by looking at the examples and transferring them to his/her own applications. Nevertheless the OO terms are used to structure this section of the manual.

4.1 Functions

The AstroAsciiData module contains the two functions open() and create(). These function serve as a starting point for the work with ASCII tables, since both return an AsciiData object by either opening and loading an existing ASCII file (open()) or creating an empty AsciiData object from scratch (create()).

4.1.1 open()

This function loads an existing ASCII table file. An AsciiData object is created and the data stored in the ASCII table is transferred to the AsciiData object. Various function parameters specify e.g. the character used as a delimiter to separate adjacent column elements.

Usage
open(filename, null=None, delimiter=None, comment_char=None)

Parameters

Name Type Default Description

filename string - the name of the ASCII

table file to be loaded

null string ['*','NULL', 'Null', 'None'] the character/string

representing a null-entry

delimiter string `` `` the delimiter separating

columns

comment_char string '#' the character/string

indicating a comment

Return
- an AsciiData object

Examples

Load the file 'example.txt' and print the result. The file 'example.txt looks like:

#
# Some objects in the GOODS field
#
unknown  189.2207323  62.2357983  26.87  0.32
 galaxy  189.1408929  62.2376331  24.97  0.15
   star  189.1409453  62.1696844  25.30  0.12
 galaxy  188.9014716  62.2037839  25.95  0.20

The command sequence is:

>>> example = asciidata.open('example.txt')
>>> print example
#
# Some objects in the GOODS field
#
unknown  189.2207323  62.2357983  26.87  0.32
 galaxy  189.1408929  62.2376331  24.97  0.15
   star  189.1409453  62.1696844  25.30  0.12
 galaxy  188.9014716  62.2037839  25.95  0.20

Load the file 'example2.txt' and print the results. 'example2.txt':

@
@ Some objects in the GOODS field
@
unknown $ 189.2207323 $ 62.2357983 $ 26.87 $ 0.32
 galaxy $      *      $ 62.2376331 $ 24.97 $ 0.15
   star $ 189.1409453 $ 62.1696844 $ 25.30 $  *
 *      $ 188.9014716 $     *      $ 25.95 $ 0.20

Load and print:

>>> example2 = asciidata.open('example2.txt', null='*', \
                              delimiter='$', comment_char='@')
>>> print example2
@
@ Some objects in the GOODS field
@
unknown  $  189.2207323 $  62.2357983 $  26.87 $  0.32
 galaxy  $            * $  62.2376331 $  24.97 $  0.15
   star  $  189.1409453 $  62.1696844 $  25.30 $     *
       * $  188.9014716 $           * $  25.95 $  0.20

4.1.2 create()

This function creates an empty AsciiData object in the 'plain' format, which means that the column information is not part of the default output. The dimension of the AsciiData object as well as the delimiter separating the elements is specified as input.

Usage
create(ncols, nrows, null=None, delimiter=None)

Parameters

Name Type Default Description

ncols int - number of columns to be created

nrows int - number of rows to be created

null string 'Null' the character/string representing a null-entry

delimiter string `` `` the delimiter separating the columns

Return
- an AsciiData object in the 'plain' format

Examples

Create an AsciiData object with 3 columns and 2 rows, print the result:

>>> example3 = asciidata.create(3,2)
>>> print (example3)
      Null       Null       Null
      Null       Null       Null

As in 1., but use a different delimiter and NULL value, print the result:

>>> example4 = asciidata.create(3,2,delimiter='|', null='<*>')
>>> print (example4)
       <*> |        <*> |        <*>
       <*> |        <*> |        <*>

4.1.3 createSEx()

Usage
createSEx(ncols, nrows, null=None, delimiter=None)

Return
- an AsciiData object in the SExtractor catalogue format

Examples

Create an AsciiData object with 3 columns and 2 rows, print the result:

>>> example5 = asciidata.createSEx(3,2)
>>> print example5
# 1  column1
# 2  column2
# 3  column3
      Null       Null       Null
      Null       Null       Null

As in 1., but use a different delimiter and NULL value, print the result:

>>> example6 = asciidata.createSEx(3,2,delimiter='|', null='<*>')
>>> print example6
# 1  column1
# 2  column2
# 3  column3
       <*>|       <*>|       <*>
       <*>|       <*>|       <*>

4.2 The AsciiData class

The AsciiData class is the central class in the AstroAsciiData module. After creating AsciiData objects with one of the functions introduced in Sect. 4.1, the returned objects are modified using its methods.

4.2.1 AsciiData data

AsciiData objects contain some information which is important to the user and can be used in the processing. Although it is possible, this class data should never be changed directly by the user. All book-keeping is done internally such that e.g. the value of ncols is adjusted when deleting a column.

Data

filename string file name associated to the object

ncols int number of columns

nrows int number of rows

Examples

Go over all table entries an store values:

>>> example3 = asciidata.create(100,100)
>>> for cindex in range(example3.ncols):
...     for rindex in range(example3.nrows):
...             example3[cindex][rindex] = do_something(rindex, rindex)
...

Derive a new filename and save the table to this filename:

>>> print example2.filename
example2.txt
>>> newname = example2.filename + '.old'
>>> print newname
example2.txt.old
>>> example2.writeto(newname)

4.2.2 AsciiData method get

This method retrieves list members of an AsciiData instance. These list members are the AsciiColumn instances (see Sect. 4.3), which are accessed via their column name or column number.
The method returns only the reference to the column, therefore changing the returned AsciiColumn instance means also changing the original AsciiData instance (see Example 2)! To get a deep copy of an AsciiColumn the method copy of the AsciiColumn class itself (see Sect. 4.3.6) must be used instead.

Usage
adata_column = adata_object[col_spec]
or
adata_column = operator.getitem(adata_object, col_spec)

Parameters

col_spec string/int column specification, either by column name or column number

Return
- an AsciiColumn instance

Examples

Retrieve the second column of the table:

>>> print example
#
# most important sources!!
#
    1  1.0  red  23.08932 -19.34509
    2  9.5 blue  23.59312 -19.94546
    3  3.5 blue  23.19843 -19.23571
>>> aad_col = example[1]
>>> print aad_col
Column: column2
 1.0
 9.5
 3.5
>>>

Retrieve the second column of the table. Demonstrate that only a shallow copy (reference) is returned:

>>> print example
#
# most important sources!!
#
    1  1.0  red  23.08932 -19.34509
    2  9.5 blue  23.59312 -19.94546
    3  3.5 blue  23.19843 -19.23571
>>> ad_col = operator.getitem(example, 'column1')
>>> print ad_col
Column: column1
    1
    2
    3
>>> ad_col[1] = 'new!'
>>> print ad_col
Column: column1
   1
new!
   3
>>> print example
#
# most important sources!!
#
   1  1.0  red  23.08932 -19.34509
new!  9.5 blue  23.59312 -19.94546
   3  3.5 blue  23.19843 -19.23571
>>>

4.2.3 AsciiData method set

This methods sets list members, which means columns, of an AsciiData instance. The list member to be changed is addressed either via its column name or the column number.
Obviously the replacing object must be an AsciiColumn instance which contains an equal number of rows. Otherwise an exception is risen.

Usage
adata_object[col_spec] = adata_column
or
operator.setitem(adata_object, col_spec, adata_column)

Parameters

col_spec string/int column specification, either by column name or column number

adata_column AsciiColumn the AsciiColumn instance to replace the previous column

Return
-

Examples

Replace the third row of the table 'exa_1' with the third row of table 'exa_2'. Please note the interplay between the get- and the set-method of the AsciiData class:

>>> exa_1 = asciidata.open('some_objects.cat')
>>> exa_2 = asciidata.open('some_objects_2.cat', delimiter='|', comment_char='@', null='*')
>>> print exa_1
#
# most important objects
#
    1  1.0  red  23.08932 -19.34509
    2  9.5 blue  23.59312 -19.94546
    3  3.5 blue  23.19843 -19.23571
>>> print exa_2
@
@
@
   10| 0.0|  pink | 130.3757| 69.87343
   25| 5.3| green | 130.5931| 69.89343
   98| 3.5|      *| 130.2984| 69.30948
>>> exa_1[2] = exa_2[2]
>>> print exa_1
#
# most important objects
#
    1  1.0   pink   23.08932 -19.34509
    2  9.5  green   23.59312 -19.94546
    3  3.5    Null  23.19843 -19.23571
>>>

4.2.4 AsciiData method writeto()

Write the AsciiData object to a file. The file name is given in a parameter. Independent of the catalogue format (plain or SExtractor) two parameters control whether the column information and the header comment are also written to the new file.

By default the header comments are always written to the file, the column info only for the SExtractor format.

Usage
adata_object.writeto(filename, colInfo, headComment)

Parameters

Name Type Default Description

filename string - the filename to save the AsciiData object to

colInfo int None write column info () or not()

headComment int None write header comment () or not()

Return
-

Examples

Write an AsciiData object to the file 'newfile.txt':

>>> print example2
@
@ Some objects in the GOODS field
@
unknown   $  189.2207323 $  62.2357983 $  26.87 $  0.32
 galaxy   $            * $  62.2376331 $  24.97 $  0.15
   star   $  189.1409453 $  62.1696844 $  25.30 $     *
        * $  188.9014716 $           * $  25.95 $  0.20
>>> example2.writeto('newfile.txt')
>>>
> more newfile.txt
@
@ Some objects in the GOODS field
@
unknown   $  189.2207323 $  62.2357983 $  26.87 $  0.32
 galaxy   $            * $  62.2376331 $  24.97 $  0.15
   star   $  189.1409453 $  62.1696844 $  25.30 $     *
        * $  188.9014716 $           * $  25.95 $  0.20

4.2.5 AsciiData method writetofits()

The method transforms an AsciiData instance to a fits-table and stores the fits-table to the disk. The filename is either specified as a parameter or is derived from the filename of the original ascii-table. In the latter case the file extension is changed to '.fits'.
The module PyFITS (see http://www.stsci.edu/resources/software_hardware/pyfits) must be installed to run this method. The transformation fails if the AsciiData instance contains any Null elements (due to a limitation of the numpy and numarray objects, which are essential for the method).

Usage
aad_object.writetofits(fits_name=None)

Parameters

fits_name string the name of the fits-file

Return
- the fits file to which the AsciiData instance was written

Examples

Store an AsciiData instance as a fits-file, using the default name:

test>ls
some_objects.cat
test>python
Python 2.4.2 (#1, Nov 10 2005, 11:34:38)
[GCC 3.3.3 20040412 (Red Hat Linux 3.3.3-7)] on linux2
Type "help", "copyright", "credits" or "license" for more information.
>>> import asciidata
>>> exa = asciidata.open('some_objects.cat')
>>> fits_name = exa.writetofits()
>>> fits_name
'some_objects.fits'
>>>
test>ls
some_objects.cat  some_objects.fits
test>

Store an AsciiData instance to the fits-file 'test.fits':

test>ls
some_objects.cat
test>python
Python 2.4.2 (#1, Nov 10 2005, 11:34:38)
[GCC 3.3.3 20040412 (Red Hat Linux 3.3.3-7)] on linux2
Type "help", "copyright", "credits" or "license" for more information.
>>> import asciidata
>>> exa = asciidata.open('some_objects.cat')
>>> fits_name = exa.writetofits('test.fits')
>>> fits_name
'test.fits'
>>>
test>ls
some_objects.cat  test.fits
test>

4.2.6 AsciiData method writetohtml()

The method writes the data of an AsciiData instance formatted as the content of an html-table to the disk. Strings used as attributes can be specified for the tags <tr> and <td>. The name of the html-file is either given as parameter or is derived from the name of the original ascii-table. In the latter case the file extension is changed to '.html'.
The html-table is neither opened nor closed at the beginning and end of the file, respectively. Also column names and other meta information is NOT used in the html.

Usage
aad_object.writetohtml(html_name=None, tr_attr=None, td_attr=None)

Parameters

html_name string the name of the html-file

tr_attr string attribute string for the tr-tag

td_attr string attribute string for the td-tag

Return
- the name of the html-file

Examples

Write an AsciiData instance to an html-file:

>>> exa = asciidata.open('some_objects.cat')
>>> exa.writetohtml()
'some_objects.html'
>>>
test>more 'some_objects.html'
<tr><td>    1</td><td> 1.0</td><td> red</td><td> 23.08932</td><td>-19.34509</td></tr>
<tr><td>    2</td><td> 9.5</td><td>blue</td><td> 23.59312</td><td>-19.94546</td></tr>
<tr><td>    3</td><td> 3.5</td><td>blue</td><td> 23.19843</td><td>-19.23571</td></tr>
test>

Write an AsciiData instance to the html-file 'mytab.tab', using attributes for the tags:

>>> exa = asciidata.open('some_objects.cat')
>>> html_name = exa.writetohtml('mytab.tab',tr_attr='id="my_tr"',td_attr='bgcolor="RED"')
>>> print html_name
mytab.tab
>>>
test>more mytab.tab
<tr id="my_tr"><td bgcolor="RED">    1</td><td bgcolor="RED"> 1.0</td><td bgcolor="RED">
 red</td><td bgcolo
r="RED"> 23.08932</td><td bgcolor="RED">-19.34509</td></tr>
<tr id="my_tr"><td bgcolor="RED">    2</td><td bgcolor="RED"> 9.5</td><td bgcolor="RED">
blue</td><td bgcolo
r="RED"> 23.59312</td><td bgcolor="RED">-19.94546</td></tr>
<tr id="my_tr"><td bgcolor="RED">    3</td><td bgcolor="RED"> 3.5</td><td bgcolor="RED">
blue</td><td bgcolo
r="RED"> 23.19843</td><td bgcolor="RED">-19.23571</td></tr>
test>

4.2.7 AsciiData method writetolatex()

The method writes the data of an AsciiData instance, formatted as the content of a L^ATEXtable, to the disk. The name of the L^ATEXfile is either given as parameter or is derived from the name of the original ascii-table. In the latter case the file extension is changed '.tex'.

Usage
aad_object.writetolatex(latex_name=None)

Parameters

latex_name string the name of the latex-file

Return
- the name of the latex-file

Examples

Write the content of an AsciiData instance to 'latextab.tb':

>>> exa = asciidata.open('some_objects.cat')
>>> latex_name = exa.writetolatex('latex.tb')
>>> print latex_name
latex.tb
>>>
test>more latex.tb
    1& 1.0& red& 23.08932&-19.34509\\
    2& 9.5&blue& 23.59312&-19.94546\\
    3& 3.5&blue& 23.19843&-19.23571\\
test>

4.2.8 AsciiData method sort()

This method sorts the data in an AsciiData instance according to the values in a specified column. Sorting in ascending and descending order is possible.
There are two different sorting algorithms implemented. A fast algorithm which is based on recursion can be used for making a single, 'isolated' sort process (ordered=0).

However the fast algorithm can break, e.g. when sorting an already sorted table (e.g. descending) in the opposite direction (ascending). Then the maximum recursion depth of python can be reached, causing a failure. In addition, fast recursive algorithms introduce random swaps of rows, which is counterproductive if the desired result of the sort process can only be reached with consequtive sortings on different columns (see examples 3 and 4 below).

In these cases a slower sorting algorithm must be used which is evoked with the parameter ordered=1.

Usage
adata_object.sort(colname, descending=0, ordered=0)

Parameters

colname string/integer the specification of the sort column

descending integer sort in ascending () or descending () order

ordered integer use the fast () algorithm or the slow ()

which avoids unnecessary row swaps

Return
-

Examples

Sort a table in ascending order of the values in the second column:

>>> sort = asciidata.open('sort_objects.cat')
>>> print sort
    1     0     1     1
    2     1     0     3
    3     1     2     4
    4     0     0     2
    5     1     2     1
    6     0     0     3
    7     0     2     4
    8     1     1     2
    9     0     1     5
   10     1     2     6
   11     0     0     6
   12     1     1     5
>>> sort.sort(1)
>>> print sort
    1     0     1     1
    6     0     0     3
    9     0     1     5
   11     0     0     6
    7     0     2     4
    4     0     0     2
   12     1     1     5
    2     1     0     3
   10     1     2     6
    3     1     2     4
    5     1     2     1
    8     1     1     2
>>>

Use the result from example 1, and sort the table in descending order of the first column:

>>> sort.sort(0, descending=1)
>>> print sort
   12     1     1     5
   11     0     0     6
   10     1     2     6
    9     0     1     5
    8     1     1     2
    7     0     2     4
    6     0     0     3
    5     1     2     1
    4     0     0     2
    3     1     2     4
    2     1     0     3
    1     0     1     1
>>>

Sort the table first along column 3 and then along column 2. The resulting table is sorted along column 2, but in addition it is ordered along column 3 for equal values in column 2. This works only using the slower, ordered sorting algorithm:

>>> sort.sort(2, ordered=1)
>>> sort.sort(1, ordered=1)
>>> print sort
   11     0     0     6
    6     0     0     3
    4     0     0     2
    9     0     1     5
    1     0     1     1
    7     0     2     4
    2     1     0     3
   12     1     1     5
    8     1     1     2
   10     1     2     6
    5     1     2     1
    3     1     2     4
>>>

As the previous example, but using the faster, un-ordered sorting algorithm. The result differs from the previous example, since the fast algorithm does not preserve the sorting in column 3 for equal values in column 2:

>>> sort.sort(2, ordered=0)
>>> sort.sort(1, ordered=0)
>>> print sort
    1     0     1     1
    4     0     0     2
    7     0     2     4
   11     0     0     6
    9     0     1     5
    6     0     0     3
   12     1     1     5
    2     1     0     3
    3     1     2     4
   10     1     2     6
    5     1     2     1
    8     1     1     2
>>>

4.2.9 AsciiData method len()

This method defines a length for every AsciiData instance, which is the number of columns.

Usage
len(aad_object)

Parameters
-

Return
- the length of the AsciiData instance

Examples

Determine and print the length of an AsciiData instance:

>>> exa = asciidata.open('some_objects.cat')
>>> print exa
#
# most important objects
#
    1  1.0  red  23.08932 -19.34509
    2  9.5 blue  23.59312 -19.94546
    3  3.5 blue  23.19843 -19.23571
>>> length = len(exa)
>>> print length
5
>>>

4.2.10 AsciiData iterator type

This defines an iterator over an AsciiData instance. The iteration is finished after aad_object.ncols calls and returns each column in subsequent calls. Please note that it is not possible to change these columns.

Usage
for iter in aad_object:
...

Parameters
-

Return
-

Examples

Iterate over an AsciiData instance and print each column name:

>>> exa = asciidata.open('sort_objects.cat')
>>> for col in exa:
...     print col.colname
...
column1
column2
column3
column4
>>>

4.2.11 AsciiData method append()

Invoking this method is the formal way to append an new column to and AsciiData object. When created there are only Null entries in the new column. The alternative way is just to specify a column with an unknown name (see Sect. 3.1).

Usage
adata_object.append(col_name)

Parameters

col_name string the name of the new column

Return
- the number of the columns created

Examples

Append a new column 'newcolumn' to the AsciiData object:

>>> print example2
@
@ Some objects in the GOODS field
@
unknown  $  189.2207323 $  62.2357983 $  26.87 $  0.32
 galaxy  $            * $  62.2376331 $  24.97 $  0.15
   star  $  189.1409453 $  62.1696844 $  25.30 $     *
       * $  188.9014716 $           * $  25.95 $  0.20
>>> cnum = example2.append('newcolumn')
>>> print cnum
5
>>> print example2
@
@ Some objects in the GOODS field
@
unknown  $  189.2207323 $  62.2357983 $  26.87 $  0.32 $          *
 galaxy  $            * $  62.2376331 $  24.97 $  0.15 $          *
   star  $  189.1409453 $  62.1696844 $  25.30 $     * $          *
       * $  188.9014716 $           * $  25.95 $  0.20 $          *

4.2.12 AsciiData method str()

This methods converts the whole AsciiData object into a string. Columns are separated with the delimiter, empty elements are represented by the Null-string and the header is indicated by a comment-string at the beginning. In this method the class object appears as a function argument and the method call is different from the usual form such as in Sect. 4.2.11

Usage
str(adata_object)

Parameters
-

Return
- the string representing the AsciiData object

Examples

Print an AsciiData object to the screen:

>>> print str(example2)
@
@ Some objects in the GOODS field
@
unknown  $  189.2207323 $  62.2357983 $  26.87 $  0.32
 galaxy  $            * $  62.2376331 $  24.97 $  0.15
   star  $  189.1409453 $  62.1696844 $  25.30 $     *
       * $  188.9014716 $           * $  25.95 $  0.20

Store the sting representation of an AsciiData object:

>>> big_string = str(example2)
>>> print big_string
@
@ Some objects in the GOODS field
@
unknown  $  189.2207323 $  62.2357983 $  26.87 $  0.32
 galaxy  $            * $  62.2376331 $  24.97 $  0.15
   star  $  189.1409453 $  62.1696844 $  25.30 $     *
       * $  188.9014716 $           * $  25.95 $  0.20

4.2.13 AsciiData method del

This method deletes a column specified either by its name or by the column number. Also this method call is slightly different from the usual form such as in Sect. 4.2.11 or 4.2.14.

Usage
del adata_obj[col_spec]

Parameters

col_spec string/int column specification either by name or by the column number

Return
-

Examples

Delete the column with name 'column5':

>>> print example2
@
@ Some objects in the GOODS field
@
unknown  $  189.2207323 $  62.2357983 $  26.87 $  0.32
 galaxy  $            * $  62.2376331 $  24.97 $  0.15
   star  $  189.1409453 $  62.1696844 $  25.30 $     *
       * $  188.9014716 $           * $  25.95 $  0.20
>>> del example2['column5']
>>> print example2
@
@ Some objects in the GOODS field
@
unknown  $  189.2207323 $  62.2357983 $  26.87
 galaxy  $            * $  62.2376331 $  24.97
   star  $  189.1409453 $  62.1696844 $  25.30
       * $  188.9014716 $           * $  25.95

Delete the second column:

>>> print example2
@
@ Some objects in the GOODS field
@
unknown  $  189.2207323 $  62.2357983 $  26.87 $  0.32
 galaxy  $            * $  62.2376331 $  24.97 $  0.15
   star  $  189.1409453 $  62.1696844 $  25.30 $     *
       * $  188.9014716 $           * $  25.95 $  0.20
>>> del example2[1]
>>> print example2
@
@ Some objects in the GOODS field
@
unknown  $  62.2357983 $  26.87 $  0.32
 galaxy  $  62.2376331 $  24.97 $  0.15
   star  $  62.1696844 $  25.30 $     *
       * $           * $  25.95 $  0.20

4.2.14 AsciiData method delete()

This method deletes rows in an AsciiData object. The rows to be deleted are specified in the parameters as start index and index of the first row not to be deleted. Deletes exactly one row if just the start value is given.

Usage
adata_obj.delete(start, end=start+1)

Parameters

start int the first row to be deleted

end int the first row not to be deleted

Return
-

Examples

Delete only row with index 1:

>>> print example2
@
@ Some objects in the GOODS field
@
unknown   $  189.2207323 $  62.2357983 $  26.87 $  0.32
 galaxy   $            * $  62.2376331 $  24.97 $  0.15
   star   $  189.1409453 $  62.1696844 $  25.30 $     *
        * $  188.9014716 $           * $  25.95 $  0.20
>>> example2.delete(1)
>>> print example2
@
@ Some objects in the GOODS field
@
unknown   $  189.2207323 $  62.2357983 $  26.87 $  0.32
   star   $  189.1409453 $  62.1696844 $  25.30 $     *
        * $  188.9014716 $           * $  25.95 $  0.20

Delete the row with index 0 and 1:

>>> print example2
@
@ Some objects in the GOODS field
@
unknown   $  189.2207323 $  62.2357983 $  26.87 $  0.32
 galaxy   $            * $  62.2376331 $  24.97 $  0.15
   star   $  189.1409453 $  62.1696844 $  25.30 $     *
        * $  188.9014716 $           * $  25.95 $  0.20
>>> example2.delete(0,2)
>>> print example2
@
@ Some objects in the GOODS field
@
   star   $  189.1409453 $  62.1696844 $  25.30 $     *
        * $  188.9014716 $           * $  25.95 $  0.20

4.2.15 AsciiData method strip()

The method removes leading or trailing table rows which are either empty or superfluous. Superfluous rows are marked by the argument given to the method.

Usage
adata_obj.strip(x=None)

Parameters

x int/float/string filling value which indicates a superfluous entry

Return
-

Examples

Remove all empty rows from the table:

>>> print example
#
#
#
 Null  Null  Null  Null
    0     0  Null     1
 Null     9     8     0
 Null  Null  Null  Null
 Null  Null  Null  Null
>>> example.strip()
>>> print example
#
#
#
    0     0  Null     1
 Null     9     8     0
>>>

Remove all rows which contain only the value

from the table:

>>> print example
#
#
#
   -1    -1    -1    -1
    0     0    -1     1
   -1     9     8     0
   -1    -1    -1    -1
   -1    -1    -1    -1
>>> example.strip(-1)
>>> print example
#
#
#
    0     0    -1     1
   -1     9     8     0
>>>

4.2.16 AsciiData method lstrip()

The method removes all table rows which are either empty or superfluous from the top ( $\equiv$ left) of the table. Superfluous rows are marked by the argument given to the method.

Usage
adata_obj.lstrip(x=None)

Parameters

x int/float/string filling value which indicates a superfluous entry

Return
-

Examples

Remove all empty rows from the top of the table:

>>> print example
#
#
#
 Null  Null  Null  Null
    0     0  Null     1
 Null     9     8     0
 Null  Null  Null  Null
 Null  Null  Null  Null
>>> example.lstrip()
>>> print example
#
#
#
    0     0  Null     1
 Null     9     8     0
 Null  Null  Null  Null
 Null  Null  Null  Null

Remove all rows which contain only the value

from the top of the table:

>>> print example
#
#
#
   -1    -1    -1    -1
    0     0    -1     1
   -1     9     8     0
   -1    -1    -1    -1
   -1    -1    -1    -1
>>> example.lstrip(-1)
>>> print example
#
#
#
    0     0    -1     1
   -1     9     8     0
   -1    -1    -1    -1
   -1    -1    -1    -1
>>>

4.2.17 AsciiData method rstrip()

The method removes all table rows which are either empty or superfluous from the bottom ( $\equiv$ right) of the table. Superfluous rows are marked by the argument given to the method..

Usage
adata_obj.rstrip(x=None)

Parameters

x int/float/string filling value which indicates a superfluous entry

Return
-

Examples

Remove all empty rows from the bottom of the table:

>>> print example
#
#
#
 Null  Null  Null  Null
    0     0  Null     1
 Null     9     8     0
 Null  Null  Null  Null
 Null  Null  Null  Null
>>> example.rstrip()
>>> print example
#
#
#
 Null  Null  Null  Null
    0     0  Null     1
 Null     9     8     0
>>>

Remove all rows which contain only the value

from the bottom of the table:

>>> print example
#
#
#
   -1    -1    -1    -1
    0     0    -1     1
   -1     9     8     0
   -1    -1    -1    -1
   -1    -1    -1    -1
>>> example.rstrip(-1)
>>> print example
#
#
#
   -1    -1    -1    -1
    0     0    -1     1
   -1     9     8     0
>>>

4.2.18 AsciiData method find()

The method determines the column number for a given column name. The value -1 is returned if a column with this name does not exist.

Usage
adata_obj.find(col_name)

Parameters

col_name string the name of the column

Return
- the column number or -1 if the column does not exist

Examples

Search for the column with name 'column3':

>>> example2 = asciidata.open('example2.txt', null='*', \
                              delimiter='$', comment_char='@')
>>> cnum = example2.find('column2')
>>> cnum
1
>>>

Search for the column with the name 'not_there':

>>> example2 = asciidata.open('example2.txt', null='*', \
                              delimiter='$', comment_char='@')
>>> cnum = example2.find('not_there')
>>> cnum
-1
>>>

Obviously the AsciiData object example2 does not have a column with this name.

4.2.19 AsciiData method flush()

The method updates the associated file with the newest version of the AsciiData object.

Usage
adata_obj.flush()

Parameters
-

Return
-

Examples

Manipulate an AsciiData object and update the file:

work>more example.txt
#
# Some objects in the GOODS field
#
unknown  189.2207323  62.2357983  26.87  0.32
 galaxy  189.1408929  62.2376331  24.97  0.15
   star  189.1409453  62.1696844  25.30  0.12
 galaxy  188.9014716  62.2037839  25.95  0.20
work>python
Python 2.4.2 (#5, Oct 21 2005, 11:12:03)
[GCC 3.3.2] on sunos5
Type "help", "copyright", "credits" or "license" for more information.
>>> import asciidata
>>> example = asciidata.open('example.txt')
>>> del example[4]
>>> example.flush()
>>>
work>more example.txt
#
# Some objects in the GOODS field
#
unknown  189.2207323  62.2357983  26.87
 galaxy  189.1408929  62.2376331  24.97
   star  189.1409453  62.1696844  25.30
 galaxy  188.9014716  62.2037839  25.95

4.2.20 AsciiData method info()

The method returns an informative overview on the AsciiData object as a string. This overview gives the user a quick insight into e.g. the column names of the object.

The focus of the method clearly is the use in interactive work. All information provided can be retrieved by AsciiColumn methods in a machine readable format as well.

The overview contains:

the name of the file associated to the AsciiData object;
the number of columns;
the number of rows;
the delimiter to separate columns;
the representing Null-values;
the comment string.

In addition, for every column the column name, type, format and Null-representation is given.

Usage
adata_object.info()

Parameters
-

Return
-

Examples

Print the information on an AsciiData object onto the screen:

>>> example = asciidata.open('example.txt')
>>> print example.info()
File:       example.txt
Ncols:      4
Nrows:      4
Delimiter:  None
Null value: ['Null', 'NULL', 'None', '*']
Comment:    #
Column name:        column1
Column type:        <type 'str'>
Column format:      ['% 7s', '%7s']
Column null value : ['Null']
Column name:        column2
Column type:        <type 'float'>
Column format:      ['% 11.7f', '%12s']
Column null value : ['Null']
Column name:        column3
Column type:        <type 'float'>
Column format:      ['% 10.7f', '%11s']
Column null value : ['Null']
Column name:        column4
Column type:        <type 'float'>
Column format:      ['% 5.2f', '%6s']
Column null value : ['Null']

4.2.21 AsciiData method insert()

This method inserts empty rows into all columns of the AsciiData object. The first parameters gives the number of rows to be inserted. The second parameter controls where exactly the new, empty rows are positioned. It specifies the index of the first, empty row. By default the rows are inserted at the table start.

Usage
adata_object.insert(nrows, start=0)

Parameters

nrows int number of rows to be inserted

start int index position of the first inserted column

Return
-

Examples

Insert two rows such that the first row will have the index 1:

>>> print example2
@
@ Some objects in the GOODS field
@
unknown   $  189.2207323 $  62.2357983 $  26.87 $  0.32
 galaxy   $            * $  62.2376331 $  24.97 $  0.15
   star   $  189.1409453 $  62.1696844 $  25.30 $     *
        * $  188.9014716 $           * $  25.95 $  0.20
>>> example2.insert(2,1)
>>> print example2
@
@ Some objects in the GOODS field
@
unknown   $  189.2207323 $  62.2357983 $  26.87 $  0.32
        * $            * $           * $      * $     *
        * $            * $           * $      * $     *
 galaxy   $            * $  62.2376331 $  24.97 $  0.15
   star   $  189.1409453 $  62.1696844 $  25.30 $     *
        * $  188.9014716 $           * $  25.95 $  0.20

4.2.22 AsciiData method newcomment_char()

The method defines a new comment string for an AsciiData object.

Usage
adata_object.newcomment_char(comment_char)

Parameters

comment_char string the string to indicate a comment

Return
-

Examples

Change the comment sign from '@' to '!!':

>>> print example2
@
@ Some objects in the GOODS field
@
unknown   $  189.2207323 $  62.2357983 $  26.87 $  0.32
 galaxy   $            * $  62.2376331 $  24.97 $  0.15
   star   $  189.1409453 $  62.1696844 $  25.30 $     *
        * $  188.9014716 $           * $  25.95 $  0.20
>>> example2.newcomment_char('!!')
>>> print example2
!!
!! Some objects in the GOODS field
!!
unknown   $  189.2207323 $  62.2357983 $  26.87 $  0.32
 galaxy   $            * $  62.2376331 $  24.97 $  0.15
   star   $  189.1409453 $  62.1696844 $  25.30 $     *
        * $  188.9014716 $           * $  25.95 $  0.20

4.2.23 AsciiData method newdelimiter()

This method specifies a new delimiter for an AsciiData object.

Usage
adata_object.newdelimiter(delimiter)

Parameters

delimiter string the new delimiter to separate columns

Return
-

Examples

Change the delimiter sign from '$' to '<>':

>>> print example2
!!
!! Some objects in the GOODS field
!!
unknown   $  189.2207323 $  62.2357983 $  26.87 $  0.32
 galaxy   $            * $  62.2376331 $  24.97 $  0.15
   star   $  189.1409453 $  62.1696844 $  25.30 $     *
        * $  188.9014716 $           * $  25.95 $  0.20
>>> example2.newdelimiter('<>')
>>> print example2
!!
!! Some objects in the GOODS field
!!
unknown   <>  189.2207323 <>  62.2357983 <>  26.87 <>  0.32
 galaxy   <>            * <>  62.2376331 <>  24.97 <>  0.15
   star   <>  189.1409453 <>  62.1696844 <>  25.30 <>     *
        * <>  188.9014716 <>           * <>  25.95 <>  0.20

4.2.24 AsciiData method newnull()

The method specifies a new string to represent Null-entries in an AsciiData object.

Usage
adata_object.newnull(newnull)

Parameters

newnull string the representation for Null-entries

Return
-

Examples

Change the Null representation from '*' to 'NaN':

>>> print example2
@
@ Some objects in the GOODS field
@
unknown   $  189.2207323 $  62.2357983 $  26.87 $  0.32
 galaxy   $            * $  62.2376331 $  24.97 $  0.15
   star   $  189.1409453 $  62.1696844 $  25.30 $     *
        * $  188.9014716 $           * $  25.95 $  0.20
>>> example2.newnull('NaN')
>>> print example2
@
@ Some objects in the GOODS field
@
unknown   $  189.2207323 $  62.2357983 $  26.87 $  0.32
 galaxy   $          NaN $  62.2376331 $  24.97 $  0.15
   star   $  189.1409453 $  62.1696844 $  25.30 $   NaN
      NaN $  188.9014716 $         NaN $  25.95 $  0.20

4.2.25 AsciiData method toplain()

Change the format of the AsciiData object to 'plain'. As a consequence the column info (names, units and comments) are no longer part of the output when e.g. writing the object to a file.

Usage
adata_object.toplain()

Parameters
-

Return
-

Examples

Load an AsciiData object in the SExtractor format, change to plain format and check the output.

>>> SExample = asciidata.open('SExample.cat')
>>> print SExample
# 1  NUMBER  Running object number
# 2  XWIN_IMAGE  Windowed position estimate along x  [pixel]
# 3  YWIN_IMAGE  Windowed position estimate along y  [pixel]
# 4  ERRY2WIN_IMAGE  Variance of windowed pos along y [pixel**2]
# 5  AWIN_IMAGE  Windowed profile RMS along major axis  [pixel]
# 6  ERRAWIN_IMAGE  RMS windowed pos error along major axis  [pixel]
# 7  BWIN_IMAGE  Windowed profile RMS along minor axis  [pixel]
# 8  ERRBWIN_IMAGE  RMS windowed pos error along minor axis  [pixel]
# 9  MAG_AUTO  Kron-like elliptical aperture magnitude  [mag]
# 10 MAGERR_AUTO  RMS error for AUTO magnitude  [mag]
# 11 CLASS_STAR  S/G classifier output
    1  100.523  11.911  2.783  0.0693  2.078  0.0688 -5.3246  0.0416  0.00    19
    2  100.660  4.872  7.005  0.1261  3.742  0.0989 -6.4538  0.0214  0.00    27
    3  131.046  10.382  1.965  0.0681  1.714  0.0663 -4.6836  0.0524  0.00    17
    4  338.959  4.966  11.439  0.1704  4.337  0.1450 -7.1747  0.0173  0.00    25
    5  166.280  3.956  1.801  0.0812  1.665  0.0769 -4.0865  0.0621  0.00    25
>>> SExample.toplain()
>>> print SExample
    1  100.523  11.911  2.783  0.0693  2.078  0.0688 -5.3246  0.0416  0.00    19
    2  100.660  4.872  7.005  0.1261  3.742  0.0989 -6.4538  0.0214  0.00    27
    3  131.046  10.382  1.965  0.0681  1.714  0.0663 -4.6836  0.0524  0.00    17
    4  338.959  4.966  11.439  0.1704  4.337  0.1450 -7.1747  0.0173  0.00    25
    5  166.280  3.956  1.801  0.0812  1.665  0.0769 -4.0865  0.0621  0.00    25

4.2.26 AsciiData method toSExtractor()

This method changes the format of the AsciiData object to 'SExtractor'. This means that for all output to the screen or to a file the column info precedes the table data.

Usage
adata_object.toSExtractor()

Parameters
-

Return
-

Examples

Load a plain AsciiData object, change to SExtractor format and write it to a new file. Examine the output on the shell.

>>> example = asciidata.open('foo.txt')
>>> print example
    1    stars  1.0
    2 galaxies  2.0
    3     qsos  3.0
>>> example[0].rename('NUM')
>>> example[1].rename('CLASS')
>>> example[2].rename('MAG')
>>> example.toSExtractor()
>>> example.writeto('bar.txt')
>>>
~> more bar.txt
# 1  NUM
# 2  CLASS
# 3  MAG
    1    stars  1.0
    2 galaxies  2.0
    3     qsos  3.0

4.2.27 AsciiData method tofits()

The method transforms an AsciiData instance to a fits-table extension. This extension might be used with other extensions to build a multi-extension fits-file.
Please use the AsciiData method writetofits() (see Sect. 4.2.5) to make both, the conversions and storing as a fits-file onto hard disk in one step.
The module PyFITS (see http://www.stsci.edu/resources/software_hardware/pyfits) must be installed to run this method. The transformation fails if the AsciiData instance contains any Null elements (due to a limitation of the numpy and numarray objects, which are essential for the method).

Usage
aad_object.tofits()

Parameters
-

Return
- a table fits extension

Examples

Convert an AsciiData object to a fits-table extension and append it to an already existing fits-table (the example is executed in PyRAF):

--> catfits exa_table.fits
EXT#  FITSNAME      FILENAME              EXTVE DIMENS       BITPI OBJECT
0     exa_table.fit                                          16
1       BINTABLE    BEAM_1A                     14Fx55R            1
--> exa = asciidata.open('some_objects.cat')
--> tab_hdu = exa.tofits()
--> tab_all = pyfits.open('exa_table.fits', 'update')
--> tab_all.append(tab_hdu)
--> tab_all.close()
--> catfits exa_table.fits
EXT#  FITSNAME      FILENAME              EXTVE DIMENS       BITPI OBJECT
0     exa_table.fit                                          16
1       BINTABLE    BEAM_1A                     14Fx55R            1
2       BINTABLE                                5Fx3R
-->

4.3 The AsciiColumn class

The AsciiColumn class is the the second important class in the AstroAsciiData module. The AsciiColumn manages all column related issues, which means that even the actual data is stored in AsciiColumn objects. These AsciiColumn object are accessed via the AsciiData object, either specifying the column name (such as e.g. adata_object['diff1']) or the column index (such as e.g. adata_object[3]).

4.3.1 AsciiColumn data

AsciiColumn objects contain some information which is important to the user and can be used in the processing. Although it is possible, this class data should never be changed directly by the user. All book-keeping is done internally.

Data

colname string file name associated to the object

4.3.2 AsciiColumn method get

This method retrieves one list element of an AsciiColumn instance. The element is specified with the row number.

Usage
elem = acol_object[row]
or
elem = operator.getitem(acol_object, row)

Parameters

row int the row number of the entry to be replaced

Return
- the requested column element

Examples

Retrieve and print the first element of the AsciiColumn instance which is the third column of the AsciiData instance 'exa':

>>> exa = asciidata.open('some_objects.cat')
>>> print exa
#
# most important objects
#
    1  1.0  red  23.08932 -19.34509
    2  9.5 blue  23.59312 -19.94546
    3  3.5 blue  23.19843 -19.23571
>>> elem = exa[2][0]
>>> print elem
 red
>>>

4.3.3 AsciiData method set

This methods sets list members, which means elements, of an AsciiColumn instance. The list member to be changed is addressed via their row number.

Usage
acol_object[row] = an_entry
or
operator.setitem(acol_object, row, adata_column)

Parameters

row int the row number of the entry to be replaced

an_entry string/integer/float the data to replace the previous entry

Return
-

Examples

Replace the third entry of the column which is the third column in the AsciiData instance 'exa':

>>> print exa
#
# most important objects
#
    1  1.0  red  23.08932 -19.34509
    2  9.5 blue  23.59312 -19.94546
    3  3.5 blue  23.19843 -19.23571
>>> exa[2][2] = 'green'
>>> print exa
#
# most important objects
#
    1  1.0  red  23.08932 -19.34509
    2  9.5 blue  23.59312 -19.94546
    3  3.5 green  23.19843 -19.23571
>>>

4.3.4 AsciiColumn method len()

This method defines a length of an AsciiColumn instance, which equals the number of row in the AsciiColumn .

Usage
len(ac_object)

Parameters
-

Return
- the length (= number of rows) of the AsciiColumn

Examples

Print the length of the fifth column onto the screen:

>>> exa = asciidata.open('some_objects.cat')
>>> print exa
#
# most important objects
#
    1  1.0  red  23.08932 -19.34509
    2  9.5 blue  23.59312 -19.94546
    3  3.5 blue  23.19843 -19.23571
>>> print len(exa[4])
3
>>>

4.3.5 AsciiColumn iterator type

This defines an iterator over an AsciiColumn instance. The iteration is finished after acolumn_object.nrows calls and returns each element in subsequent calls. Please note that it is not possible to change these elements.

Usage
for element in acolumn_object:
...

Parameters
-

Return
-

Examples

Iterate over an AsciiColumn instance and print the elements:

>>> print exa
#
# most important objects
#
    1  1.0  red  23.08932 -19.34509
    2  9.5 blue  23.59312 -19.94546
    3  3.5 blue  23.19843 -19.23571
>>> acol = exa[4]
>>> for element in acol:
...     print element
...
-19.34509
-19.94546
-19.23571
>>>

4.3.6 AsciiColumn method copy()

This method generates a so-called deep copy of a column. This means the copy is not only a reference to an existing column, but a real copy with all data.

Usage
adata_object[colname].copy()

Parameters
-

Return
- the copy of the column

Examples

Copy the column 5 of AsciiData object 'example2' to column 2 of AsciiData object 'example1'

>>> print example1
#
# Some objects in the GOODS field
#
unknown  189.2207323  62.2357983  26.87  0.32
 galaxy            *  62.2376331  24.97  0.15
   star  189.1409453  62.1696844  25.30  0.12
 galaxy  188.9014716  62.2037839  25.95  0.20
>>> print example2
@
@ Some objects in the GOODS field
@
unknown   $  189.2207323 $  62.2357983 $  26.87 $  0.32
 galaxy   $            * $  62.2376331 $  24.97 $  0.15
   star   $  189.1409453 $  62.1696844 $  25.30 $     *
        * $  188.9014716 $           * $  25.95 $  0.20
>>> example1[1] = example2[4].copy()
>>> print example1
#
# Some objects in the GOODS field
#
unknown  0.32  62.2357983  26.87  0.32
 galaxy  0.15  62.2376331  24.97  0.15
   star     *  62.1696844  25.30  0.12
 galaxy  0.20  62.2037839  25.95  0.20

4.3.7 AsciiColumn method get_format()

The method returns the format of the AsciiColumn object The format description in AstroAsciiData is taken from Python. The Python Library Reference (Chapt. 2.3.6.2 in Python 2.5 ) gives a list of all possible formats.

Usage
adata_object[colname].get_format()

Parameters
-

Return
- the format of the AsciiColumn object

Examples

Get the format of AsciiColumn 0:

>>> print example2
@
@ Some objects in the GOODS field
@
unknown   $  189.2207323 $  62.2357983 $  26.87 $  0.32
 galaxy   $            * $  62.2376331 $  24.97 $  0.15
   star   $  189.1409453 $  62.1696844 $  25.30 $     *
        * $  188.9014716 $           * $  25.95 $  0.20
>>> example2[0].get_format()
'% 9s'

4.3.8 AsciiColumn method get_type()

The method returns the type of an AsciiColumn object

Usage
adata_object[colname].get_type()

Parameters
-

Return
- the type of the AsciiColumn

Examples

Get the type of AsciiColumn 0:

>>> print example2
@
@ Some objects in the GOODS field
@
unknown   $  189.2207323 $  62.2357983 $  26.87 $  0.32
 galaxy   $            * $  62.2376331 $  24.97 $  0.15
   star   $  189.1409453 $  62.1696844 $  25.30 $     *
        * $  188.9014716 $           * $  25.95 $  0.20
>>> example2[0].get_type()
<type 'str'>

4.3.9 AsciiColumn method get_nrows()

This method offers a way to derive the number of rows in a AsciiColumn instance.

Usage
acolumn_object.get_nrows()

Parameters
-

Return
- the number of rows

Examples

get the number of rows in the column named 'column1':

>>> exa = asciidata.open('sort_objects.cat')
>>> exa['column1'].get_nrows()
12
>>> print exa
    1     0     1     1
    2     1     0     3
    3     1     2     4
    4     0     0     2
    5     1     2     1
    6     0     0     3
    7     0     2     4
    8     1     1     2
    9     0     1     5
   10     1     2     6
   11     0     0     6
   12     1     1     5
>>>

4.3.10 AsciiColumn method get_unit()

The method returns the unit of an AsciiColumn instance. If there is not unit defined, a string with zero length is returned (`')

Usage
acolumn_object.get_unit()

Parameters
-

Return
- the unit of the column

Examples

Print the overview of the AsciiColumn with index 1:

test>more some_objects.cat
# 1 NUMBER          Running object number
# 2 X_Y
# 3 COLOUR
# 4 RA              Barycenter position along world x axis          [deg]
# 5 DEC             Barycenter position along world y axis          [deg]
#
# most important objects
#
1 1.0  red 23.08932 -19.34509
2 9.5 blue 23.59312 -19.94546
3 3.5 blue 23.19843 -19.23571
test>python
Python 2.4.2 (#1, Nov 10 2005, 11:34:38)
[GCC 3.3.3 20040412 (Red Hat Linux 3.3.3-7)] on linux2
Type "help", "copyright", "credits" or "license" for more information.
>>> import asciidata
>>> exa = asciidata.open('some_objects.cat')
>>> print exa['RA'].get_unit()
deg
>>>

4.3.11 AsciiColumn method info()

The method gives an overview on an AsciiColumn object including its type, format and the number of elements.

Its focus is on interactive work. All information can also be retrieved by other methods in a machine readable format.

Usage
adata_object[colname].info()

Parameters
-

Return
- the overview on the AsciiColumn object

Examples

Print the overview of the AsciiColumn with index 1:

>>> print example2
@
@ Some objects in the GOODS field
@
unknown   $  189.2207323 $  62.2357983 $  26.87 $  0.32
 galaxy   $            * $  62.2376331 $  24.97 $  0.15
   star   $  189.1409453 $  62.1696844 $  25.30 $     *
        * $  188.9014716 $           * $  25.95 $  0.20
>>> print example2[1].info()
Column name:        column2
Column type:        <type 'float'>
Column format:      ['% 11.7f', '%12s']
Column null value : ['*']

4.3.12 AsciiColumn method reformat()

The method gives a new format to an AsciiColumn object. Please note that the new format does not change the column content, but only the string representation of the content. The format description in AstroAsciiData is taken from Python. The Python Library Reference (Chapt. 2.3.6.2 in Python 2.5) gives a list of all possible formats.

Usage
adata_object[colname].reformat('newformat')

Parameters

new_format string the new format of the AsciiColumn

Return
-

Examples

Change the format of the AsciiColumn with index 1:

>>> print example2
@
@ Some objects in the GOODS field
@
unknown   $  189.2207323 $  62.2357983 $  26.87 $  0.32
 galaxy   $            * $  62.2376331 $  24.97 $  0.15
   star   $  189.1409453 $  62.1696844 $  25.30 $     *
        * $  188.9014716 $           * $  25.95 $  0.20
>>> example2[1].reformat('% 6.2f')
>>> print example2
@
@ Some objects in the GOODS field
@
unknown   $  189.22 $  62.2357983 $  26.87 $  0.32
 galaxy   $       * $  62.2376331 $  24.97 $  0.15
   star   $  189.14 $  62.1696844 $  25.30 $     *
        * $  188.90 $           * $  25.95 $  0.20

4.3.13 AsciiColumn method rename()

The method changes the name on AsciiColumn object.

Usage
adata_object[colname].rename('newname')

Parameters

newname string the filename to save the AsciiData object to

Return
-

Examples

Change the column name from 'column1' to 'newname':

>>> print example2[3].info()
Column name:        column4
Column type:        <type 'float'>
Column format:      ['% 5.2f', '%6s']
Column null value : ['*']

>>> example2[3].rename('newname')
>>> print example2[3].info()
Column name:        newname
Column type:        <type 'float'>
Column format:      ['% 5.2f', '%6s']
Column null value : ['*']

4.3.14 AsciiColumn method tonumarray()

The method converts the content of an AsciiData object into a numarray object. Note that this is only possible if there are no Null-entries in the column, since numarray would not allow these Null-entries.

Usage
adata_object[colname].tonumarray()

Parameters
-

Return
- the AsciiColumn content in a numarray object.

Examples

Convert the column with the index 3 to a numarray object:

>>> print example2
@
@ Some objects in the GOODS field
@
unknown   $  189.2207323 $  62.2357983 $  26.87 $  0.32
 galaxy   $            * $  62.2376331 $  24.97 $  0.15
   star   $  189.1409453 $  62.1696844 $  25.30 $     *
        * $  188.9014716 $           * $  25.95 $  0.20
>>> numarr =  example2[3].tonumarray()
>>> numarr
array([ 26.87,  24.97,  25.3 ,  25.95])

4.3.15 AsciiColumn method tonumpy()

The method converts the content of an AsciiData object into a numpy object. Columns without Null-entries are converted to numpy array objects, columns with Null-entries become a numpy masked arrays (see numpy manual for details).

Usage
adata_object[colname].tonumpy()

Parameters
-

Return
- the AsciiColumn content in a numpy (-masked) object.

Examples

Convert the column with index 3 to a numpy object:

>>> print example
@
@ Some objects in the GOODS field
@
unknown   $ 189.2207323$ 62.2357983$ 26.87$ 0.32
 galaxy   $        Null$ 62.2376331$ 24.97$ 0.15
   star   $ 189.1409453$ 62.1696844$ 25.30$ Null
      Null$ 188.9014716$       Null$ 25.95$ 0.20
>>> nump = example[3].tonumpy()
>>> print nump
[ 26.87  24.97  25.3   25.95]

Convert the column with index 2 to a numpy object. This column contains a Null-entry, thus it is converted to a masked array:

>>> print example
@
@ Some objects in the GOODS field
@
unknown   $ 189.2207323$ 62.2357983$ 26.87$ 0.32
 galaxy   $        Null$ 62.2376331$ 24.97$ 0.15
   star   $ 189.1409453$ 62.1696844$ 25.30$ Null
      Null$ 188.9014716$       Null$ 25.95$ 0.20
>>> nump = example[2].tonumpy()
>>> type(nump)
<class 'numpy.core.ma.MaskedArray'>
>>> nump[3]
array(data =
 999999,
      mask =
 True,
      fill_value=999999)

4.3.16 AsciiColumn method set_unit()

The method sets the unit for a given column. Already existing units are just replaced.

Usage
adata_object[colname].set_unit(acol_unit)

Parameters

acol_unit string the new column unit

Return
-

Examples

Set a unit for the column FLAGS:

>>> print sm
# 1  NUMBER  Running object number
# 2  X_IMAGE  Object position along x  [pixel]
# 3  Y_IMAGE  Object position along y  [pixel]
# 4  FLAGS  Extraction flags
    2  379.148  196.397     3
    3  177.377  199.843     4
    1  367.213  123.803     8
>>> sm['FLAGS'].set_unit('arbitrary')
>>> print sm
# 1  NUMBER  Running object number
# 2  X_IMAGE  Object position along x  [pixel]
# 3  Y_IMAGE  Object position along y  [pixel]
# 4  FLAGS  Extraction flags  [arbitrary]
    2  379.148  196.397     3
    3  177.377  199.843     4
    1  367.213  123.803     8
>>>

4.3.17 AsciiColumn method set_colcomment()

The method writes a comment for a column into the AsciiData header.

Usage
adata_object[colname].set_colcomment(acol_comment)

Parameters

acol_comment string the new column comment

Return
-

Examples

Set (in this case change) the column comment for the column FLAGS:

>>> print sm
# 1  NUMBER  Running object number
# 2  X_IMAGE  Object position along x  [pixel]
# 3  Y_IMAGE  Object position along y  [pixel]
# 4  FLAGS  Extraction flags  [arbitrary]
    2  379.148  196.397     3
    3  177.377  199.843     4
    1  367.213  123.803     8
>>> sm['FLAGS'].set_colcomment('Quality numbers')
>>> print sm
# 1  NUMBER  Running object number
# 2  X_IMAGE  Object position along x  [pixel]
# 3  Y_IMAGE  Object position along y  [pixel]
# 4  FLAGS  Quality numbers  [arbitrary]
    2  379.148  196.397     3
    3  177.377  199.843     4
    1  367.213  123.803     8
>>>

4.3.18 AsciiColumn method get_colcomment()

The method reads a column comment from an AsciiData column.

Usage
adata_object[colname].get_colcomment()

Parameters
-

Return
- the comment string of the column

Examples

Read and print the column comment of the column X_IMAGE:

>>> cocomm = sm['X_IMAGE'].get_colcomment()
>>> print cocomm
Object position along x
>>>

4.4 The Header class

The Header class manages the header of an AsciiData object. The header contains a list of comments. Any kind of meta-data such as column names are part of the columns and therefore located in the AsciiColumn (see Sect. 4.3) class. The header object is accessed through various methods to e.g. get or set items.

4.4.1 Header method get

The header class contains a method to get individual items from a header instance via their index.

Usage
header_entry = adata_object.header[index]
or
header_entry = operator.getitem(adata_object.header, index)

Parameters

index int the index of the item to retrieve

Return
- one entry of the header

Examples

Retrieve the second entry of this table header:

>>> print example
#
# most important sources!!
#
    1  1.0  red  23.08932 -19.34509
    2  9.5 blue  23.59312 -19.94546
    3  3.5 blue  23.19843 -19.23571
>>> header_entry = example.header[1]
>>> print header_entry
 most important sources!!

>>>

Access the third entry of this table header:

>>> print example
#
# most important sources!!
#
    1  1.0  red  23.08932 -19.34509
    2  9.5 blue  23.59312 -19.94546
    3  3.5 blue  23.19843 -19.23571
>>> example.header[2]
'\n'
>>>

4.4.2 Header method set

The header class contains a method to set individual items in a header. The item is specified via its index.

Usage
adata_object.header[index] = new_entry
or
header_entry = operator.setitem(adata_object.header, index, new_entry)

Parameters

index int the index of the item to be set

new_entry string the new content of the header item

Return
-

Examples

Change the second header item:

>>> print example
#
# most important sources!!
#
    1  1.0  red  23.08932 -19.34509
    2  9.5 blue  23.59312 -19.94546
    3  3.5 blue  23.19843 -19.23571
>>> example.header[1] = 'a new header entry?'
>>> print example
#
#a new header entry?
#
    1  1.0  red  23.08932 -19.34509
    2  9.5 blue  23.59312 -19.94546
    3  3.5 blue  23.19843 -19.23571
>>>

Change the third header item:

>>> print example
#
# most important sources!!
#
    1  1.0  red  23.08932 -19.34509
    2  9.5 blue  23.59312 -19.94546
    3  3.5 blue  23.19843 -19.23571
>>> example.header[2] = '   >>> dont forget leading spaces if desired!'
>>> print example
#
# most important sources!!
#   >>> dont forget leading spaces if desired!
    1  1.0  red  23.08932 -19.34509
    2  9.5 blue  23.59312 -19.94546
    3  3.5 blue  23.19843 -19.23571
>>>

4.4.3 Header method del

The header class contains a method to delete individual items in a header. The item is specified via its index.

Usage
del adata_object.header[index]
or
operator.delitem(adata_object.header, index)

Parameters

index int the index of the item to be deleted

Return
-

Examples

Delete the second header item:

>>> print example
#
# most important sources!!
#
    1  1.0  red  23.08932 -19.34509
    2  9.5 blue  23.59312 -19.94546
    3  3.5 blue  23.19843 -19.23571
>>> del example.header[1]
>>> print example
#
#
    1  1.0  red  23.08932 -19.34509
    2  9.5 blue  23.59312 -19.94546
    3  3.5 blue  23.19843 -19.23571
>>>

4.4.4 Header method str()

This method converts the entire AsciiHeader instance into a string. The print command called with an AsciiHeader instance as first parameter also prints the string created using this method str().

Usage
str(adata_object.header)

Parameters
-

Return
- the string representation of the AsciiHeader instance

Examples

Delete the second header item:

>>> print example
#
# most important sources!!
#
    1  1.0  red  23.08932 -19.34509
    2  9.5 blue  23.59312 -19.94546
    3  3.5 blue  23.19843 -19.23571
>>> print example.header
#
# most important sources!!
#

>>>

4.4.5 Header method len()

The method defines the length of an AsciiHeader instance, which equals the number of the comment entries. Please note that empty lines are are counted as well.

Usage
len(adata_object.header)

Parameters
-

Return
- the length of the AsciiHeader instance

Examples

Get the length of an AsciiHeader :

>>> print example
#
# most important sources!!
#
    1  1.0  red  23.08932 -19.34509
    2  9.5 blue  23.59312 -19.94546
    3  3.5 blue  23.19843 -19.23571
>>> header_length = len(example.header)
>>> header_length
3
>>>

4.4.6 Header iterator type

This defines an iterator over an AsciiHeader instance. The iteration is finished after len(adata_object.header) calls and returns each header element in subsequent calls. Please not that it is not possible to change these elements.

Usage
for element in adata_object.header:
...

Parameters
-

Return
-

Examples

Iterate over an AsciiHeader instance and print the elements:

>>> print example
@
@Some objects in the GOODS field
@ -classification
@ -RA
@ -DEC
@ -MAG
@ -extent
unknown   $ 189.2207323$ 62.2357983$ 26.87$ 0.32
 galaxy   $        Null$ 62.2376331$ 24.97$ 0.15
   star   $ 189.1409453$ 62.1696844$ 25.30$ Null
      Null$ 188.9014716$       Null$ 25.95$ 0.20
>>> for h_entry in example.header:
...     print h_entry.strip()
...

Some objects in the GOODS field
-classification
-RA
-DEC
-MAG
-extent
>>>

4.4.7 Header method reset()

The method deletes all entries from an AsciiHeader instance and provides a clean, empty header.

Usage
adata_object.header.reset()

Parameters
-

Return
-

Examples

Reset an AsciiHeader instance:

>>> print example
#
# most important sources!!
#
    1  1.0  red  23.08932 -19.34509
    2  9.5 blue  23.59312 -19.94546
    3  3.5 blue  23.19843 -19.23571
>>> example.header.reset()
>>> print example
    1  1.0  red  23.08932 -19.34509
    2  9.5 blue  23.59312 -19.94546
    3  3.5 blue  23.19843 -19.23571
>>>

4.4.8 Header method append()

The method appends a string or a list of strings to the header of an AsciiData object.

Usage
adata_object.header.append(hlist)

Parameters

hlist string the list of strings to be appended to the header

Return
-

Examples

Change the column name from 'column1' to 'newname':

>>> print example2
@
@ Some objects in the GOODS field
@
unknown   $  189.2207323 $  62.2357983 $  26.87 $  0.32
 galaxy   $            * $  62.2376331 $  24.97 $  0.15
   star   $  189.1409453 $  62.1696844 $  25.30 $     *
        * $  188.9014716 $           * $  25.95 $  0.20
>>> example2.header.append('Now a header line is appended!')
>>> print example2
@
@ Some objects in the GOODS field
@
@ Now a header line is appended!
unknown   $  189.2207323 $  62.2357983 $  26.87 $  0.32
 galaxy   $            * $  62.2376331 $  24.97 $  0.15
   star   $  189.1409453 $  62.1696844 $  25.30 $     *
        * $  188.9014716 $           * $  25.95 $  0.20
>>> example2.header.append("""And now we try to put
... even a set of lines
... into the header!!""")
>>> print example2
@
@ Some objects in the GOODS field
@
@ Now a header line is appended!
@ And now we try to put
@ even a set of lines
@ into the header!!
unknown   $  189.2207323 $  62.2357983 $  26.87 $  0.32
 galaxy   $            * $  62.2376331 $  24.97 $  0.15
   star   $  189.1409453 $  62.1696844 $  25.30 $     *
        * $  188.9014716 $           * $  25.95 $  0.20

$\begin{figure}\vbox{\include{index} }\end{figure}$

Next: About this document ... Up: AstroAsciiData 1.1 User Manual Previous: 3 All in one Contents

mkuemmel@eso.org

Name	Type	Default	Description
filename	string	-	the name of the ASCII
			table file to be loaded
null	string	['*','NULL', 'Null', 'None']	the character/string
			representing a null-entry
delimiter	string	`` ``	the delimiter separating
			columns
comment_char	string	'#'	the character/string
			indicating a comment

filename	string	file name associated to the object
ncols	int	number of columns
nrows	int	number of rows

col_spec	string/int	column specification, either by column name or column number
adata_column	AsciiColumn	the `AsciiColumn` instance to replace the previous column

html_name	string	the name of the html-file
tr_attr	string	attribute string for the tr-tag
td_attr	string	attribute string for the td-tag

colname	string/integer	the specification of the sort column
descending	integer	sort in ascending () or descending () order
ordered	integer	use the fast () algorithm or the slow ()
		which avoids unnecessary row swaps

start	int	the first row to be deleted
end	int	the first row not to be deleted

nrows	int	number of rows to be inserted
start	int	index position of the first inserted column

row	int	the row number of the entry to be replaced
an_entry	string/integer/float	the data to replace the previous entry

index	int	the index of the item to be set
new_entry	string	the new content of the header item