__init__(self, columns=3, data=[])
(Constructor)

Creates a Picalo Table. Tables are the single-most important item in Picalo. It should be the first place users look to understand how to use the program. See the manual for more information on how tables work.

The columns (field definitions) are required to be named and to have types. Fields are specified as a sequence of (name, type) pairs. The name can be any string starting with a letter and then any combination of letters and numbers. Column names must be unique. The type must be a type object, such as int, float, unicode, DateTime, etc. See below for examples.

The initial data for the table can be specified as a sequence of sequences, or a grid of data. See below for examples.

>>> # creates a table with two columns
>>> data = Table([
...  ( 'id',   int ),
...  ( 'name', unicode),
... ])
>>> data.structure().view()
+--------+------------------+------------+--------+
| Column |       Type       | Expression | Format |
+--------+------------------+------------+--------+
| id     | <type 'int'>     |    <N>     |  <N>   |
| name   | <type 'unicode'> |    <N>     |  <N>   |
+--------+------------------+------------+--------+

>>> # creates a table with two columns and initial data
>>> data = Table([
...   ( 'id',   int ),
...   ( 'name', unicode),
... ],[
...   [ 1, 'Danny'    ],
...   [ 2, 'Vijay'    ],
...   [ 3, 'Dongsong' ],
...   [ 4, 'Sally'    ],
... ])
>>> data.structure().view()
+--------+------------------+------------+--------+
| Column |       Type       | Expression | Format |
+--------+------------------+------------+--------+
| id     | <type 'int'>     |    <N>     |  <N>   |
| name   | <type 'unicode'> |    <N>     |  <N>   |
+--------+------------------+------------+--------+

>>> # creates a table with two columns (using shortcut notation)
>>> # since types are not specified, both columns are typed as unicode
>>> data = Table(['id', 'name'])
>>> data.structure().view()
+--------+------------------+------------+--------+
| Column |       Type       | Expression | Format |
+--------+------------------+------------+--------+
| id     | <type 'unicode'> |    <N>     |  <N>   |
| name   | <type 'unicode'> |    <N>     |  <N>   |
+--------+------------------+------------+--------+

>>> # creates a table with two columns (using another shortcut notation)
>>> data = Table(3)
>>> data.structure().view()
+--------+------------------+------------+--------+
| Column |       Type       | Expression | Format |
+--------+------------------+------------+--------+
| col000 | <type 'unicode'> |    <N>     |  <N>   |
| col001 | <type 'unicode'> |    <N>     |  <N>   |
| col002 | <type 'unicode'> |    <N>     |  <N>   |
+--------+------------------+------------+--------+

Parameters:

columns - A list of (name, type) pairs specifying the column names and their types
           (type=list)

data - The initial data for the table specified as another Picalo table or a list of lists.
           (type=Table/list)

Returns:

The new Picalo table.
           (type=Table)

__add__(self, other)
(Addition operator)

Adds two tables together. To be added together, two tables should have the same number of columns and be compatible with one another. The new table includes the records of the first table followed by the records of the second table. The column columns (and column calculations) of the first table are carried to the new table. The two source tables are not modified.

Stated differently, this method copies the first table and appends the second table's records to it.

Some users might expect this method to add individual cells together, similar to matrix addition. This is *not* the case. Instead, the new table includes all records from both tables.

>>> t1 = Table([('id', int)], [[1,1], [2,2]])
>>> t2 = Table([('id', int)], [[3,3], [4,4]])
>>> t3 = t1 + t2
>>> t3.view()
+--------+--------+
| col000 | col001 |
+--------+--------+
|      1 |      1 |
|      2 |      2 |
|      3 |      3 |
|      4 |      4 |
+--------+--------+

Parameters:

other - A Table to be added to this one.
           (type=Table)

Returns:

A new table with records from both tables
           (type=Table)

__copy__(self)

Returns:

A new Table object with the columns and data of this Table.
           (type=returns)

__delitem__(self, index)
(Index deletion operator)

__eq__(self, other)
(Equality operator)

__getitem__(self, index)
(Indexing operator)

Parameters:

index - The zero-based index of the record to pull OR the string name of the column to pull.
           (type=int or str)

Returns:

A Picalo Record object or Picalo Column object from this table
           (type=Record or Column)

__getslice__(self, i, j)
(Slicling operator)

__iadd__(self, other)

__iter__(self)

>>> for record in mytable:
>>>   # do something with each record object

Returns:

An iterator to this Table.
           (type=iterator)

__len__(self)
(Length operator)

Returns:

The number of records in the table.
           (type=int)

__repr__(self)
(Representation operator)

Returns:

The number of rows and columns in the table.
           (type=str)

__setitem__(self, index, record)
(Index assignment operator)

Replaces an existing Record with the given data. Use = to set items.

>>> table = Table([('id', int)], [[1,2], [3,4]])
>>> table[1] = [5,6]
>>> table.view()
+--------+--------+
| col000 | col001 |
+--------+--------+
|      1 |      2 |
|      5 |      6 |
+--------+--------+

Parameters:

index - The index of the record where data will be replaced.
           (type=int)

record - A Record object, a list, or a Python sequence containing data for the
           (type=Record/list/tuple of columns for the record records.)

_insert_column_(self, index, coldef, records=None, expression=None)

append(self, *a, **k)

Inserts a new record at the end of this table. This is the primary way to add new data to a table. If you need to insert a row in the middle of a table, use the insert() method.

Records can be added in any of the following ways:

• newrec = mytable3.append()
• newrec['ID'] = 4
• newrec['Name'] = 'Homer'
• newrec['Salary'] = 15000

• mytable.append(4, 'Homer', 1500)

• mytable3.append([4, 'Homer', 1500])

• mytable3.append({'ID':5, 'Name':'Marge', 'Salary': 275000})

• mytable3.append({0:5, 1:'Marge', 2: 275000})

• mytable3.append(ID=5, Name='Krusty', Salary=50000)

Returns:

The new record object (that was appended to the end of the table)
           (type=Record)

append_calculated(self, name, expression)

Adds a new, calculated column with records given by expression. Calculated columns act as regular columns in all ways. Their records are 'active' meaning their records change when the result of the expression. In other words, they are recalculated each time they are used rather than being stored statically. This is similar to the way Excel functions always reflect the most updated data records.

>>> table = Table([('id', int)], [[1],[2],[4]])
>>> table.append_calculated('plusone', "col000+1")
>>> table.view()
+--------+---------+
| col000 | plusone |
+--------+---------+
|      1 |       2 |
|      2 |       3 |
|      4 |       5 |
+--------+---------+

Parameters:

name - The new column name
           (type=str)

expression - An expression that returns the record of the new field. As shown in the example, use rec to denote the current record being evaluated.
           (type=str)

Returns:

The new column object.
           (type=Column)

append_calculated_static(self, name, column_type, expression)

Adds a new, calculated column with records given by expression. The records are calculated immediately using expression, and then they are static. In other words, this method calculates a new, regular column. The records are not 'active' in the sense that append_calculated() columns are active. When this method returns, the new column is the same as any other, non-calculated column.

>>> table = Table([('id', int)], [[1],[2],[4]])
>>> table.append_calculated('plusone', int, "col000+1")
>>> table.view()
+--------+---------+
| col000 | plusone |
+--------+---------+
|      1 |       2 |
|      2 |       3 |
|      4 |       5 |
+--------+---------+

Parameters:

name - The new column name
           (type=str)

column_type - The type of the new column (str, Date, int, long, etc.)
           (type=type)

expression - An expression that returns the record of the new field. As shown in the example, use rec to denote the current record being evaluated.
           (type=str)

Returns:

The new column object.
           (type=Column)

append_column(self, name, column_type, records=None)

Parameters:

name - The new column name
           (type=str)

column_type - The new column type (int, float, DateTime, unicode, str, etc)
           (type=type)

records - A list of records to place into the cells of the new column (if a full Table, the first column is used)
           (type=list, Column, or Table)

Returns:

The new column object.
           (type=Column)

clear_filter(self)

column(self, col)

Returns a single column of the table. Column records can be read and modified but not deleted. This is a useful method when you want to work with a single column of a table.

The returned Column object is essentially a list of records and can be treated as such. Any function that takes a list can take a Column object.

Parameters:

col - The column name to return
           (type=str)

Returns:

A Column object representing the specified column of the table.
           (type=Column)

column_count(self)

Retrieves the number of columns in a table. Note that since Picalo lists are zero-based, you access individual columns starting with 0.

So although column_count() may report 3 columns, you access them via table.column(0), table.column(1), and table.column(2).

Returns:

The number columns in the table
           (type=int)

delete_column(self, column)

Removes a column from the table and discards the records. Remaining column indices are decremented to reflect the new table structure. Column names (columns) are not modified.

Parameters:

column - The name or index of the column to be removed. If a list of columns, all of the columns are removed.
           (type=str or list)

deref_column(self, col_name)

Dereferences the col name to its index (if it is a name). For example, if the column name "id" is given, it returns the index of this column (such as 0, 1, 2, etc.).

Parameters:

col_name - The name of the column
           (type=str/int)

Returns:

The index of the column
           (type=int)

extend(self, table)

Appends the records in the given table to the end of this table. The two tables must have the same number of columns to be merged.

>>> mytable3.extend(mytable2)  # appends mytable2 to the end of mytable3

Parameters:

table - The records of the specified table will be added to this table.
           (type=Table)

filter(self, expression=None)

Filters the table with the given expression. Until the filter is either replaced or cleared, only the records matching the filter will be available in the table. All Picalo functions will see only this limited view of the table in their analyses. In other words, it is as if the filtered record is not in the table at all until the filter is removed.

Filters are transient. They do not save with the table and they do not carry over if you copy a table. They are simply temporary filters that you can use to restrict Picalo analyses to a few records.

Only one filter can be active at any time. Setting a new filter will replace the existing one.

Parameters:

expression - A valid Picalo expression that returns True or False. If the expression evaluates to Frue, the record is included in the filtered view. If False, the record is hidden from view.
           (type=str)

find(self, **pairs)

Finds the record indices with given key=record pairs. This method is not normally used directly -- use Simple.select_by_record instead.

This method is different than Simple.select_by_record in that it does not create a new table. Simple.select_by_record creates a new table consisting of copies of all matching records. In contrast, this method simply returns the record indices of the matching records.

This method *is* efficient and can be used often. It calculates indices as needed and should select very fast.

>>> table = Table([
...  ('col001', int),
...  ('col002', int),
...  ('col003', unicode),
... ],[
...  [5,6,'flo'], 
...  [3,2,'sally'], 
...  [4,6,'dan'], 
...  [4,7,'stu'], 
...  [4,7,'ben'],
...  [4,6,'benny'],
... ])
>>> results = table.find(col001=6, col000=4)
>>> results
[2, 5]

Parameters:

pairs - column=record pairings giving the key(s) to select on.
           (type=object)

Returns:

A list of indices that match the pairs.
           (type=list)

get_column_names(self)

Returns:

A list of string names of columns
           (type=list)

get_columns(self)

Returns the column objects of this table. Columns are Column objects, which contain the column name, calculated expression (if any), type if set, etc.

Returns:

A list of Column objects
           (type=list)

guess_types(self, num_records=-1)

Inspects the first num_records in each column and automatically sets the type of each column. This method is not perfect, but it is fairly robust. It is a good method to call after importing from TSV/CSV if you don't want to set types manually. If num_records is less than 1, all records in the table are inspected (this can take a long time for huge tables but should be done for all other tables).

Parameters:

num_records - The number of records to inspect before setting the type.
           (type=int)

index(self, *col_names)

Returns an index on this table for the given column name(s). This method allows you to find the record indices that match specific keys. If only one column name is specified, the index will have as many records as there are unique records in the column. If multiple columns are specified, the index will have as many records as there are unique combinations of the records in the columns.

Indices are used throughout Picalo internally and are not normally accessed by users. However, many analyses need to calculate indices directly, and exposing this method allows this behavior.

Parameters:

col_names - One or more column names (separated by commas) to calculate the unique index on.
           (type=str)

insert(self, *a, **k)

Inserts a new record at the given index location. The first parameter *must* be the index location to insert the record. The remaining parameters are the same as the append() method. Possible formats are (assuming you want to place the new record in the second row and push all existing records down one):

• newrec = mytable3.insert(2) # insert before row 2
• newrec['ID'] = 4
• newrec['Name'] = 'Homer'
• newrec['Salary'] = 15000

• mytable.insert(2, 4, 'Homer', 1500) # insert before row 2

• mytable3.insert(2, [4, 'Homer', 1500]) # insert before row 2

• mytable3.insert(2, {'ID':5, 'Name':'Marge', 'Salary': 275000}) # insert before row 2

• mytable3.insert(2, {0:5, 1:'Marge', 2: 275000}) # insert before row 2

• mytable3.insert(2, ID=5, Name='Krusty', Salary=50000) # insert before row 2

Returns:

The new record object (that was inserted to the end of the table)
           (type=returns)

insert_calculated(self, index, name, expression)

Inserts a new, calculated column with records given by expression at the given index location. Calculated columns act as regular columns in all ways. Their records are 'active' meaning their records change when the result of the expression. In other words, they are recalculated each time they are used rather than being stored statically. This is similar to the way Excel functions always reflect the most updated data records.

>>> table = Table([('id', int)], [[1],[2],[4]])
>>> table.insert_calculated(0, 'plusone', "col000+1")
>>> table.view()
+---------+--------+
| plusone | col000 |
+---------+--------+
|       2 |      1 |
|       3 |      2 |
|       5 |      4 |
+---------+--------+

Parameters:

index - The index location of the new column. Previous column indices are incremented one to make room for the new column.
           (type=int)

name - The new column name
           (type=str)

expression - An expression that returns the record of the new field. As shown in the example, use rec to denote the current record being evaluated.
           (type=str)

Returns:

The new column object.
           (type=Column)

insert_calculated_static(self, index, name, column_type, expression)

Inserts a new, calculated column with records given by expression at the given index location. The records are calculated immediately using expression, and then they are static. In other words, this method calculates a new, regular column. The records are not 'active' in the sense that append_calculated() columns are active. When this method returns, the new column is the same as any other, non-calculated column.

>>> table = Table([('id', int)], [[1],[2],[4]])
>>> table.append_calculated('plusone', int, "col000 + 1")
>>> table.view()
+--------+---------+
| col000 | plusone |
+--------+---------+
|      1 |       2 |
|      2 |       3 |
|      4 |       5 |
+--------+---------+

Parameters:

index - The index location of the new column. Previous column indices are incremented one to make room for the new column.
           (type=int)

name - The new column name
           (type=str)

column_type - The type of the new column (str, Date, int, long, etc.)
           (type=type)

expression - An expression that returns the record of the new field. As shown in the example, use rec to denote the current record being evaluated.
           (type=str)

Returns:

The new column object.
           (type=Column)

insert_column(self, index, name, column_type, records=None)

Parameters:

name - The new column name
           (type=str)

column_type - The new column type (int, float, DateTime, unicode, str, etc)
           (type=type)

records - A list of records to place into the cells of the new column (if a full Table, the first column is used)
           (type=list, Column, or Table)

Returns:

The new column object.
           (type=Column)

is_changed(self)

is_filtered(self)

is_readonly(self)

Returns:

Whether this table is read only.
           (type=bool)

iterator(self, respect_filter=True)

>>> for record in mytable:
>>>   # do something with each record object

Returns:

An iterator to this Table.
           (type=iterator)

move_column(self, column, new_index)

Moves a column to another location in the table. A column can be moved in front of other columns or behind other columns with this method.

The column parameter is the name of the column to be moved, the index of the column to be moved, or the column object itself.

Parameters:

column - The name, index, or column object to be moved.
           (type=int/str/Column)

new_index - The name, index, or column object that the column will be placed before.
           (type=int/str/Column)

prettyprint(self, fp=None, center_columns=True, space_before=' ', space_after=' ', col_separator_char='|', row_separator_char='-', join_char='+', line_ending='\n', none='<N>', respect_filter=True)

Parameters:

fp - An open file pointer object. If None, defaults to standard output stream.
           (type=file)

center_columns - Whether to center columns or not.
           (type=bool)

space_before - An optional spacing between the leading column separator and the field record.
           (type=str)

space_after - An optional spacing between the field and the trailing column separator.
           (type=str)

col_separator_char - An optional column separator character to use in the printout.
           (type=str)

row_separator_char - An optional row separator character to use in the printout.
           (type=str)

join_char - An optional character to use when joining rows and columns.
           (type=str)

line_ending - An optional line ending character(s) to use.
           (type=str)

none - The record to print when cells are set to the special None record.
           (type=str)

record(self, index, respect_filter=True)

Retrieves the record at the given index. This is one of the most-used methods in the Picalo toolkit as it gives you access to records.

In keeping with most computer languages, Picalo indices are always zero-based. This may require a slight adjustment for some users, but it makes mathematical calculations much easier and has other implications. This means that record 1 is table[0], record 2 is table[1], and so forth.

Note that the shortcut way to access this method is the simple [n] notation, as in table[1] to access the second record. table.record() is rarely called as the shortcut is preferred instead.

For advanced users: Index can also be a slice, as in table[2:5] to return a new Picalo table including only records 2, 3, and 4. See the Python documentation for more information on slices.

The method respects any filters on the table by default. This can be overridden to ignore the filter.

>>> table = Table([('id', int)], [[1],[2],[3],[4]])
>>> table2 = table[1]
>>> # table2 is now a Record object pointing at [2]

>>> table = Table([('id', int)], [[1],[2],[3],[4]])
>>> print table[1]['col000']
2

Parameters:

index - The zero-based index of the record to pull.
           (type=int)

Returns:

A Picalo Record object, which allows access to members via column name.
           (type=Record)

record_count(self, respect_filter=True)

Returns:

The number of records in the table.
           (type=int)

reorder_columns(self, columns)

Reorders the columns according to the given list. This is an alternative to move_column. If you know the exact order you want the columns in, use this method to explicitly set them.

Parameters:

columns - A list giving the new column order (use column names, not indices).
           (type=list)

save(self, filename, respect_filter=False)

Parameters:

filename - The filename to save to. This can also be an open stream.
           (type=str @param respect_filter Whether to save the entire file or only those rows available through any current filter. @type respect_filter bool)

save_csv(self, filename, line_ending='\n', none='', encoding='utf-8', respect_filter=False)

Saves this table to a Comma Separated Values (CSV) text file. CSV is an industry-standard way of transferring data between applications. This is the preferred way of exporting data from Picalo.

• No type information is saved to the file. All data is essentially turned into strings.
• Be sure to use the correct encoding if using international languages.
• Different standards for CSV exist (that's the nice thing about standards :). This export uses the Microsoft version.

Parameters:

filename - A file name or a file pointer to an open file. Using the file name string directly is suggested since it ensures the file is opened correctly for reading in CSV.
           (type=str)

line_ending - An optional line ending to separate rows with
           (type=str)

none - An optional parameter specifying what to write for cells that have the None record.
           (type=str)

encoding - The unicode encoding to use for international or special characters. For example, Microsoft applications like to use special characters for double quotes rather than the standard characters. Unicode (the default) handles these nicely.
           (type=str @param respect_filter Whether to save the entire file or only those rows available through any current filter. @type respect_filter bool)

save_delimited(self, filename, delimiter=',', qualifier='"', line_ending='\n', none='', encoding='utf-8', respect_filter=False)

Saves this table to a delimited text file. This method allows the specification of different types of delimiters and qualifiers.

Parameters:

filename - A file name or a file pointer to an open file. Using the file name string directly is suggested since it ensures the file is opened correctly for reading in CSV.
           (type=str)

delimiter - An optional field delimiter character
           (type=str)

qualifier - An optional qualifier to use when delimiters exist in field records
           (type=str)

line_ending - An optional line ending to separate rows with
           (type=str)

none - An optional parameter specifying what to write for cells that have the None record.
           (type=str)

encoding - The unicode encoding to use for international or special characters. For example, Microsoft applications like to use special characters for double quotes rather than the standard characters. Unicode (the default) handles these nicely.
           (type=str @param respect_filter Whether to save the entire file or only those rows available through any current filter. @type respect_filter bool)

save_excel(self, filename, none='', respect_filter=False)

Parameters:

filename - A file name or a file pointer to an open file. Using the file name string directly is suggested since it ensures the file is opened correctly for reading in CSV.
           (type=str)

none - An optional parameter specifying what to write for cells that have the None record.
           (type=str @param respect_filter Whether to save the entire file or only those rows available through any current filter. @type respect_filter bool)

save_fixed(self, filename, line_ending='\n', none='', respect_filter=False)

Saves this table to a fixed width text file. Fixed width files pad column records with extra spaces so they are easier to read.

Parameters:

filename - A file name or a file pointer to an open file. Using the file name string directly is suggested since it ensures the file is opened correctly for reading in CSV.
           (type=str)

line_ending - An optional line ending to separate rows with
           (type=str)

none - An optional parameter specifying what to write for cells that have the None record.
           (type=str @param respect_filter Whether to save the entire file or only those rows available through any current filter. @type respect_filter bool)

save_tsv(self, filename, line_ending='\n', none='', encoding='utf-8', respect_filter=False)

Saves this table to a Tab Separated Values (TSV) text file. TSV is an industry-standard way of transferring data between applications.

• No type information is saved to the file. All data is essentially turned into strings.
• Be sure to use the correct encoding if using international languages.
• Different standards for TSV exist (that's the nice thing about standards :). This export uses the Microsoft version.

Parameters:

filename - A file name or a file pointer to an open file. Using the file name string directly is suggested since it ensures the file is opened correctly for reading in CSV.
           (type=str)

line_ending - An optional line ending to separate rows with
           (type=str)

none - An optional parameter specifying what to write for cells that have the None record.
           (type=str)

encoding - The unicode encoding to use for international or special characters. For example, Microsoft applications like to use special characters for double quotes rather than the standard characters. Unicode (the default) handles these nicely.
           (type=str)

save_xml(self, filename, line_ending='\n', indent='\t', compact=False, none='', respect_filter=False)

Parameters:

filename - A file name or a file pointer to an open file. Using the file name string directly is suggested since it ensures the file is opened correctly for reading in CSV.
           (type=str)

line_ending - An optional line ending to separate rows with (when compact is False)
           (type=str)

indent - The character(s) to use for indenting (when compact is False)
           (type=str)

compact - Whether to compact the XML or make it "pretty" with whitespace
           (type=bool)

none - An optional parameter specifying what to write for cells that have the None record.
           (type=str @param respect_filter Whether to save the entire file or only those rows available through any current filter. @type respect_filter bool)

set_changed(self, changed)

set_format(self, column, format=None)

Sets the format of this column.  The format is used for printing the record 
and showing the record in the Picalo GUI.

The format should be a Picalo expression that evaluates to a string.  Use the
'record' variable for the record of the current cell.

Note that this is not an input mask.  It doesn't affect the internal record of 
the field records.  It only affects how it is displayed on the screen.

Example:
  # shows the current record in uppercase
  table.set_format('Salary', "record.upper()")

@param column:  The column name or index to set the type of
@type  column:  str
@param format:  A Picalo expression that evaluates to a string
@type  format:  str

set_name(self, column, name)

set_readonly(self, readonly_flag=False)

Parameters:

readonly_flag - True or False, depending upon whether the table should be read only or not.
           (type=bool)

set_type(self, column, column_type=None, format=None, expression=None)

Sets the type of a column. The type must be a valid <type> object, such as int, float, str, unicode, DateTime, etc. All records in this column will be converted to this new type.

Parameters:

column - The column name or index to set the type of
           (type=str)

column_type - The new type of this column.
           (type=type)

format - A Picalo expression that evaluates to a string
           (type=str)

expression - A Picalo expression that calculates this column.

sort(self, cmp=None, key=None, reverse=False)

Parameters:

cmp - An optional function that compares two items
           (type=function)

key - A function that takes a single item and returns a version of it for use in sorting.
           (type=function)

reverse - Whether to sort in reverse
           (type=bool)

structure(self)

Returns:

A Picalo table describing the structure of this table.
           (type=Table)

view(self)

_add_listener(self, listener)

_calculate_columns_map(self)

_check_page_size(self)

_get_filtered_index(self, index)

_invalidate_indexes(self)

_notify_listeners(self, level=1)

_populate_record(self, rec, *a, **k)

• Format 1: mytable._populate_record(val1, val2)
• Format 2: mytable._populate_record([val1, val2])
• Format 3: mytable._populate_record(head1=val1, head2=val2)
• Format 4: mytable._populate_record({'head1':val1, 'head2':val2})
• Format 5: mytable._populate_record({0:val1, 1:val2})

You cannot mix formats in the same call.

_remove_listener(self, listener)

_save_dialect(self, filename, dialect, none='', encoding='utf-8', respect_filter=False)

_set_cursor_datasource(self, cursor)

_swap_page(self, new_pageindex)

_swap_page_to_index(self, key)

_update_filter_index(self)