datadocs

Specifying the data that goes into a plot.

Plot constructors are deliberately permissive about how data arrives: a single array of points, a pair of coordinate sequences, or an axis object standing in for one of the coordinates, each optionally paired with colors; a mapping from dates to values, or a grid of them keyed by column. This module defines what is accepted and normalises it before plotting.

Types:

  • number: A scalar, Python or NumPy.
  • Series and Series3: The accepted shapes for 2d and 3d point data. See these aliases for the full list of forms.
  • DateSeries: The accepted shapes for values observed on dates.
  • TableData: The accepted shapes for a grid of values to tabulate.

Special series:

  • axis, and its subclasses xaxis, yaxis and zaxis: Stand-ins for a coordinate that runs over a range, so that a series can be given as one sequence of values against an axis rather than as two sequences.

Parsers:

  • parse_series, parse_series3, and their parse_multiple_* variants: Turn any accepted form into arrays of points and colors.
  • parse_date and parse_date_series: Turn any accepted form of dated data into a list of dates and an array of values.
  • parse_table_data: Turn any accepted form of tabular data into the names of its columns and a list of rows, and parse_per_column spread a setting given for the table, per column, or by column name over one entry per column.
  • parse_range: Fill in missing axis limits from the data.

For turning 3d data into positions on a camera's film, see matthewplotlib.camera.

Series = NDArray | tuple[NDArray, ColorSpec] | tuple[ArrayLike, ArrayLike] | tuple[ArrayLike, ArrayLike, ColorSpec] | axis | tuple[axis, ColorSpec] : source docs

The accepted shapes for 2d point data.

Any of the following, for a series of n points, where the colors are one ColorSpec for the whole series:

  • number[n,2]: An array of coordinate pairs.
  • (number[n,2], colors): The same, coloured.
  • (number[n], number[n]): The x and y coordinates as separate sequences.
  • (number[n], number[n], colors): The same, coloured.
  • axis: An axis, standing in for points spaced along it, with the other coordinate held at zero.
  • (axis, colors): The same, coloured.

Series3 = NDArray | tuple[NDArray, ColorSpec] | tuple[ArrayLike, ArrayLike, ArrayLike] | tuple[ArrayLike, ArrayLike, ArrayLike, ColorSpec] | axis | tuple[axis, ColorSpec] : source docs

The accepted shapes for 3d point data.

As Series, with a third coordinate:

  • number[n,3]: An array of coordinate triples.
  • (number[n,3], colors): The same, coloured.
  • (number[n], number[n], number[n]): The three coordinates as separate sequences.
  • (number[n], number[n], number[n], colors): The same, coloured.
  • axis: An axis, standing in for points spaced along it, with the other two coordinates held at zero.
  • (axis, colors): The same, coloured.

DateLike = datetime.date | datetime.datetime | np.datetime64 | str : source docs

The accepted spellings of a single date.

A datetime.date, a datetime.datetime or a NumPy datetime64 (in each of the latter two cases the time of day is discarded), or a string in ISO 8601 format such as "2025-01-01".

DateSeries = Mapping[DateLike, number] | tuple[Sequence[DateLike], ArrayLike] | tuple[DateLike, ArrayLike] : source docs

The accepted shapes for values observed on dates.

Any of the following, for n dated values:

  • {date: value}: A mapping from dates to values.
  • (date[n], number[n]): The dates and the values as separate sequences.
  • (date, number[n]): One date, standing in for the n consecutive days starting there, and the values on those days.

The dates need not be sorted or contiguous, but no date may appear twice. Each of them is any DateLike. A value that is not finite marks a date whose value is unknown, as distinct from one whose value is zero.

TableData = Sequence[Mapping[Any, Any]] | Mapping[Any, Sequence[Any]] | Sequence[Sequence[Any]] | NDArray : source docs

The accepted shapes for a grid of values to tabulate.

Any of the following:

  • A sequence of mappings, one per row. The columns are the keys, in the order they are first seen, and a row missing one of them leaves that cell blank.
  • A mapping from column to the values down it. A column shorter than the longest is blank where it runs out.
  • A sequence of sequences, or a 2d array, one row of values each. These name no columns of their own.

The first two name their columns and the last does not, which is what decides whether a headers argument picks columns out or names them.

parse_range(data: NDArray, range: tuple[number | None, number | None] | None) -> tuple[number, number] : source docs

Fill in missing axis limits from the data.

Limits come from the data's extremes, ignoring non-finite values, since those mark gaps in it rather than describing how far it reaches. Data that reaches no distance at all, a constant series or an empty one, is given a range around itself to be drawn in the middle of.

parse_date(date: DateLike) -> datetime.date : source docs

Reduce any accepted spelling of a date to a datetime.date.

parse_date_series(series: DateSeries) -> tuple[list[datetime.date], NDArray] : source docs

Turn any accepted form of dated data into a list of dates and an array of values, ordered by date.

parse_table_data(data: TableData, headers: Sequence[Any] | Mapping[Any, str] | None) -> tuple[list[str] | None, list[list[Any]]] : source docs

Standardise the accepted spellings of tabular data into the names of the columns, or None where the data carries none, and a list of rows.

parse_per_column(spec: Any, names: list[str] | None, num_columns: int, what: str) -> list[Any] : source docs

Spread a specification given for the whole table, for each column in turn, or for columns picked out by name, into one entry per column.

parse_segments(*seriess: Series) -> tuple[NDArray, NDArray, NDArray, NDArray] : source docs

Turn series into the segments joining their consecutive points, with the colors at each end of each.

Where parse_multiple_series pools every series into one cloud of points, this pairs the points up within each series first: a series is one stroke of the pen, and the last point of one is never joined to the first point of the next.

parse_segments3(*seriess: Series3) -> tuple[NDArray, NDArray, NDArray, NDArray] : source docs

Turn 3d series into the segments joining their consecutive points, with the colors at each end of each. See parse_segments.

xaxis : dataclass source docs

Bases: axis

A series of n points evenly spaced from a to b along the x axis, with the y and z coordinates held at zero.

Accepted wherever a series is, so that something can be plotted against an axis without building coordinates for it by hand.

yaxis : dataclass source docs

Bases: axis

A series of n points evenly spaced from a to b along the y axis, with the x and z coordinates held at zero.

Accepted wherever a series is, so that something can be plotted against an axis without building coordinates for it by hand.

zaxis : dataclass source docs

Bases: axis

A series of n points evenly spaced from a to b along the z axis, with the x and y coordinates held at zero.

Accepted wherever a series is, so that something can be plotted against an axis without building coordinates for it by hand.