Документ взят из кэша поисковой машины. Адрес оригинального документа : http://www.stecf.org/software/PYTHONtools/astroasciidata/manual/asciidata_0.01.pdf Дата изменения: Wed May 10 11:51:00 2006 Дата индексирования: Tue Oct 2 04:40:13 2012 Кодировка: Поисковые слова: п п р р р р р р р р р р р р р р

User Manual version 0.01
M. Kummel (mkuemmel@eso.org), J. Haase (jhaase@eso.org) Ё Space Telescope - European Coordinating Facility 30 November 2005

Contents
1 Intro duction 2 Installation 3 All in one chapter 3.1 Working with existing data . . . . . . . . . . . . . . . . . . . . . 3.2 Creating an ASCII table from scratch . . . . . . . . . . . . . . . 4 The detailed description 4.1 Functions . . . . . . . . 4.1.1 open() . . . . . . 4.1.2 create() . . . . . 4.2 The AsciiData class . . 4.2.1 AsciiData data . 4.2.2 AsciiData method 4.2.3 AsciiData method 4.2.4 AsciiData method 4.2.5 AsciiData method 4.2.6 AsciiData method 4.2.7 AsciiData method 4.2.8 AsciiData method 4.2.9 AsciiData method 4.2.10 AsciiData method 4.2.11 AsciiData method 4.2.12 AsciiData method 4.2.13 AsciiData method 4.3 The AsciiColumn class . 3 4 5 5 8 11 11 11 12 13 13 14 15 16 17 18 18 19 20 21 22 23 24 24

......... ......... ......... ......... ......... append() . . . str() . . . . . del . . . . . . delete() . . . . find() . . . . . flush() . . . . info() . . . . . insert() . . . . newcomment() newdelimiter() newnull() . . . writeto() . . . .........

. . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . .

1


4.4

4.3.1 AsciiColumn metho 4.3.2 AsciiColumn metho 4.3.3 AsciiColumn metho 4.3.4 AsciiColumn metho 4.3.5 AsciiColumn metho 4.3.6 AsciiColumn metho 4.3.7 AsciiColumn metho The Header class . . . . . 4.4.1 Header method app

d copy() . . . . d get format() d get type() . . d info() . . . . d reformat() . d rename() . . d tonumarray() ......... end() . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

25 25 26 27 27 28 29 29 30

2


1

Intro duction

ASCII tables are one of the ma jor data exchange formats used in science. In astronomy ASCII tables are used for a variety of things like ob ject lists, line lists or even spectra. Every person working with astronomy has to deal with ASCII data, and there are various ways of doing so. Some use the awk scripting language, some transfer the ASCII tables to FITS tables and then work on the FITS data, some use IDL routines. Most of those approaches need individual efforts (such as preparing a format file for the transformation to FITS) whenever there is a new kind of ASCII table with e.g. a different number of columns. Within the AstroAsciiData pro ject we envision a module which can be used to work on all kinds of ASCII tables. The module should provide a convenient tool such that the user easily can: · read in ASCII tables; · manipulate table elements; · save the modified ASCII table; · combine several tables; · delete/add rows and columns. Python (www.python.org) is in the process of becomming the programming language of choice for astronomers, both for interactive data analysis as well as for large scale software development. A number of interfaces such as PyRAF (http://www.stsci.edu/resources/software hardware/pyraf) or PyFITS (http://www.stsci.edu/resources/software hardware/pyfits) have already been written to bridge the gap between widely used astronomical software packages, data formats and Python. This makes the development of the AstroAsciiData module for Python a natural choice. Within Python, the AstroAsciiData module may be used interactively, within small scripts, in data reduction tasks and even in data bases. In general, the ASCII tables used in astronomy have a relatively small size. As an example, the size of the Wide Field Camera catalogue of Hubble Ultra Deep Field is only 2.2 MB. Handling those amounts of data is not a time consuming task for modern day computers. As a consequence, computational speed is not a prime issue in software design and construction, and there was no attempt to implement a particularly fast module. The focus was rather to maximizing convenience and ensuring a shallow learning curve for the users. AstroAsciiData is a young and form, suggestions, critics, comments, come and will certainly contribute to The feedback should be sent directly AstroAsciiData@stecf.org. fresh software pro ject. Feedback in any development requests, is very much welimprove the next versions of the module. to the developers or to

3


2

Installation

The AstroAsciiData module requires Python 2.2 or later and the numarray (http://www.stsci.edu/resources/software hardware/numarray) module. It was developed on linux (SUSE, redhat) and Solaris 5.8, however there should be no problems installing it on any machine hosting Python. The current version 0.01 of AstroAsciiData is distributed as the source archive asciidata-0.01.tar.gz from the AstroAsciiData webpage at http://www.stecf.org/software/astroasciidata/. Installing the module is not difficult. Unpack the tarball with: > gunzip asciidata-0.01.tar.gz > tar -xvf asciidata-0.01.tar Then enter the the unpacked directory and do the usual: > cd asciidata-0.01 > python setup.py install After installation, some Unit Test are executed with: > python setup.py test If there are no errors reported in the Unit Tests, the proper working of the module is assured. In all classes and sub-modules the epydoc-conventions have been used in the inline documentation. In case that epydoc (http://epydoc.sourceforge.net/) is installed, the command > epydoc Lib/ creates webpages from the inline documenatation, which are written to the the directory './html'. This would be certainly a very good start for users whoe really want to find out what is behind the module and how it is built. In case that you just want to use the AstroAsciiData module, there is no need to look at its inline documentation.

4


3

All in one chapter

Reading documentation is no fun. Moreover the AstroAsciiData module promised to be convenient for users (see Sect. 1). This Section gives a fast introduction on all features of the AstroAsciiData module and how these features are used to work with ASCII tables. On the basis of some sample session the most important classes and methods are introduced without explicitly listing all their names and modes of usage. A complete and detailed overview on all AstroAsciiData classes and their methods is given in Section 4.

3.1

Working with existing data

This chapter shows how to load and work with the ASCII table 'example.txt'. This tables looks like: # # Some # unknown galaxy star galaxy objects in the GOODS field 189.2207323 189.1408929 189.1409453 188.9014716 62.2357983 62.2376331 62.1696844 62.2037839 26.87 24.97 25.30 25.95 0.32 0.15 0.12 0.20

Before actually loading the table, the AstroAsciiData module must be imported with: >>> import asciidata The ASCII table is loaded with: >>> example = asciidata.open('example.txt') Just to check whether the table was loaded correctly you do: >>> print str(example) # # Some objects in the GOODS field # unknown 189.2207323 62.2357983 galaxy 189.1408929 62.2376331 star 189.1409453 62.1696844 galaxy 188.9014716 62.2037839

26.87 24.97 25.30 25.95

0.32 0.15 0.12 0.20

As a first application, you want to compute the average from the numbers in the second and third row:

5


>>> sum1=0.0 >>> sum2=0.0 >>> for index in range(example.nrows): ... sum1 += example[1][index] ... sum2 += example[2][index] ... >>> ave1 = sum1/example.nrows >>> ave2 = sum2/example.nrows >>> print ave1, ave2 189.101010525 62.211724925 Please note that indices start with 0, so the first row in the first column is example[0][0]. You want to change the table values, but before that perhaps it would be wise to keep a copy of the original ASCII table : >>> example.writeto('example_orig.txt') This gives you a file 'example orig.txt', which is identical to the original 'example.txt'. Now you may want to compute and save the differences between the average and the individual values:
>>> for index in range(example.nr ... example['diff1'][index] = ... example['diff2'][index] = ... >>> print str(example) # # Some objects in the GOODS field # unknown 189.2207323 62.2357983 galaxy 189.1408929 62.2376331 star 189.1409453 62.1696844 galaxy 188.9014716 62.2037839 ows): example[1][index] - ave1 example[2][index] - ave2

26.87 24.97 25.30 25.95

0.32 1.197218e-01 2.407338e-02 0.15 3.988237e-02 2.590817e-02 0.12 3.993477e-02 -4.204052e-02 0.20 -1.995389e-01 -7.941025e-03

There are two new columns, which were created by addressing elements in an unknown column with the name 'diff1' and 'diff2'. To remember the new columns and their meaning, you would like to put a note into the table header:
>>> example.header.append('Nov 16 2005: computed and stored differences!') >>> print str(example) # # Some objects in the GOODS field #

6


# Nov 16 unknown galaxy star galaxy

2005: computed and store 189.2207323 62.2357983 189.1408929 62.2376331 189.1409453 62.1696844 188.9014716 62.2037839

d differences! 26.87 0.32 1.197218e-01 2.407338e-02 24.97 0.15 3.988237e-02 2.590817e-02 25.30 0.12 3.993477e-02 -4.204052e-02 25.95 0.20 -1.995389e-01 -7.941025e-03

There is a new commented line at the beginning of the table with your note. That was enough for now, and the best is to save the modified ASCII table: >>> example.flush() Now the file 'example.txt' also has the two new columns. OK, there is a column with the name 'diff1' and another named 'diff2', but what are the names of the original columns? To get all information, just type:
>>> print example.info() File: example.txt Ncols: 7 Nrows: 4 Delimiter: None Null value: ['Null', 'NULL', 'Non Comment: # Column name: column1 Column type: Column format: ['% 7s', '%7s Column null value : ['Null'] Column name: column2 Column type:
e', '*']

']

> %12s']

> %11s']

> 6s']

> 5s']

> %13s']

7


Column Column Column Column Column

null value : ['Null'] name: diff2 type: format: ['% 12.6e', '%13s'] null value : ['Null']

So the original columns had default names such as 'column1', 'column2', ... Moreover the method info() returns the column type and format for every column .

3.2

Creating an ASCI I table from scratch

In this Section an ASCII table is created from scratch using functions classes and methods in the AstroAsciiData module. To create an empty AsciiData ob ject, import the AstroAsciiData module and type:
>>> import asciidata >>> example2 = asciidata.create(4,10) >>> print example2 Null Null Null Null Null Null Null Null Null Null Null Null Null Null Null Null Null Null Null Null Null Null Null Null Null Null Null Null Null Null

Nu Nu Nu Nu Nu Nu Nu Nu Nu Nu

ll ll ll ll ll ll ll ll ll ll

The ob ject has four columns with ten rows, all empty so far. The first column should contain an index:
>>> for index in range(example2.n ... example2[0][index] = inde ... >>> print example2 1 Null Null 2 Null Null 3 Null Null 4 Null Null 5 Null Null 6 Null Null 7 Null Null 8 Null Null 9 Null Null 10 Null Null rows): x+1

Null Null Null Null Null Null Null Null Null Null

8


For convenience the index starts with 1. Now the rest is filled using a functional form:
>>> for cindex in range(1, example2.ncols): ... for rindex in range(example2.nrows): ... example2[cindex][rindex] = 0.3*float(example2[0][rindex])**cindex ... >>> print example2 1 3.000000e-01 3.000000e-01 3.000000e-01 2 6.000000e-01 1.200000e+00 2.400000e+00 3 9.000000e-01 2.700000e+00 8.100000e+00 4 1.200000e+00 4.800000e+00 1.920000e+01 5 1.500000e+00 7.500000e+00 3.750000e+01 6 1.800000e+00 1.080000e+01 6.480000e+01 7 2.100000e+00 1.470000e+01 1.029000e+02 8 2.400000e+00 1.920000e+01 1.536000e+02 9 2.700000e+00 2.430000e+01 2.187000e+02 10 3.000000e+00 3.000000e+01 3.000000e+02

Please note that the column type of the first column is int since only integer type data was entered. In all other columns numbers of type float were entered, hence their column type is also float. Inserting one element with a more generic data type changes the type of the whole column:
>>> example2[0][1] = 2.0 >>> print example2 1.000000e+00 3.000000e-01 2.000000e+00 6.000000e-01 3.000000e+00 9.000000e-01 4.000000e+00 1.200000e+00 5.000000e+00 1.500000e+00 6.000000e+00 1.800000e+00 7.000000e+00 2.100000e+00 8.000000e+00 2.400000e+00 9.000000e+00 2.700000e+00 1.000000e+01 3.000000e+00

3.0 1.2 2.7 4.8 7.5 1.0 1.4 1.9 2.4 3.0

00000e-01 00000e+00 00000e+00 00000e+00 00000e+00 80000e+01 70000e+01 20000e+01 30000e+01 00000e+01

3.000000e-01 2.400000e+00 8.100000e+00 1.920000e+01 3.750000e+01 6.480000e+01 1.029000e+02 1.536000e+02 2.187000e+02 3.000000e+02

Now the first column is of type float as well. Eventually, some comments are added for specific rows:
>>> newcol = example2.append('comment') >>> example2[newcol][0] = 'small!' >>> example2[newcol][2] = 'bigger!' >>> example2[newcol][7] = 'Huge!' >>> print example2 1.000000e+00 3.000000e-01 3.000000e-01

3.000000e-01 small!

9


2.000000e+00 3.000000e+00 4.000000e+00 5.000000e+00 6.000000e+00 7.000000e+00 8.000000e+00 9.000000e+00 1.000000e+01

6.000000e-01 9.000000e-01 1.200000e+00 1.500000e+00 1.800000e+00 2.100000e+00 2.400000e+00 2.700000e+00 3.000000e+00

1.2 2.7 4.8 7.5 1.0 1.4 1.9 2.4 3.0

00000e+00 00000e+00 00000e+00 00000e+00 80000e+01 70000e+01 20000e+01 30000e+01 00000e+01

2.400000e+00 Null 8.100000e+00 bigger! 1.920000e+01 Null 3.750000e+01 Null 6.480000e+01 Null 1.029000e+02 Null 1.536000e+02 Huge! 2.187000e+02 Null 3.000000e+02 Null

Obviously it also is possible to create a new column using the AsciiData append() method. This method returns the column number, which then can be used to fill the new column. Now its time to safe the AsciiData ob ject:
>>> example2.flush() Traceback (most recent call last): File "", line 1, in ? File ".../site-packages/asciidata/asciidata.py", line 279, in flush raise "No filename given. Use 'writeto()' instead." No filename given. Use 'writeto()' instead. >>> example2.writeto('example2.txt')

Since the ob ject was created from scratch, there is no filename associated with and the method flush() can not be used. The method writeto() must be used instead!

10


4

The detailed description

The AstroAsciiData module was developed in Python using an Ob ject 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 ob jects, 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 ob ject by either opening and loading an existing ASCII file (open()) or creating an empty AsciiData ob ject from scratch (create()). 4.1.1 op en()

This function loads an existing ASCII table file. An AsciiData ob ject is created and the data stored in the ASCII table is transferred to the AsciiData ob ject. 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=None) Parameters filename null delimiter comment strin strin strin strin g g g g the the the the name of the ASCII table file to be loaded character/string representing a null-entry delimiter separating the columns character/string indicating a comment

Return - an AsciiData ob ject Examples 1. Load the file 'example.txt' and print the result. The file 'example.txt looks like:
#

11


# Some objects in the # unknown 189.2207323 galaxy 189.1408929 star 189.1409453 galaxy 188.9014716

GOODS field 62.2357983 62.2376331 62.1696844 62.2037839 26.87 24.97 25.30 25.95 0.32 0.15 0.12 0.20

The command sequence is:
>>> example = asciidata.open('exa >>> print example # # Some objects in the GOODS field # unknown 189.2207323 62.2357983 galaxy 189.1408929 62.2376331 star 189.1409453 62.1696844 galaxy 188.9014716 62.2037839 mple.txt')

26.87 24.97 25.30 25.95

0.32 0.15 0.12 0.20

2. Load the file 'example2.txt' and print the results. 'example2.txt':
@ @ Some objects in the @ unknown $ 189.2207323 galaxy $ * star $ 189.1409453 * $ 188.9014716

GOODS field $ 62.2357983 $ 62.2376331 $ 62.1696844 $ * $ $ $ $ 26.87 24.97 25.30 25.95 $ 0.32 $ 0.15 $* $ 0.20

Load and print:
>>> example2 = asciidata.open('example2.txt', null='*', \ delimiter='$', comment='@') >>> 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()

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

12


ncols nrows null delimiter

int int string string

number of columns to be created number of rows to be created the character/string representing a null-entry the delimiter separating the columns

Return - an AsciiData ob ject Examples 1. Create an AsciiData ob ject with 3 columns and 2 rows, print the result: >>> example3 = asciidata.create(3,2) >>> print (example3) Null Null Null Null Null Null 2. As in 1., but use a different delimiter and NULL value, print the result: >>> example4 = asciidata.create(3,2,delimiter='|', null='<*>') >>> print (example4) <*> | <*> | <*> <*> | <*> | <*>

4.2

The AsciiData class

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

AsciiData ob jects 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 ncols nrows Examples 1. Go over all table entries an store values: string int int file name associated to the ob ject number of columns number of rows

13


>>> example3 = asciidata.create(1 >>> for cindex in range(example3. ... for rindex in range(examp ... example3[cindex][ ...

00,100) ncols): le3.nrows): rindex] = do_something(rindex, rindex)

2. 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 metho d app end()

Invoking this method is the formal way to append an new column to and AsciiData ob ject. 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 ob ject.append(col name) Parameters col name string

the name of the new column

Return - the number of the columns created Examples 1. Append a new column 'newcolumn' to the AsciiData ob ject:
>>> print example2 @ @ Some objects in the GOODS field @ unknown $ 189.2207323 $ 62.2357983 $ galaxy $ * $ 62.2376331 $ star $ 189.1409453 $ 62.1696844 $ * $ 188.9014716 $ *$ >>> cnum = example2.append('newcolumn') >>> print cnum 5 >>> print example2 @

26.87 24.97 25.30 25.95

$ $ $ $

0.32 0.15 * 0.20

14


@ Some objects in the GOODS field @ unknown $ 189.2207323 $ 62.2357983 galaxy $ * $ 62.2376331 star $ 189.1409453 $ 62.1696844 * $ 188.9014716 $ *

$ $ $ $

26.87 24.97 25.30 25.95

$ $ $ $

0.32 0.15 * 0.20

$ $ $ $

* * * *

4.2.3

AsciiData metho d str()

This methods converts the whole AsciiData ob ject into a string. Columns are separated with the delimiter, empty elements are represented by the Nullstring and the header is indicated by a comment-string at the beginning. In this method the class ob ject appears as a function argument and the method call is different from the usual form such as in Sect. 4.2.2 Usage str(adata ob ject) Parameters Return - the string representing the AsciiData ob ject Examples 1. Print an AsciiData ob ject to the screen: >>> print str(example2) @ @ Some objects in the GOODS field @ unknown $ 189.2207323 $ 62.2357983 galaxy $ * $ 62.2376331 star $ 189.1409453 $ 62.1696844 * $ 188.9014716 $ *

$ $ $ $

26.87 24.97 25.30 25.95

$ $ $ $

0.32 0.15 * 0.20

2. Store the sting representation of an AsciiData ob ject: >>> big_string = str(example2) >>> print big_string @ @ Some objects in the GOODS field @ unknown $ 189.2207323 $ 62.2357983 galaxy $ * $ 62.2376331 star $ 189.1409453 $ 62.1696844 * $ 188.9014716 $ * 15

$ $ $ $

26.87 24.97 25.30 25.95

$ $ $ $

0.32 0.15 * 0.20


4.2.4

AsciiData metho d 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.2 or 4.2.5. Usage del adata ob j[col spec] Parameters col spec string/int Return Examples 1. Delete the column with name 'column1': >>> print example2 @ @ Some objects in the GOODS field @ unknown $ 189.2207323 $ 62.2357983 galaxy $ * $ 62.2376331 star $ 189.1409453 $ 62.1696844 * $ 188.9014716 $ * >>> del example2['column5'] >>> print example2 @ @ Some objects in the GOODS field @ unknown $ 189.2207323 $ 62.2357983 galaxy $ * $ 62.2376331 star $ 189.1409453 $ 62.1696844 * $ 188.9014716 $ * 2. Delete the second column: >>> print example2 @ @ Some objects in the GOODS field @ unknown $ 189.2207323 $ 62.2357983 $ galaxy $ * $ 62.2376331 $ star $ 189.1409453 $ 62.1696844 $

column specification either by name or by the column number

$ $ $ $

26.87 24.97 25.30 25.95

$ $ $ $

0.32 0.15 * 0.20

$ $ $ $

26.87 24.97 25.30 25.95

26.87 $ 24.97 $ 25.30 $

0.32 0.15 *

16


* $ 188.9014716 $ >>> del example2[1] >>> print example2 @ @ Some objects in the GOODS field @ unknown $ 62.2357983 $ 26.87 $ galaxy $ 62.2376331 $ 24.97 $ star $ 62.1696844 $ 25.30 $ *$ * $ 25.95 $ 4.2.5 AsciiData metho d delete()

*$

25.95 $

0.20

0.32 0.15 * 0.20

This method deletes rows in an AsciiData ob ject. The rows to be deleted are specified in the parameters. Usage adata ob j.delete(start, end) Parameters start int the first row to be deleted end int the first row not to be deleted Return Examples 1. Delete the row with index 1: >>> print example2 @ @ Some objects in the GOODS @ unknown $ 189.2207323 $ galaxy $ *$ star $ 189.1409453 $ * $ 188.9014716 $ >>> example2.delete(1,2) >>> print example2 @ @ Some objects in the GOODS @ unknown $ 189.2207323 $ star $ 189.1409453 $ * $ 188.9014716 $

field 62.2357983 62.2376331 62.1696844 * $ $ $ $ 26.87 24.97 25.30 25.95 $ $ $ $ 0.32 0.15 * 0.20

field 62.2357983 $ 62.1696844 $ *$ 26.87 $ 25.30 $ 25.95 $ 0.32 * 0.20

17


4.2.6

AsciiData metho d 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 ob j.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 1. Search for the column with name 'column3': >>> example2 = asciidata.open('example2.txt', null='*', \ delimiter='$', comment='@') >>> cnum = example2.find('column2') >>> cnum 1 >>> 2. Search for the column with the name 'not there': >>> example2 = asciidata.open('example2.txt', null='*', \ delimiter='$', comment='@') >>> cnum = example2.find('not_there') >>> cnum -1 >>> Obviously the AsciiData ob ject example2 does not have a column with this name. 4.2.7 AsciiData metho d flush()

The method updates the associated file with the newest version of the AsciiData ob ject. Usage adata ob j.flush() Parameters

18


Return Examples 1. Manipulate an AsciiData ob ject and update the file:
work>more example.txt # # Some objects in the GOODS field # unknown 189.2207323 62.2357983 galaxy 189.1408929 62.2376331 star 189.1409453 62.1696844 galaxy 188.9014716 62.2037839 work>python Python 2.4.2 (#5, Oct 21 2005, 11 [GCC 3.3.2] on sunos5 Type "help", "copyright", "credit >>> import asciidata >>> example = asciidata.open('exa >>> del example[4] >>> example.flush() >>> work>more example.txt # # Some objects in the GOODS field # unknown 189.2207323 62.2357983 galaxy 189.1408929 62.2376331 star 189.1409453 62.1696844 galaxy 188.9014716 62.2037839

26.87 24.97 25.30 25.95 :12:03)

0.32 0.15 0.12 0.20

s" or "license" for more information. mple.txt')

26.87 24.97 25.30 25.95

4.2.8

AsciiData metho d info()

The method returns an informative overview on the AsciiData ob ject as a string. This overview gives the user a quick insight into e.g. the column names of the ob ject. A further use of the information within programmes is not recommended, since all information can also be retrieved by other in a machine usable format using other methods. The overview contains: · the name of the file associated to the AsciiData ob ject; · the number of columns; · the number of rows; · the delimiter to separate columns; 19


· the representing Null-values; · the comment string. In addition, for every column the column name, type, format and Null-representation is given. Usage adata ob ject.info() Parameters Return Examples 1. Print the information on an AsciiData ob ject onto the screen:
>>> example = asciidata.open('exa >>> print example.info() File: example.txt Ncols: 4 Nrows: 4 Delimiter: None Null value: ['Null', 'NULL', 'Non Comment: # Column name: column1 Column type: Column format: ['% 7s', '%7s Column null value : ['Null'] Column name: column2 Column type:
e', '*']

']

> %12s']

> %11s']

> 6s']

4.2.9

AsciiData metho d insert()

This method inserts rows into all columns of the AsciiData ob ject. The second parameter controls where exactly the new, empty rows are positioned. The 20


number specified there the first empty row will be . Usage adata ob ject.insert(nrows, start) Parameters nrows int start int Return Examples 1. Insert two rows such that the first row will have the index 1:
>>> print example2 @ @ Some objects in the GOODS @ unknown $ 189.2207323 $ galaxy $ *$ star $ 189.1409453 $ * $ 188.9014716 $ >>> example2.insert(2,1) >>> print example2 @ @ Some objects in the GOODS @ unknown $ 189.2207323 $ *$ *$ *$ *$ galaxy $ *$ star $ 189.1409453 $ * $ 188.9014716 $

number of rows to be inserted index position of the first inserted column

field 62.2357983 62.2376331 62.1696844 * $ $ $ $ 26.87 24.97 25.30 25.95 $ $ $ $ 0.32 0.15 * 0.20

field 62.2357983 * * 62.2376331 62.1696844 * $ $ $ $ $ $ 26.87 * * 24.97 25.30 25.95 $ $ $ $ $ $ 0.32 * * 0.15 * 0.20

4.2.10

AsciiData metho d newcomment()

The method defines a new comment string for an AsciiData ob ject. Usage adata ob ject.newcomment(comment) Parameters comment string Return

the string to indicate a comment

21


Examples 1. Change the comment sign from '@' to ' !':
>>> print example2 @ @ Some objects in the GOODS field @ unknown $ 189.2207323 $ 62.2357983 galaxy $ * $ 62.2376331 star $ 189.1409453 $ 62.1696844 * $ 188.9014716 $ * >>> example2.newcomment('!!') >>> print example2 !! !! Some objects in the GOODS field !! unknown $ 189.2207323 $ 62.2357983 galaxy $ * $ 62.2376331 star $ 189.1409453 $ 62.1696844 * $ 188.9014716 $ *

$ $ $ $

26.87 24.97 25.30 25.95

$ $ $ $

0.32 0.15 * 0.20

$ $ $ $

26.87 24.97 25.30 25.95

$ $ $ $

0.32 0.15 * 0.20

4.2.11

AsciiData metho d newdelimiter()

This method specifies a new delimiter for an AsciiData ob ject. Usage adata ob ject.newdelimiter(delimiter) Parameters delimiter string Return Examples 1. Change the delimiter sign from '$' to '<>':
>>> print example2 !! !! Some objects in the GOODS field !! unknown $ 189.2207323 $ 62.2357983 $ galaxy $ * $ 62.2376331 $ star $ 189.1409453 $ 62.1696844 $

the new delimiter to separate columns

26.87 $ 24.97 $ 25.30 $

0.32 0.15 *

22


* $ 188.9014716 $ *$ >>> example2.newdelimiter('<>') >>> print example2 !! !! Some objects in the GOODS field !! unknown <> 189.2207323 <> 62.2357983 galaxy <> * <> 62.2376331 star <> 189.1409453 <> 62.1696844 * <> 188.9014716 <> *

25.95 $

0.20

<> <> <> <>

26.87 24.97 25.30 25.95

<> <> <> <>

0.32 0.15 * 0.20

4.2.12

AsciiData metho d newnull()

The method specifies a new string to represent Null-entries in an AsciiData ob ject. Usage adata ob ject.newnull(newnull) Parameters newnull string Return Examples 1. Change the Null representation from '*' to 'NaN':
>>> print example2 @ @ Some objects in the GOODS @ unknown $ 189.2207323 $ galaxy $ *$ star $ 189.1409453 $ * $ 188.9014716 $ >>> example2.newnull('NaN') >>> print example2 @ @ Some objects in the GOODS @ unknown $ 189.2207323 $ galaxy $ NaN $ star $ 189.1409453 $ NaN $ 188.9014716 $

the representation for Null-entries

field 62.2357983 62.2376331 62.1696844 * $ $ $ $ 26.87 24.97 25.30 25.95 $ $ $ $ 0.32 0.15 * 0.20

field 62.2357983 62.2376331 62.1696844 NaN $ $ $ $ 26.87 24.97 25.30 25.95 $ $ $ $ 0.32 0.15 NaN 0.20

23


4.2.13

AsciiData metho d writeto()

Write the AsciiData ob ject to a file. The file name is given in a parameter. Usage adata ob ject.writeto(filename) Parameters filename string Return Examples 1. Write an AsciiData ob ject to the file 'newfile.txt':
>>> print example2 @ @ Some objects in the GOODS field @ unknown $ 189.2207323 $ 62.2357983 galaxy $ * $ 62.2376331 star $ 189.1409453 $ 62.1696844 * $ 188.9014716 $ * >>> example2.writeto('newfile.txt') >>> > more newfile.txt @ @ Some objects in the GOODS field @ unknown $ 189.2207323 $ 62.2357983 galaxy $ * $ 62.2376331 star $ 189.1409453 $ 62.1696844 * $ 188.9014716 $ *

the filename to save the AsciiData ob ject to

$ $ $ $

26.87 24.97 25.30 25.95

$ $ $ $

0.32 0.15 * 0.20

$ $ $ $

26.87 24.97 25.30 25.95

$ $ $ $

0.32 0.15 * 0.20

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 ob jects. These AsciiColumn ob ject are accessed via the AsciiData ob ject, either specifying the column name (such as e.g. adata_object['diff1']) or the column index (such as e.g. adata_object[3]).

24


4.3.1

AsciiColumn metho d 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 ob ject[colname].copy() Parameters Return - the copy of the column Examples 1. Copy the column 5 of AsciiData ob ject 'example2' to column 2 of AsciiData ob ject 'example1'
>>> print example1 # # 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 galaxy 188.9014716 62.2037839 25.95 >>> print example2 @ @ Some objects in the GOODS field @ unknown $ 189.2207323 $ 62.2357983 $ galaxy $ * $ 62.2376331 $ star $ 189.1409453 $ 62.1696844 $ * $ 188.9014716 $ *$ >>> 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

0.32 0.15 0.12 0.20

26.87 24.97 25.30 25.95

$ $ $ $

0.32 0.15 * 0.20

4.3.2

AsciiColumn metho d get format()

The method returns the format of the AsciiColumn ob ject The format description in AstroAsciiData is taken from Python. The Python Library Reference 25


(Chapt. 2.3.6.2 in Python 2.4 ) gives a list of all possible formats. Usage adata ob ject[colname].get format() Parameters Return - the format of the AsciiColumn ob ject Examples 1. Get the format of AsciiColumn 0:
>>> print example2 @ @ Some objects in the GOODS field @ unknown $ 189.2207323 $ 62.2357983 galaxy $ * $ 62.2376331 star $ 189.1409453 $ 62.1696844 * $ 188.9014716 $ * >>> example2[0].get_format() '% 9s'

$ $ $ $

26.87 24.97 25.30 25.95

$ $ $ $

0.32 0.15 * 0.20

4.3.3

AsciiColumn metho d get typ e()

The method returns the type of an AsciiColumn ob ject Usage adata ob ject[colname].get type() Parameters Return - the type of the AsciiColumn Examples 1. Get the type of AsciiColumn 0:
>>> print example2 @ @ Some objects in the GOODS field @ unknown $ 189.2207323 $ 62.2357983 $

26.87 $

0.32

26


$ *$ $ 189.1409453 $ * $ 188.9014716 $ >>> example2[0].get_type()

galaxy star

62.2376331 $ 62.1696844 $ *$

24.97 $ 25.30 $ 25.95 $

0.15 * 0.20

4.3.4

AsciiColumn metho d info()

The method gives an overview on an AsciiColumn ob ject including its type, format and the number of elements. Usage adata ob ject[colname].info() Parameters Return - the overview on the AsciiColumn ob ject Examples 1. Print the overview of the AsciiColumn with index 1:
>>> print example2 @ @ Some objects in the GOODS field @ unknown $ 189.2207323 $ 62.2357983 $ galaxy $ * $ 62.2376331 $ star $ 189.1409453 $ 62.1696844 $ * $ 188.9014716 $ *$ >>> print example2[1].info() Column name: column2 Column type: Column format: ['% 11.7f', '%12s'] Column null value : ['*']

26.87 24.97 25.30 25.95

$ $ $ $

0.32 0.15 * 0.20

4.3.5

AsciiColumn metho d reformat()

The method gives a new format to an AsciiColumn ob ject. 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.4 ) gives a list of all possible formats. Usage

27


adata ob ject[colname].reformat('newformat') Parameters new format Return Examples 1. 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

string

the new format of the AsciiColumn

4.3.6

AsciiColumn metho d rename()

The method changes the name on AsciiColumn ob ject. Usage adata ob ject[colname].rename('newname') Parameters newname string Return Examples 1. Change the column name from 'column1' to 'newname':
>>> print example2[3].info()

the filename to save the AsciiData ob ject to

28


Column Column Column Column

name: type: format: null value :

column4 ['% 5.2f', '%6s'] ['*']

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

4.3.7

AsciiColumn metho d tonumarray()

The method converts the content of an AsciiData ob ject 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 ob ject[colname].tonumarray() Parameters Return - the AsciiColumn content in a numarray ob ject. Examples 1. Change the column name from 'column1' to 'newname':
>>> print example2 @ @ Some objects in the GOODS field @ unknown $ 189.2207323 $ 62.2357983 $ galaxy $ * $ 62.2376331 $ star $ 189.1409453 $ 62.1696844 $ * $ 188.9014716 $ *$ >>> numarr = example2[3].tonumarray() >>> numarr array([ 26.87, 24.97, 25.3 , 25.95])

26.87 24.97 25.30 25.95

$ $ $ $

0.32 0.15 * 0.20

4.4

The Header class

The Header class manages the header of an AsciiData ob ject. As of now, this header contains only a list of comments. Any kind of meta-data such as column names are not used. The header ob ject is accessed through the associated AsciiData ob ject, such as e.g. adata_object.header. 29


4.4.1

Header metho d app end()

The method appends a string or a list of strings to the header of an AsciiData ob ject. Usage adata ob ject.header.append(hlist) Parameters hlist string Return Examples 1. 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

the list of strings to be appended to the header

30


star

$ *$

189.1409453 $ 188.9014716 $

62.1696844 $ *$

25.30 $ 25.95 $

* 0.20

31


Index
append(), 10, 14, 30 AsciiColumn class, 24 AsciiData data, 13 AsciiData class, 13 AstroAsciiData webpage, 4 class data, 13 classes, 13, 24, 29 AsciiColumn, 24 AsciiData, 13 Header, 29 copy(), 25 del, 16 delete(), 17 epydoc, 4 find(), 18 flush(), 7, 10, 18 format, 27 functions, 11 create(), 12 open(), 11 get format(), 25 get type(), 26 Header class, 29 info(), 8, 19, 27 insert(), 20 installation, 4 linux, 4 redhat, 4 SUSE, 4 methods, 14­30 append(), 10 AsciiColumn copy(), 25 get format(), 25 get type(), 26 info(), 27 reformat(), 27 rename(), 28 tonumarray(), 29 AsciiData append(), 14 del, 16 delete(), 17 find(), 18 flush(), 18 info(), 19 insert(), 20 newcomment(), 21 newdelimiter(), 22 newnull(), 23 str(), 15 writeto(), 24 flush(), 7, 10 Header append(), 30 info(), 8 writeto(), 6, 10 newcomment(), 21 newdelimiter(), 22 newnull(), 23 numarray, 4 PyFITS, 3 PyRAF, 3 redhat, 4 reformat(), 27 rename(), 28 Solaris, 4 str(), 15 SUSE, 4 tonumarray(), 29 writeto(), 6, 10, 24

32