From c915818ac7a3a2d244c4bbf384bfa7868c6ff9f1 Mon Sep 17 00:00:00 2001 From: "Weng, Chia-Ling" <75072960+ChiaLingWeng@users.noreply.github.com> Date: Mon, 16 Oct 2023 11:14:36 +0800 Subject: [PATCH] [Doc] Update UserGuide: Add Rotate Axis, Sort Legend Example, Citing Section (#3217) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * [Doc] Update UserGuide: Add Rotate Axis Method * [Doc] Update User Guide: Add sort legend using EncodingSortField example * [Doc] Ａｄｄ　Ｃｉｔｉｎｇ　Ｓｅｃｔｉｏｎ　 * Add Citing Section * Update to new sorting without explicit encoding field and fix a few small typos * Avoid configure_axis method and use .axis() directly Co-authored-by: Joel Ostblom * Fix parenthesis * Clarify text --------- Co-authored-by: Rita Weng Co-authored-by: Joel Ostblom Co-authored-by: Joel Ostblom --- doc/about/citing.rst | 41 ++++++++++++++++++++++++++++++ doc/about/roadmap.rst | 1 + doc/user_guide/customization.rst | 17 ++++++++++++- doc/user_guide/encodings/index.rst | 38 +++++++++++++++++---------- 4 files changed, 83 insertions(+), 14 deletions(-) create mode 100644 doc/about/citing.rst diff --git a/doc/about/citing.rst b/doc/about/citing.rst new file mode 100644 index 000000000..2e1e2fd7a --- /dev/null +++ b/doc/about/citing.rst @@ -0,0 +1,41 @@ +Citing +=============== + +Vega-Altair +----------- +If you use Vega-Altair in academic work, please consider citing +`Altair: Interactive Statistical Visualizations for Python `_ as + +.. code-block:: + + @article{VanderPlas2018, + doi = {10.21105/joss.01057}, + url = {https://doi.org/10.21105/joss.01057}, + year = {2018}, + publisher = {The Open Journal}, + volume = {3}, + number = {32}, + pages = {1057}, + author = {Jacob VanderPlas and Brian Granger and Jeffrey Heer and Dominik Moritz and Kanit Wongsuphasawat and Arvind Satyanarayan and Eitan Lees and Ilia Timofeev and Ben Welsh and Scott Sievert}, + title = {Altair: Interactive Statistical Visualizations for Python}, + journal = {Journal of Open Source Software} + } + +Vega-Lite +--------- +Please additionally consider citing the +`Vega-Lite `_ project, which Vega-Altair is based on: +`Vega-Lite: A Grammar of Interactive Graphics `_ + +.. code-block:: + + @article{Satyanarayan2017, + author={Satyanarayan, Arvind and Moritz, Dominik and Wongsuphasawat, Kanit and Heer, Jeffrey}, + title={Vega-Lite: A Grammar of Interactive Graphics}, + journal={IEEE transactions on visualization and computer graphics}, + year={2017}, + volume={23}, + number={1}, + pages={341-350}, + publisher={IEEE} + } \ No newline at end of file diff --git a/doc/about/roadmap.rst b/doc/about/roadmap.rst index 07f8fe576..9dd20ca34 100644 --- a/doc/about/roadmap.rst +++ b/doc/about/roadmap.rst @@ -162,3 +162,4 @@ Areas of focus: self code_of_conduct governance + citing diff --git a/doc/user_guide/customization.rst b/doc/user_guide/customization.rst index be44055b1..d8c9849a4 100644 --- a/doc/user_guide/customization.rst +++ b/doc/user_guide/customization.rst @@ -294,7 +294,7 @@ the y labels as a dollar value: alt.Y('y').axis(format='$').title('dollar amount') ) -Axis labels can also be easily removed: +Axis labels can be easily removed: .. altair-plot:: @@ -303,6 +303,21 @@ Axis labels can also be easily removed: alt.Y('y').axis(labels=False) ) +Axis title can also be rotated: + +.. altair-plot:: + + alt.Chart(df).mark_circle().encode( + alt.X('x').axis(title="x"), + alt.Y('y').axis( + title="Y Axis Title", + titleAngle=0, + titleAlign="left", + titleY=-2, + titleX=0, + ) + ) + Additional formatting codes are available; for a listing of these see the `d3 Format Code Documentation `_. diff --git a/doc/user_guide/encodings/index.rst b/doc/user_guide/encodings/index.rst index 87fa7c3e7..56db07138 100644 --- a/doc/user_guide/encodings/index.rst +++ b/doc/user_guide/encodings/index.rst @@ -422,8 +422,7 @@ options available to change the sort order: sort. For example ``sort='-x'`` would sort by the x channel in descending order. - Passing a list to ``sort`` allows you to explicitly set the order in which you would like the encoding to appear -- Passing a :class:`EncodingSortField` class to ``sort`` allows you to sort - an axis by the value of some other field in the dataset. +- Using the ``field`` and ``op`` parameters to specify a field and aggregation operation to sort by. Here is an example of applying these five different sort approaches on the x-axis, using the barley dataset: @@ -489,7 +488,9 @@ x-axis, using the barley dataset: The last two charts are the same because the default aggregation (see :ref:`encoding-aggregates`) is ``mean``. To highlight the difference between sorting via channel and sorting via field consider the -following example where we don't aggregate the data: +following example where we don't aggregate the data +and use the `op` parameter to specify a different aggregation than `mean` +to use when sorting: .. altair-plot:: @@ -512,34 +513,45 @@ following example where we don't aggregate the data: sortfield = base.encode( alt.X('site:N').sort(field='yield', op='max') ).properties( - title='By Min Yield' + title='By Max Yield' ) sortchannel | sortfield -By passing a :class:`EncodingSortField` class to ``sort`` we have more control over -the sorting process. - Sorting Legends ^^^^^^^^^^^^^^^ -While the above examples show sorting of axes by specifying ``sort`` in the +Just as how the above examples show sorting of axes by specifying ``sort`` in the :class:`X` and :class:`Y` encodings, legends can be sorted by specifying -``sort`` in the :class:`Color` encoding: +``sort`` in the encoding used in the legend (e.g. color, shape, size, etc). +Below we show an example using the :class:`Color` encoding: .. altair-plot:: - alt.Chart(barley).mark_rect().encode( - alt.X('mean(yield):Q').sort('ascending'), - alt.Y('site:N').sort('descending'), + alt.Chart(barley).mark_bar().encode( + alt.X('mean(yield):Q'), + alt.Y('site:N').sort('x'), alt.Color('site:N').sort([ 'Morris', 'Duluth', 'Grand Rapids', 'University Farm', 'Waseca', 'Crookston' ]) ) -Here the y-axis is sorted reverse-alphabetically, while the color legend is +Here the y-axis is sorted based on the x-values, while the color legend is sorted in the specified order, beginning with ``'Morris'``. +In the next example, +specifying ``field``, ``op`` and ``order``, +sorts the legend sorted based on a chosen data field +and operation. + +.. altair-plot:: + + alt.Chart(barley).mark_bar().encode( + alt.X('mean(yield):Q'), + alt.Y('site:N').sort('x'), + color=alt.Color('site').sort(field='yield', op='max', order='ascending') + ) + Datum and Value ~~~~~~~~~~~~~~~