Table

The Table object is the most important class in agate. Tables are created by supplying row data, column names and subclasses of DataType to the constructor. Once created, the data in a table can not be changed. This concept is central to agate.

Instead of modifying the data, various methods can be used to create new, derivative tables. For example, the Table.select() method creates a new table with only the specified columns. The Table.where() method creates a new table with only those rows that pass a test. And Table.order_by() creates a sorted table. In all of these cases the output is a new Table and the existing table remains unmodified.

Tables are not themselves iterable, but the columns of the table can be accessed via Table.columns and the rows via Table.rows. Both sequences can be accessed either by numeric index or by name. (In the case of rows, row names are optional.)

agate.Table

A dataset consisting of rows and columns.

Properties

agate.Table.columns

A MappedSequence with column names for keys and Column instances for values.

agate.Table.column_names

An tuple of strings.

agate.Table.column_types

An tuple DataType instances.

agate.Table.rows

A MappedSeqeuence with row names for keys (if specified) and Row instances for values.

agate.Table.row_names

An tuple of strings, if this table has row names.

Creating

agate.Table.from_csv

Create a new table from a CSV.

agate.Table.from_json

Create a new table from a JSON file.

agate.Table.from_fixed

Create a new table from a fixed-width file and a CSV schema.

agate.Table.from_object

Create a new table from a Python object.

Saving

agate.Table.to_csv

Write this table to a CSV.

agate.Table.to_json

Write this table to a JSON file or file-like object.

Basic processing

agate.Table.distinct

Create a new table with only unique rows.

agate.Table.exclude

Create a new table without the specified columns.

agate.Table.find

Find the first row that passes a test.

agate.Table.limit

Create a new table with fewer rows.

agate.Table.order_by

Create a new table that is sorted.

agate.Table.select

Create a new table with only the specified columns.

agate.Table.where

Create a new Table with only those rows that pass a test.

Calculating new data

agate.Table.aggregate

Apply one or more Aggregation instances to this table.

agate.Table.compute

Create a new table by applying one or more Computation instances to each row.

Advanced processing

agate.Table.bins

Generates (approximately) evenly sized bins for the values in a column.

agate.Table.denormalize

Create a new table with row values converted into columns.

agate.Table.group_by

Create a TableSet with a table for each unique key.

agate.Table.homogenize

Fill in missing rows in a series.

agate.Table.join

Create a new table by joining two table's on common values.

agate.Table.merge

Create a new table from a sequence of similar tables.

agate.Table.normalize

Create a new table with columns converted into rows values.

agate.Table.pivot

Create a new table by grouping the data, aggregating those groups, applying a computation, and then organizing the groups into new rows and columns.

agate.Table.rename

Create a copy of this table with different column names or row names.

Previewing

agate.Table.print_bars

Print a text-based bar chart based on this table.

agate.Table.print_csv

Print this table as a CSV.

agate.Table.print_html

Print an HTML version of this table.

agate.Table.print_json

Print this table as JSON.

agate.Table.print_structure

Print this table's column names and types as a plain-text table.

agate.Table.print_table

Print a text-based view of the data in this table.

Charting

agate.Table.bar_chart

Render a bar chart using leather.Chart.

agate.Table.column_chart

Render a column chart using leather.Chart.

agate.Table.line_chart

Render a line chart using leather.Chart.

agate.Table.scatterplot

Render a scatterplot using leather.Chart.

Detailed list

class agate.Table(rows, column_names=None, column_types=None, row_names=None, _is_fork=False)

Bases: object

A dataset consisting of rows and columns. Columns refer to “vertical” slices of data that must all be of the same type. Rows refer to “horizontal” slices of data that may (and usually do) contain mixed types.

The sequence of Column instances are retrieved via the Table.columns property. They may be accessed by either numeric index or by unique column name.

The sequence of Row instances are retrieved via the Table.rows property. They may be accessed by either numeric index or, if specified, unique row names.

Parameters:
  • rows – The data as a sequence of any sequences: tuples, lists, etc. If any row has fewer values than the number of columns, it will be filled out with nulls. No row may have more values than the number of columns.

  • column_names – A sequence of string names for each column or None, in which case column names will be automatically assigned using letter_name().

  • column_types – A sequence of instances of DataType or an instance of TypeTester or None in which case a generic TypeTester will be used. Alternatively, a dictionary with column names as keys and instances of DataType as values to specify some types.

  • row_names – Specifies unique names for each row. This parameter is optional. If specified it may be 1) the name of a single column that contains a unique identifier for each row, 2) a key function that takes a Row and returns a unique identifier or 3) a sequence of unique identifiers of the same length as the sequence of rows. The uniqueness of resulting identifiers is not validated, so be certain the values you provide are truly unique.

  • _is_fork – Used internally to skip certain validation steps when data is propagated from an existing table. When True, rows are assumed to be Row instances, rather than raw data.

property column_types

An tuple DataType instances.

property column_names

An tuple of strings.

property row_names

An tuple of strings, if this table has row names.

If this table does not have row names, then None.

property columns

A MappedSequence with column names for keys and Column instances for values.

property rows

A MappedSeqeuence with row names for keys (if specified) and Row instances for values.

print_csv(**kwargs)

Print this table as a CSV.

This is the same as passing sys.stdout to Table.to_csv().

kwargs will be passed on to Table.to_csv().

print_json(**kwargs)

Print this table as JSON.

This is the same as passing sys.stdout to Table.to_json().

kwargs will be passed on to Table.to_json().

aggregate(aggregations)

Apply one or more Aggregation instances to this table.

Parameters:

aggregations – A single Aggregation instance or a sequence of tuples in the format (name, aggregation), where each aggregation is an instance of Aggregation.

Returns:

If the input was a single Aggregation then a single result will be returned. If it was a sequence then an OrderedDict of results will be returned.

bar_chart(label=0, value=1, path=None, width=None, height=None)

Render a bar chart using leather.Chart.

Parameters:
  • label – The name or index of a column to plot as the labels of the chart. Defaults to the first column in the table.

  • value – The name or index of a column to plot as the values of the chart. Defaults to the second column in the table.

  • path – If specified, the resulting SVG will be saved to this location. If None and running in IPython, then the SVG will be rendered inline. Otherwise, the SVG data will be returned as a string.

  • width – The width of the output SVG.

  • height – The height of the output SVG.

bins(column_name, count=10, start=None, end=None)

Generates (approximately) evenly sized bins for the values in a column. Bins may not be perfectly even if the spread of the data does not divide evenly, but all values will always be included in some bin.

The resulting table will have two columns. The first will have the same name as the specified column, but will be type Text. The second will be named count and will be of type Number.

Parameters:
  • column_name – The name of the column to bin. Must be of type Number

  • count – The number of bins to create. If not specified then each value will be counted as its own bin.

  • start – The minimum value to start the bins at. If not specified the minimum value in the column will be used.

  • end – The maximum value to end the bins at. If not specified the maximum value in the column will be used.

Returns:

A new Table.

column_chart(label=0, value=1, path=None, width=None, height=None)

Render a column chart using leather.Chart.

Parameters:
  • label – The name or index of a column to plot as the labels of the chart. Defaults to the first column in the table.

  • value – The name or index of a column to plot as the values of the chart. Defaults to the second column in the table.

  • path – If specified, the resulting SVG will be saved to this location. If None and running in IPython, then the SVG will be rendered inline. Otherwise, the SVG data will be returned as a string.

  • width – The width of the output SVG.

  • height – The height of the output SVG.

compute(computations, replace=False)

Create a new table by applying one or more Computation instances to each row.

Parameters:
  • computations – A sequence of pairs of new column names and Computation instances.

  • replace – If True then new column names can match existing names, and those columns will be replaced with the computed data.

Returns:

A new Table.

denormalize(key=None, property_column='property', value_column='value', default_value=<object object>, column_types=None)

Create a new table with row values converted into columns.

For example:

name

property

value

Jane

gender

female

Jane

race

black

Jane

age

24

Can be denormalized so that each unique value in field becomes a column with value used for its values.

name

gender

race

age

Jane

female

black

24

Jack

male

white

35

Joe

male

black

28

If one or more keys are specified then the resulting table will automatically have row_names set to those keys.

This is the opposite of Table.normalize().

Parameters:
  • key – A column name or a sequence of column names that should be maintained as they are in the normalized table. Typically these are the tables unique identifiers and any metadata about them. Or, None if there are no key columns.

  • field_column – The column whose values should become column names in the new table.

  • property_column – The column whose values should become the values of the property columns in the new table.

  • default_value – Value to be used for missing values in the pivot table. If not specified Decimal(0) will be used for aggregations that return Number data and None will be used for all others.

  • column_types – A sequence of column types with length equal to number of unique values in field_column or an instance of TypeTester. Defaults to a generic TypeTester.

Returns:

A new Table.

distinct(key=None)

Create a new table with only unique rows.

Parameters:

key – Either the name of a single column to use to identify unique rows, a sequence of such column names, a function that takes a row and returns a value to identify unique rows, or None, in which case the entire row will be checked for uniqueness.

Returns:

A new Table.

exclude(key)

Create a new table without the specified columns.

Parameters:

key – Either the name of a single column to exclude or a sequence of such names.

Returns:

A new Table.

find(test)

Find the first row that passes a test.

Parameters:

test (function) – A function that takes a Row and returns True if it matches.

Returns:

A single Row if found, or None.

classmethod from_csv(path, column_names=None, column_types=None, row_names=None, skip_lines=0, header=True, sniff_limit=0, encoding='utf-8', row_limit=None, **kwargs)

Create a new table from a CSV.

This method uses agate’s builtin CSV reader, which supplies encoding support for both Python 2 and Python 3.

kwargs will be passed through to the CSV reader.

Parameters:
  • path – Filepath or file-like object from which to read CSV data. If a file-like object is specified, it must be seekable. If using Python 2, the file should be opened in binary mode (rb).

  • column_names – See Table.__init__().

  • column_types – See Table.__init__().

  • row_names – See Table.__init__().

  • skip_lines – The number of lines to skip from the top of the file.

  • header – If True, the first row of the CSV is assumed to contain column names. If header and column_names are both specified then a row will be skipped, but column_names will be used.

  • sniff_limit – Limit CSV dialect sniffing to the specified number of bytes. Set to None to sniff the entire file. Defaults to 0 (no sniffing).

  • encoding – Character encoding of the CSV file. Note: if passing in a file handle it is assumed you have already opened it with the correct encoding specified.

  • row_limit – Limit how many rows of data will be read.

classmethod from_fixed(path, schema_path, column_names=<object object>, column_types=None, row_names=None, encoding='utf-8', schema_encoding='utf-8')

Create a new table from a fixed-width file and a CSV schema.

Schemas must be in the “ffs” format. There is a repository of such schemas maintained at wireservice/ffs.

Parameters:
  • path – File path or file-like object from which to read fixed-width data.

  • schema_path – File path or file-like object from which to read schema (CSV) data.

  • column_names – By default, these will be parsed from the schema. For alternatives, see Table.__init__().

  • column_types – See Table.__init__().

  • row_names – See Table.__init__().

  • encoding – Character encoding of the fixed-width file. Note: if passing in a file handle it is assumed you have already opened it with the correct encoding specified.

  • schema_encoding – Character encoding of the schema file. Note: if passing in a file handle it is assumed you have already opened it with the correct encoding specified.

classmethod from_json(path, row_names=None, key=None, newline=False, column_types=None, encoding='utf-8', **kwargs)

Create a new table from a JSON file.

Once the JSON has been deseralized, the resulting Python object is passed to Table.from_object().

If the file contains a top-level dictionary you may specify what property contains the row list using the key parameter.

kwargs will be passed through to json.load().

Parameters:
  • path – Filepath or file-like object from which to read JSON data.

  • row_names – See the Table.__init__().

  • key – The key of the top-level dictionary that contains a list of row arrays.

  • newline – If True then the file will be parsed as “newline-delimited JSON”.

  • column_types – See Table.__init__().

  • encoding – According to RFC4627, JSON text shall be encoded in Unicode; the default encoding is UTF-8. You can override this by using any encoding supported by your Python’s open() function if path is a filepath. If passing in a file handle, it is assumed you have already opened it with the correct encoding specified.

classmethod from_object(obj, row_names=None, column_types=None)

Create a new table from a Python object.

The object should be a list containing a dictionary for each “row”. Nested objects or lists will also be parsed. For example, this object:

{
    'one': {
        'a': 1,
        'b': 2,
        'c': 3
    },
    'two': [4, 5, 6],
    'three': 'd'
}

Would generate these columns and values:

{
    'one/a': 1,
    'one/b': 2,
    'one/c': 3,
    'two.0': 4,
    'two.1': 5,
    'two.2': 6,
    'three': 'd'
}

Column names and types will be inferred from the data.

Not all rows are required to have the same keys. Missing elements will be filled in with null values.

Keys containing a slash (/) can collide with other keys. For example:

{
    'a/b': 2,
    'a': {
        'b': False
    }
}

Would generate:

{
    'a/b': false
}
Parameters:
  • obj – Filepath or file-like object from which to read JSON data.

  • row_names – See Table.__init__().

  • column_types – See Table.__init__().

group_by(key, key_name=None, key_type=None)

Create a TableSet with a table for each unique key.

Note that group names will always be coerced to a string, regardless of the format of the input column.

Parameters:
  • key – Either the name of a column from the this table to group by, or a function that takes a row and returns a value to group by.

  • key_name – A name that describes the grouped properties. Defaults to the column name that was grouped on or “group” if grouping with a key function. See TableSet for more.

  • key_type – An instance of any subclass of DataType. If not provided it will default to a :class`.Text`.

Returns:

A TableSet mapping where the keys are unique values from the key and the values are new Table instances containing the grouped rows.

homogenize(key, compare_values, default_row=None)

Fill in missing rows in a series.

This can be used, for instance, to add rows for missing years in a time series.

Missing rows are found by comparing the values in the key columns with those provided as compare_values.

Values not found in the table will be used to generate new rows with the given default_row.

default_row should be an array of values or an array-generating function. If not specified, the new rows will have None in columns all columns not specified in key.

If default_row is an array of values, its length should be row length minus the number of column names provided in the key.

If it is an array-generating function, the function should take an array of missing values for each new row and output a full row including those values.

Parameters:
  • key – Either a column name or a sequence of such names.

  • compare_values – Either an array of column values if key is a single column name or a sequence of arrays of values if key is a sequence of names. It can also be a generator that yields either of the two. A row is created for each value or list of values not found in the rows of the table.

  • default_row – An array of values or a function to generate new rows. The length of the input array should be equal to row length minus column_names count. The length of array generated by the function should be the row length.

Returns:

A new Table.

join(right_table, left_key=None, right_key=None, inner=False, full_outer=False, require_match=False, columns=None)

Create a new table by joining two table’s on common values. This method implements most varieties of SQL join, in addition to some unique features.

If left_key and right_key are both None then this method will perform a “sequential join”, which is to say it will join on row number. The inner and full_outer arguments will determine whether dangling left-hand and right-hand rows are included, respectively.

If left_key is specified, then a “left outer join” will be performed. This will combine columns from the right_table anywhere that left_key and right_key are equal. Unmatched rows from the left table will be included with the right-hand columns set to None.

If inner is True then an “inner join” will be performed. Unmatched rows from either table will be left out.

If full_outer is True then a “full outer join” will be performed. Unmatched rows from both tables will be included, with the columns in the other table set to None.

In all cases, if right_key is None then it left_key will be used for both tables.

If left_key and right_key are column names, the right-hand identifier column will not be included in the output table.

If require_match is True unmatched rows will raise an exception. This is like an “inner join” except any row that doesn’t have a match will raise an exception instead of being dropped. This is useful for enforcing expectations about datasets that should match.

Column names from the right table which also exist in this table will be suffixed “2” in the new table.

A subset of columns from the right-hand table can be included in the joined table using the columns argument.

Parameters:
  • right_table – The “right” table to join to.

  • left_key – Either the name of a column from the this table to join on, the index of a column, a sequence of such column identifiers, a function that takes a row and returns a value to join on, or None in which case the tables will be joined on row number.

  • right_key – Either the name of a column from :code:table` to join on, the index of a column, a sequence of such column identifiers, or a function that takes a ow and returns a value to join on. If None then left_key will be used for both. If left_key is None then this value is ignored.

  • inner – Perform a SQL-style “inner join” instead of a left outer join. Rows which have no match for left_key will not be included in the output table.

  • full_outer – Perform a SQL-style “full outer” join rather than a left or a right. May not be used in combination with inner.

  • require_match – If true, an exception will be raised if there is a left_key with no matching right_key.

  • columns – A sequence of column names from right_table to include in the final output table. Defaults to all columns not in right_key. Ignored when full_outer is True.

Returns:

A new Table.

limit(start_or_stop=None, stop=None, step=None)

Create a new table with fewer rows.

See also: Python’s builtin slice().

Parameters:
  • start_or_stop – If the only argument, then how many rows to include, otherwise, the index of the first row to include.

  • stop – The index of the last row to include.

  • step – The size of the jump between rows to include. (step=2 will return every other row.)

Returns:

A new Table.

line_chart(x=0, y=1, path=None, width=None, height=None)

Render a line chart using leather.Chart.

Parameters:
  • x – The name or index of a column to plot as the x-axis. Defaults to the first column in the table.

  • y – The name or index of a column to plot as the y-axis. Defaults to the second column in the table.

  • path – If specified, the resulting SVG will be saved to this location. If None and running in IPython, then the SVG will be rendered inline. Otherwise, the SVG data will be returned as a string.

  • width – The width of the output SVG.

  • height – The height of the output SVG.

classmethod merge(tables, row_names=None, column_names=None)

Create a new table from a sequence of similar tables.

This method will not carry over row names from the merged tables, but new row names can be specified with the row_names argument.

It is possible to limit the columns included in the new Table with column_names argument. For example, to only include columns from a specific table, set column_names equal to table.column_names.

Parameters:
  • tables – An sequence of Table instances.

  • row_names – See Table for the usage of this parameter.

  • column_names – A sequence of column names to include in the new Table. If not specified, all distinct column names from tables are included.

Returns:

A new Table.

normalize(key, properties, property_column='property', value_column='value', column_types=None)

Create a new table with columns converted into rows values.

For example:

name

gender

race

age

Jane

female

black

24

Jack

male

white

35

Joe

male

black

28

can be normalized on columns ‘gender’, ‘race’ and ‘age’:

name

property

value

Jane

gender

female

Jane

race

black

Jane

age

24

This is the opposite of Table.denormalize().

Parameters:
  • key – A column name or a sequence of column names that should be maintained as they are in the normalized self. Typically these are the tables unique identifiers and any metadata about them.

  • properties – A column name or a sequence of column names that should be converted to properties in the new self.

  • property_column – The name to use for the column containing the property names.

  • value_column – The name to use for the column containing the property values.

  • column_types – A sequence of two column types for the property and value column in that order or an instance of TypeTester. Defaults to a generic TypeTester.

Returns:

A new Table.

order_by(key, reverse=False)

Create a new table that is sorted.

Parameters:
  • key – Either the name of a single column to sort by, a sequence of such names, or a function that takes a row and returns a value to sort by.

  • reverse – If True then sort in reverse (typically, descending) order.

Returns:

A new Table.

pivot(key=None, pivot=None, aggregation=None, computation=None, default_value=<object object>, key_name=None)

Create a new table by grouping the data, aggregating those groups, applying a computation, and then organizing the groups into new rows and columns.

This is sometimes called a “crosstab”.

name

race

gender

Joe

white

male

Jane

black

female

Josh

black

male

Jim

asian

female

This table can be pivoted with key equal to “race” and columns equal to “gender”. The default aggregation is Count. This would result in the following table.

race

male

female

white

1

0

black

1

1

asian

0

1

If one or more keys are specified then the resulting table will automatically have row_names set to those keys.

See also the related method Table.denormalize().

Parameters:
  • key – Either the name of a column from the this table to group by, a sequence of such column names, a function that takes a row and returns a value to group by, or None, in which case there will be only a single row in the output table.

  • pivot – A column name whose unique values will become columns in the new table, or None in which case there will be a single value column in the output table.

  • aggregation

    An instance of an Aggregation to perform on each group of data in the pivot table. (Each cell is the result of an aggregation of the grouped data.)

    If not specified this defaults to Count with no arguments.

  • computation

    An optional Computation instance to be applied to the aggregated sequence of values before they are transposed into the pivot table.

    Use the class name of the aggregation as your column name argument when constructing your computation. (This is “Count” if using the default value for aggregation.)

  • default_value – Value to be used for missing values in the pivot table. Defaults to Decimal(0). If performing non-mathematical aggregations you may wish to set this to None.

  • key_name – A name for the key column in the output table. This is most useful when the provided key is a function. This argument is not valid when key is a sequence.

Returns:

A new Table.

print_bars(label_column_name='group', value_column_name='Count', domain=None, width=120, output=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>, printable=False)

Print a text-based bar chart based on this table.

Parameters:
  • label_column_name – The column containing the label values. Defaults to group, which is the default output of Table.pivot() or Table.bins().

  • value_column_name – The column containing the bar values. Defaults to Count, which is the default output of Table.pivot() or Table.bins().

  • domain – A 2-tuple containing the minimum and maximum values for the chart’s x-axis. The domain must be large enough to contain all values in the column.

  • width – The width, in characters, to use for the bar chart. Defaults to 120.

  • output – A file-like object to print to. Defaults to sys.stdout.

  • printable – If true, only printable characters will be outputed.

print_html(max_rows=20, max_columns=6, output=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>, max_column_width=20, locale=None, max_precision=3)

Print an HTML version of this table.

Parameters:
  • max_rows – The maximum number of rows to display before truncating the data. This defaults to 20 to prevent accidental printing of the entire table. Pass None to disable the limit.

  • max_columns – The maximum number of columns to display before truncating the data. This defaults to 6 to prevent wrapping in most cases. Pass None to disable the limit.

  • output – A file-like object to print to. Defaults to sys.stdout, unless running in Jupyter. (See above.)

  • max_column_width – Truncate all columns to at most this width. The remainder will be replaced with ellipsis.

  • locale – Provide a locale you would like to be used to format the output. By default it will use the system’s setting.

Max_precision:

Puts a limit on the maximum precision displayed for number types. Numbers with lesser precision won’t be affected. This defaults to 3. Pass None to disable limit.

print_structure(output=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>, max_rows=None)

Print this table’s column names and types as a plain-text table.

Parameters:

output – The output to print to.

print_table(max_rows=20, max_columns=6, output=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>, max_column_width=20, locale=None, max_precision=3)

Print a text-based view of the data in this table.

The output of this method is GitHub Flavored Markdown (GFM) compatible.

Parameters:
  • max_rows – The maximum number of rows to display before truncating the data. This defaults to 20 to prevent accidental printing of the entire table. Pass None to disable the limit.

  • max_columns – The maximum number of columns to display before truncating the data. This defaults to 6 to prevent wrapping in most cases. Pass None to disable the limit.

  • output – A file-like object to print to.

  • max_column_width – Truncate all columns to at most this width. The remainder will be replaced with ellipsis.

  • locale – Provide a locale you would like to be used to format the output. By default it will use the system’s setting.

Max_precision:

Puts a limit on the maximum precision displayed for number types. Numbers with lesser precision won’t be affected. This defaults to 3. Pass None to disable limit.

rename(column_names=None, row_names=None, slug_columns=False, slug_rows=False, **kwargs)

Create a copy of this table with different column names or row names.

By enabling slug_columns or slug_rows and not specifying new names you may slugify the table’s existing names.

kwargs will be passed to the slugify method in python-slugify. See: https://github.com/un33k/python-slugify

Parameters:
  • column_names – New column names for the renamed table. May be either an array or a dictionary mapping existing column names to new names. If not specified, will use this table’s existing column names.

  • row_names – New row names for the renamed table. May be either an array or a dictionary mapping existing row names to new names. If not specified, will use this table’s existing row names.

  • slug_columns – If True, column names will be converted to slugs and duplicate names will have unique identifiers appended.

  • slug_rows – If True, row names will be converted to slugs and dupicate names will have unique identifiers appended.

scatterplot(x=0, y=1, path=None, width=None, height=None)

Render a scatterplot using leather.Chart.

Parameters:
  • x – The name or index of a column to plot as the x-axis. Defaults to the first column in the table.

  • y – The name or index of a column to plot as the y-axis. Defaults to the second column in the table.

  • path – If specified, the resulting SVG will be saved to this location. If None and running in IPython, then the SVG will be rendered inline. Otherwise, the SVG data will be returned as a string.

  • width – The width of the output SVG.

  • height – The height of the output SVG.

select(key)

Create a new table with only the specified columns.

Parameters:

key – Either the name of a single column to include or a sequence of such names.

Returns:

A new Table.

to_csv(path, **kwargs)

Write this table to a CSV. This method uses agate’s builtin CSV writer, which supports unicode on both Python 2 and Python 3.

kwargs will be passed through to the CSV writer.

The lineterminator defaults to the newline character (LF, \n).

Parameters:

path – Filepath or file-like object to write to.

to_json(path, key=None, newline=False, indent=None, **kwargs)

Write this table to a JSON file or file-like object.

kwargs will be passed through to the JSON encoder.

Parameters:
  • path – File path or file-like object to write to.

  • key – If specified, JSON will be output as an hash instead of a list. May be either the name of a column from the this table containing unique values or a function that takes a row and returns a unique value.

  • newline – If True, output will be in the form of “newline-delimited JSON”.

  • indent – If specified, the number of spaces to indent the JSON for formatting.

where(test)

Create a new Table with only those rows that pass a test.

Parameters:

test (function) – A function that takes a Row and returns True if it should be included in the new Table.

Returns:

A new Table.