From d72795f886730af8aa9e347aac7c1ec641bfdf3d Mon Sep 17 00:00:00 2001 From: Rita Weng Date: Thu, 5 Oct 2023 09:55:46 +0800 Subject: [PATCH 1/8] [Doc] Update UserGuide: Add Rotate Axis Method --- doc/user_guide/customization.rst | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) diff --git a/doc/user_guide/customization.rst b/doc/user_guide/customization.rst index be44055b1..2dd299e14 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,20 @@ 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") + ).configure_axisY( + titleAngle=0, + titleAlign="left", + titleY=0, + titleX=0, + ) + Additional formatting codes are available; for a listing of these see the `d3 Format Code Documentation `_. From 1bab8fda17dd475f1c66fb25b6895c51238cad33 Mon Sep 17 00:00:00 2001 From: Rita Weng Date: Thu, 5 Oct 2023 13:19:25 +0800 Subject: [PATCH 2/8] [Doc] Update User Guide: Add sort legend using EncodingSortField example --- doc/user_guide/encodings/index.rst | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/doc/user_guide/encodings/index.rst b/doc/user_guide/encodings/index.rst index 4de8616fc..71af88463 100644 --- a/doc/user_guide/encodings/index.rst +++ b/doc/user_guide/encodings/index.rst @@ -526,6 +526,18 @@ While the above examples show sorting of axes by specifying ``sort`` in the Here the y-axis is sorted reverse-alphabetically, while the color legend is sorted in the specified order, beginning with ``'Morris'``. +Here is another example using :class:`EncodingSortField` class to sort color legend. +By specifying ``field``, ``op`` and ``order``, the legend can be sorted based on chosen data field. + +.. altair-plot:: + + alt.Chart(barley).mark_rect().encode( + alt.X('mean(yield):Q').sort('ascending'), + alt.Y('site:N').sort('x'), + color=alt.Color('site', + sort=alt.EncodingSortField(field='yield', op='mean', order='ascending')) + ) + Datum and Value ~~~~~~~~~~~~~~~ From dfccf806ef0ad7302ea8a3950ebc4296fa558254 Mon Sep 17 00:00:00 2001 From: Rita Weng Date: Thu, 5 Oct 2023 16:16:32 +0800 Subject: [PATCH 3/8] =?UTF-8?q?[Doc]=20=EF=BC=A1=EF=BD=84=EF=BD=84?= =?UTF-8?q?=E3=80=80=EF=BC=A3=EF=BD=89=EF=BD=94=EF=BD=89=EF=BD=8E=EF=BD=87?= =?UTF-8?q?=E3=80=80=EF=BC=B3=EF=BD=85=EF=BD=83=EF=BD=94=EF=BD=89=EF=BD=8F?= =?UTF-8?q?=EF=BD=8E=E3=80=80?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- doc/about/citing.rst | 41 +++++++++++++++++++++++++++++++++++++++++ doc/about/roadmap.rst | 1 + 2 files changed, 42 insertions(+) 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 From 18fa168660b5a1913ed847fc774b7998165e2a9d Mon Sep 17 00:00:00 2001 From: Rita Weng Date: Thu, 5 Oct 2023 16:16:32 +0800 Subject: [PATCH 4/8] Add Citing Section --- doc/about/citing.rst | 41 +++++++++++++++++++++++++++++++++++++++++ doc/about/roadmap.rst | 1 + 2 files changed, 42 insertions(+) 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 From 0a75361ff1844e1eb9f662b720470983dc759f80 Mon Sep 17 00:00:00 2001 From: Joel Ostblom Date: Sat, 7 Oct 2023 17:50:14 -0700 Subject: [PATCH 5/8] Update to new sorting without explicit encoding field and fix a few small typos --- doc/user_guide/encodings/index.rst | 32 ++++++++++++++---------------- 1 file changed, 15 insertions(+), 17 deletions(-) diff --git a/doc/user_guide/encodings/index.rst b/doc/user_guide/encodings/index.rst index 71af88463..bce932e13 100644 --- a/doc/user_guide/encodings/index.rst +++ b/doc/user_guide/encodings/index.rst @@ -408,8 +408,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: @@ -475,7 +474,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:: @@ -498,26 +499,24 @@ 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' ]) @@ -531,11 +530,10 @@ By specifying ``field``, ``op`` and ``order``, the legend can be sorted based on .. altair-plot:: - alt.Chart(barley).mark_rect().encode( - alt.X('mean(yield):Q').sort('ascending'), - alt.Y('site:N').sort('x'), - color=alt.Color('site', - sort=alt.EncodingSortField(field='yield', op='mean', order='ascending')) + 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='mean', order='ascending') ) Datum and Value From e7f797caa758a8c82846f7fdc694ded35e95c6cb Mon Sep 17 00:00:00 2001 From: "Weng, Chia-Ling" <75072960+ChiaLingWeng@users.noreply.github.com> Date: Tue, 10 Oct 2023 14:38:16 +0800 Subject: [PATCH 6/8] Avoid configure_axis method and use .axis() directly Co-authored-by: Joel Ostblom --- doc/user_guide/customization.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/user_guide/customization.rst b/doc/user_guide/customization.rst index 2dd299e14..dd8cb063e 100644 --- a/doc/user_guide/customization.rst +++ b/doc/user_guide/customization.rst @@ -309,8 +309,8 @@ Axis title can also be rotated: alt.Chart(df).mark_circle().encode( alt.X('x').axis(title="x"), - alt.Y('y').axis(title="Y Axis Title") - ).configure_axisY( + alt.Y('y').axis( + title="Y Axis Title", titleAngle=0, titleAlign="left", titleY=0, From 2cd9876a8723da0c1f18b125c0c6d247a7d3c2a6 Mon Sep 17 00:00:00 2001 From: Joel Ostblom Date: Sun, 15 Oct 2023 19:25:21 -0700 Subject: [PATCH 7/8] Fix parenthesis --- doc/user_guide/customization.rst | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/doc/user_guide/customization.rst b/doc/user_guide/customization.rst index dd8cb063e..d8c9849a4 100644 --- a/doc/user_guide/customization.rst +++ b/doc/user_guide/customization.rst @@ -308,13 +308,14 @@ 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=0, - titleX=0, + 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 From 358658ebb338d3e180a8f6e1c8488253a2a108ae Mon Sep 17 00:00:00 2001 From: Joel Ostblom Date: Sun, 15 Oct 2023 19:25:31 -0700 Subject: [PATCH 8/8] Clarify text --- doc/user_guide/encodings/index.rst | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/doc/user_guide/encodings/index.rst b/doc/user_guide/encodings/index.rst index bce932e13..027d6cb24 100644 --- a/doc/user_guide/encodings/index.rst +++ b/doc/user_guide/encodings/index.rst @@ -522,18 +522,20 @@ Below we show an example using the :class:`Color` encoding: ]) ) -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'``. -Here is another example using :class:`EncodingSortField` class to sort color legend. -By specifying ``field``, ``op`` and ``order``, the legend can be sorted based on chosen data field. +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='mean', order='ascending') + color=alt.Color('site').sort(field='yield', op='max', order='ascending') ) Datum and Value