# 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)

  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.

  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.

  property column_names

    An tuple of strings.

  property column_types

    An tuple `DataType` instances.

  property columns

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

  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.

    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_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_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_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()`.

  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.

  property row_names

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

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

  property rows

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

  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.

    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`.