DataMatrix - a Pythonic implementation of R's data.frame

(C) 2008 Luca Beltrame

(C) 2008 Giovanni Marco Dall'Olio

Contents

1. License

2. Description

3. Requirements and installation

4. Usage

5. Credits

------------------------------------------------------------------------------

1. License

------------------------------------------------------------------------------

This program is distributed under the terms of the GNU General Public License

(GPL), version 2. This means that you can freely modify, copy and distribute

the program, under the terms of said license. The COPYING file gives a good

overview of what you can and can't do.

Although we hope that this program will be useful, but it is without ANY 

WARRANTY, without even the implied warranty of MERCHANTABILITY or FITNESS FOR 

A PARTICULAR PURPOSE.

------------------------------------------------------------------------------

2. Description

------------------------------------------------------------------------------

DataMatrix is a Python module that tries to emulate the behavior of the 

"data.frame" data structure of the R programming language. Data.frames are 

essentially tables that can be queried either by row or columns, or, in the 

presence of a header, even by column names. 

DataMatrix emulates this behavior by reading a text file (or file-like object) 

into a dictionary which in turn contains lists (the columns of the table).

For each row in the original text file, the columns contain a two item tuple, 

whose first item is the "row name" and the second the actual value for that 

row and column. 

Row names are a way to identify a row precisely (R uses it because some of its

operations return the names of the rows rather than their values) and are either

read from a specific column or a progressive numeric value otherwise.

DataMatrix objects can be queried with a dictionary-like syntax (e.g., 

matrix["column name"]), or by other methods.

------------------------------------------------------------------------------

3. Requirements and installation

------------------------------------------------------------------------------

DataMatrix requires Python, at least version 2.5. Python 2.6 is 

also known to work. It will likely not work on Python 3.0. It makes no use of

third-party modules so it should work on a standard Python install. Being a 

pure Python module, it will work reliably on Windows, Linux, *BSD and OS X. 

The latest version can be downloaded from 

http://www.dennogumi.org/projects-2/datamatrix  

both as a source distribution and a Windows installer. Windows user just need

to run the installer and follow the on-screen instructions. Other operating 

system users should download the source distribution, unpack it 

(tar xvzf filename) and then install it by issuing

python setup.py install

as root.

------------------------------------------------------------------------------

4. Usage

------------------------------------------------------------------------------

DataMatrix requires a file, or file-like object. We will use the StringIO 

module to create a virtual file, so you will have also idea of how an

input file should look like:

>>> from StringIO import StringIO

>>> fh = StringIO('''name surname

... Albert Einstein

... Groucho Marx

... ''')

The basic usage is to create a matrix object by passing a filehandler object

to datamatrix.DataMatrix:

>>> import datamatrix

>>> matrix = datamatrix.DataMatrix(fh, header=True, delimiter=' ')

Aside the file object, which is mandatory, there are a number of parameters 

that can be used. First of all, the "header" parameters tells DataMatrix if 

the file to read has a header or not, and if so, the header will be used to

assign names to the columns. Otherwise, it will just be a number for each

column.

To specify the column where row names are located, the row_names parameter is

used:

>>> matrix2 = datamatrix.DataMatrix(fh, header=True, row_names=1)

In this case, row names are obtained from the first column in the file.

DataMatrix uses the csv module to do its parsing, so you can specify

additional parameters to define the format of your data, such as delimiter

(the separator between fields), lineterminator and quoting (how to deal with

non-numeric fields). See the csv module documentation for additional details.

If you print a DataMatrix instance, you'll get some basic information:

>>> print matrix

File name: 

Column with identifier names: None (numeric)

No. of rows: 2

No. of columns: 2

Columns: name, surname

With the columns attribute you can view the columns as a list:

>>> print matrix.columns

['name', 'surname']

You can access specific rows with the getRow method:

>>> matrix.getRow(1)

['1', 'Albert', 'Einstein']

Or specific columns with the getColumn method:

>>> matrix.getColumn("surname",column_name=True)

['surname', 'Einstein', 'Marx']

To get a representation of your data, there is the view method:

>>> matrix.view()

1 Albert Einstein

2 Groucho Marx

Rows and columns can be appended with the append and appendRow methods,

respectively. In both cases, the item to be appended needs to be a sequence

(list or tuple) and must be as long as the other columns (when appending 

columns) or cover all the columns (when appending rows):

>>> profession = ["scientist", "comedian"] # new column

>>> matrix.append(profession, "Job")

>>> entry = ["Isaac", "Asimov", "writer"] # new row

>>> matrix.appendRow(entry,"3")

Notice that when you append a row and a column you must specify a column or a

row name to the methods, as the examples above show.

Finally, you can write DataMatrix objects to files or file-like objects with 

the writeMatrix function in the DataMatrix module:

>>> fh = StringIO()

>>> datamatrix.writeMatrix(matrix,fh)

Output formatting is again set via options to the csv module. Optionally you 

can save only part of the columns, specified as a list:

>>> datamatrix.writeMatrix(matrix,fh,columns=["name","Job"])

For other uses, please see the API documentation (generated with pydoc as a 

HTML file), also present in the distribution.

------------------------------------------------------------------------------

5. Credits and contact information

------------------------------------------------------------------------------

DataMatrix was started by me (Luca Beltrame) and Giovanni joined up later, 

with code fixes and most importantly with unit tests. 

Bug reports, feature requests and comments should be either sent via email

(einar at heavensinferno dot net) or by leaving a comment at 

http://www.dennogumi.org/projects-2/datamatrix