Specify a layer of the visualization in terms of mark and data transform(s). This is the main method for specifying how the data should be visualized. It can be called multiple times with different arguments to define a plot with multiple layers. Parameters
(
self,
mark: Mark,
*transforms: Stat | Move,
orient: str | None = None,
legend: bool = True,
label: str | None = None,
data: DataSource = None,
**variables: VariableSpec,
)
| 482 | return new |
| 483 | |
| 484 | def add( |
| 485 | self, |
| 486 | mark: Mark, |
| 487 | *transforms: Stat | Move, |
| 488 | orient: str | None = None, |
| 489 | legend: bool = True, |
| 490 | label: str | None = None, |
| 491 | data: DataSource = None, |
| 492 | **variables: VariableSpec, |
| 493 | ) -> Plot: |
| 494 | """ |
| 495 | Specify a layer of the visualization in terms of mark and data transform(s). |
| 496 | |
| 497 | This is the main method for specifying how the data should be visualized. |
| 498 | It can be called multiple times with different arguments to define |
| 499 | a plot with multiple layers. |
| 500 | |
| 501 | Parameters |
| 502 | ---------- |
| 503 | mark : :class:`Mark` |
| 504 | The visual representation of the data to use in this layer. |
| 505 | transforms : :class:`Stat` or :class:`Move` |
| 506 | Objects representing transforms to be applied before plotting the data. |
| 507 | Currently, at most one :class:`Stat` can be used, and it |
| 508 | must be passed first. This constraint will be relaxed in the future. |
| 509 | orient : "x", "y", "v", or "h" |
| 510 | The orientation of the mark, which also affects how transforms are computed. |
| 511 | Typically corresponds to the axis that defines groups for aggregation. |
| 512 | The "v" (vertical) and "h" (horizontal) options are synonyms for "x" / "y", |
| 513 | but may be more intuitive with some marks. When not provided, an |
| 514 | orientation will be inferred from characteristics of the data and scales. |
| 515 | legend : bool |
| 516 | Option to suppress the mark/mappings for this layer from the legend. |
| 517 | label : str |
| 518 | A label to use for the layer in the legend, independent of any mappings. |
| 519 | data : DataFrame or dict |
| 520 | Data source to override the global source provided in the constructor. |
| 521 | variables : data vectors or identifiers |
| 522 | Additional layer-specific variables, including variables that will be |
| 523 | passed directly to the transforms without scaling. |
| 524 | |
| 525 | Examples |
| 526 | -------- |
| 527 | .. include:: ../docstrings/objects.Plot.add.rst |
| 528 | |
| 529 | """ |
| 530 | if not isinstance(mark, Mark): |
| 531 | msg = f"mark must be a Mark instance, not {type(mark)!r}." |
| 532 | raise TypeError(msg) |
| 533 | |
| 534 | # TODO This API for transforms was a late decision, and previously Plot.add |
| 535 | # accepted 0 or 1 Stat instances and 0, 1, or a list of Move instances. |
| 536 | # It will take some work to refactor the internals so that Stat and Move are |
| 537 | # treated identically, and until then well need to "unpack" the transforms |
| 538 | # here and enforce limitations on the order / types. |
| 539 | |
| 540 | stat: Optional[Stat] |
| 541 | move: Optional[List[Move]] |