forked from vega/altair
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request vega#749 from jakevdp/more-docs
DOC: clean up HTML documentation
- Loading branch information
Showing
15 changed files
with
263 additions
and
187 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,62 @@ | ||
|
|
||
| .. _customizing-renderers: | ||
|
|
||
| Customizing Renderers | ||
| ===================== | ||
| Renderers in Altair are all based on the mimebundle representation accessed by | ||
| the ``_repr_mimebundle_`` method of the top-level Altair objects. When you enable | ||
| a renderer, functionally what that does is to define a new kind of mimebundle | ||
| output. | ||
|
|
||
| The ``alt.renderers`` registry allows the user to define and enable new mimetypes | ||
| for the chart. | ||
| As a simple example, imagine we would like to add a ``plaintext`` renderer that | ||
| renders a chart description in plain text. We could do it this way:: | ||
|
|
||
| def plaintext_mimetype(spec): | ||
| return {'text/plain': "description: " + spec.get('description', 'none')} | ||
|
|
||
| alt.renderers.register('plaintext', plaintext_mimetype) | ||
|
|
||
| Now you can enable this mimetype, and then when your chart is displayed you | ||
| will see this description:: | ||
|
|
||
| alt.renderers.enable('plaintext') | ||
|
|
||
| alt.Chart('data.txt').mark_point().encode( | ||
| x='x:Q', | ||
| y='y:Q' | ||
| ).properties( | ||
| description='This is a simple chart' | ||
| ) | ||
|
|
||
| .. code-block:: none | ||
| This is a simple chart | ||
| This is a simple example, but it shows you the flexibility of this approach. | ||
| If you have a frontend that recognizes ``_repr_mimebundle_`` as a means of | ||
| obtaining a MIME type representation of a Python object, then you can define | ||
| a function that will process the chart content in any way before returning | ||
| any mimetype. | ||
|
|
||
| The renderers built-in to Altair are the following: | ||
|
|
||
| - ``"default"``: default rendering, using the | ||
| ``'application/vnd.vegalite.v2+json'`` MIME type which is supported | ||
| by JupyterLab and nteract. | ||
| - ``"jupyterlab"``: identical to ``"default"`` | ||
| - ``"nteract"``: identical to ``"default"`` | ||
| - ``"colab"``: renderer for Google's Colab notebook, using the | ||
| ``"text/html"`` MIME type. | ||
| - ``"notebook"``: renderer for the classic notebook, provided by the ipyvega3_ | ||
| package | ||
| - ``"json"``: renderer that outputs the raw JSON chart specification, using the | ||
| ``'application/json'`` MIME type. | ||
| - ``"png"``: renderer that renders and converts the chart to PNG, outputting it | ||
| using the ``'image/png'`` MIME type. | ||
| - ``"svg"``: renderer that renders and converts the chart to an SVG image, | ||
| outputting it using the ``'image/svg+xml'`` MIME type. | ||
|
|
||
|
|
||
| .. _ipyvega3: https://github.com/vega/ipyvega/tree/vega3 |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,106 @@ | ||
| .. _data-transformers: | ||
|
|
||
| Data transformers | ||
| ================= | ||
|
|
||
| Before a Vega-Lite or Vega specification can be passed to a renderer, it typically | ||
| has to be transformed in a number of ways: | ||
|
|
||
| * Pandas Dataframe has to be sanitized and serialized to JSON. | ||
| * The rows of a Dataframe might need to be sampled or limited to a maximum number. | ||
| * The Dataframe might be written to a ``.csv`` of ``.json`` file for performance | ||
| reasons. | ||
|
|
||
| These data transformations are managed by the data transformation API of Altair. | ||
|
|
||
| .. note:: | ||
|
|
||
| The data transformation API of Altair should not be confused with the ``transform`` | ||
| API of Vega and Vega-Lite. | ||
|
|
||
| A data transformer is a Python function that takes a Vega-Lite data ``dict`` or | ||
| Pandas ``DataFrame`` and returns a transformed version of either of these types:: | ||
|
|
||
| from typing import Union | ||
| Data = Union[dict, pd.DataFrame] | ||
|
|
||
| def data_transformer(data: Data) -> Data: | ||
| # Transform and return the data | ||
| return transformed_data | ||
|
|
||
| Built-in data transformers | ||
| ~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
|
|
||
| Altair includes a default set of data transformers with the following signatures. | ||
|
|
||
| Raise a ``MaxRowsError`` if a Dataframe has more than ``max_rows`` rows:: | ||
|
|
||
| limit_rows(data, max_rows=5000) | ||
|
|
||
| Randomly sample a DataFrame (without replacement) before visualizing:: | ||
|
|
||
| sample(data, n=None, frac=None) | ||
|
|
||
| Convert a Dataframe to a separate ``.json`` file before visualization:: | ||
|
|
||
| to_json(data, prefix='altair-data'): | ||
|
|
||
| Convert a Dataframe to a separate ``.csv`` file before visualiztion:: | ||
|
|
||
| to_csv(data, prefix='altair-data'): | ||
|
|
||
| Convert a Dataframe to inline JSON values before visualization:: | ||
|
|
||
| to_values(data): | ||
|
|
||
| Piping | ||
| ~~~~~~ | ||
|
|
||
| Multiple data transformers can be piped together using ``pipe``:: | ||
|
|
||
| from altair import pipe, limit_rows, to_values | ||
| pipe(data, limit_rows(10000), to_values) | ||
|
|
||
| Managing data transformers | ||
| ~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
|
|
||
| Altair maintains a registry of data transformers, which includes a default | ||
| data transformer that is automatically applied to all Dataframes before rendering. | ||
|
|
||
| To see the registered transformers:: | ||
|
|
||
| >>> import altair as alt | ||
| >>> alt.data_transformers.names() | ||
| ['default', 'json', 'csv'] | ||
|
|
||
| The default data transformer is the following:: | ||
|
|
||
| def default_data_transformer(data): | ||
| return pipe(data, limit_rows, to_values) | ||
|
|
||
| The ``json`` and ``csv`` data transformers will save a Dataframe to a temporary | ||
| ``.json`` or ``.csv`` file before rendering. There are a number of performance | ||
| advantages to these two data transformers: | ||
|
|
||
| * The full dataset will not be saved in the notebook document. | ||
| * The performance of the Vega-Lite/Vega JavaScript appears to be better | ||
| for standalone JSON/CSV files than for inline values. | ||
|
|
||
| There are disadvantages of the JSON/CSV data transformers: | ||
|
|
||
| * The Dataframe will be exported to a temporary ``.json`` or ``.csv`` | ||
| file that sits next to the notebook. | ||
| * That notebook will not be able to re-render the visualization without | ||
| that temporary file (or re-running the cell). | ||
|
|
||
| In our experience, the performance improvement is significant enough that | ||
| we recommend using the ``json`` data transformer for any large datasets:: | ||
|
|
||
| alt.data_transformers.enable('json') | ||
|
|
||
| We hope that others will write additional data transformers - imagine a | ||
| transformer which saves the dataset to a JSON file on S3, which could | ||
| be registered and enabled as:: | ||
|
|
||
| alt.data_transformers.register('s3', lambda data: pipe(sample, to_s3('mybucket'))) | ||
| alt.data_transformers.enable('s3') |
Oops, something went wrong.