From 505ff69b11c696ddaf2512751ed08725185ca4ab Mon Sep 17 00:00:00 2001 From: "Weng, Chia-Ling" Date: Fri, 6 Oct 2023 11:27:53 +0800 Subject: [PATCH] [Doc] Add integers to four digit year format example --- doc/user_guide/encodings/index.rst | 32 ++++++++++++++++++++++++------ doc/user_guide/times_and_dates.rst | 7 ++++++- 2 files changed, 32 insertions(+), 7 deletions(-) diff --git a/doc/user_guide/encodings/index.rst b/doc/user_guide/encodings/index.rst index 4de8616fc..5dad018dc 100644 --- a/doc/user_guide/encodings/index.rst +++ b/doc/user_guide/encodings/index.rst @@ -198,23 +198,26 @@ Effect of Data Type on Axis Scales ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Similarly, for x and y axis encodings, the type used for the data will affect the scales used and the characteristics of the mark. For example, here is the -difference between a ``quantitative`` and ``ordinal`` scale for an column +difference between a ``quantitative`` , ``ordinal`` and ``temporal`` scale for an column that contains integers specifying a year: .. altair-plot:: - pop = data.population.url + pop = data.population() + # Convert interger to string data type + pop.year = pop.year.astype(str) - base = alt.Chart(pop).mark_bar().encode( + base = alt.Chart(pop).mark_line().encode( alt.Y('mean(people):Q').title('total population') ).properties( - width=200, + width=150, height=200 ) alt.hconcat( base.encode(x='year:Q').properties(title='year=quantitative'), - base.encode(x='year:O').properties(title='year=ordinal') + base.encode(x='year:O').properties(title='year=ordinal'), + base.encode(x='year:T').properties(title='year=temporal') ) Because quantitative values do not have an inherent width, the bars do not @@ -222,10 +225,15 @@ fill the entire space between the values. This view also makes clear the missing year of data that was not immediately apparent when we treated the years as categories. +To plot the year data as four digit format; i.e. without thousand separator, +we recommend converting integer to string data type first, then storing the data as temporal, +since directly convert integer to temporal data type would result in an error. + + This kind of behavior is sometimes surprising to new users, but it emphasizes the importance of thinking carefully about your data types when visualizing data: a visual encoding that is suitable for categorical data may not be -suitable for quantitative data, and vice versa. +suitable for quantitative data or temporal data, and vice versa. .. _shorthand-description: @@ -526,6 +534,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 ~~~~~~~~~~~~~~~ diff --git a/doc/user_guide/times_and_dates.rst b/doc/user_guide/times_and_dates.rst index 8f62b061c..372b68617 100644 --- a/doc/user_guide/times_and_dates.rst +++ b/doc/user_guide/times_and_dates.rst @@ -52,7 +52,12 @@ example, we'll limit ourselves to the first two weeks of data: (notice that for date/time values we use the ``T`` to indicate a temporal encoding: while this is optional for pandas datetime input, it is good practice -to specify a type explicitly; see :ref:`encoding-data-types` for more discussion). +to specify a type explicitly; see :ref:`encoding-data-types` for more discussion. + +If you want to plot integers as four digit year format stored as temporal data, +please see the :ref:`type-axis-scale`). + + For date-time inputs like these, it can sometimes be useful to extract particular time units (e.g. hours of the day, dates of the month, etc.).