Altair Alt.x

[Doria Vilcan]

Whetherto override the figure's native width with the width ofthe parent container. If use_container_width is False(default), Streamlit sets the width of the chart to fit its contentsaccording to the plotting library, up to the width of the parentcontainer. If use_container_width is True, Streamlit setsthe width of the figure to match the width of the parent container.

To use selection events, the object passed to altair_chart mustinclude selection paramters. To learn about defining interactionsin Altair and how to declare selection-type parameters, seeInteractive Chartsin Altair's documentation.

When Streamlit uses a selection parameter, selections from thatparameter will trigger a rerun and be included in the selectionstate. When Streamlit does not use a selection parameter,selections from that parameter will not trigger a rerun and not beincluded in the selection state.

If on_select is "ignore" (default), this method returns aninternal placeholder for the chart element that can be used withthe .add_rows() method. Otherwise, this method returns adictionary-like object that supports both key and attributenotation. The attributes are described by the VegaLiteStatedictionary schema.

The state of the on_select event. This attribure returns adictionary-like object that supports both key and attribute notation.The name of each Vega-Lite selection parameter becomes an attribute inthe selection dictionary. The format of the data within eachattribute is determined by the selection parameter definition withinVega-Lite.

The following two examples have equivalent definitions. Each one has apoint and interval selection parameter include in the chart definition.The point seleciton parameter is named "point_selection". The intervalor box selection parameter is named "interval_selection".

Try selecting points in this interactive example. When you click a point,the selection will appear under the attribute, "point_selection", whichis the name given to the point selection parameter. Similarly, when youmake an interval selection, it will appear under the attribute"interval_selection". You can give your selection parameters othernames if desired.

Altair charts are displayed using the Streamlit theme by default. This theme is sleek, user-friendly, and incorporates Streamlit's color palette. The added benefit is that your charts better integrate with the rest of your app's design.

If you're wondering if your own customizations will still be taken into account, don't worry! You can still make changes to your chart configurations. In other words, although we now enable the Streamlit theme by default, you can overwrite it with custom colors or fonts. For example, if you want a chart line to be green instead of the default red, you can do it!

In most cases, we suggest that you use the first approach, because it is morestraightforward to those who are familiar with data manipulation in Python, andbecause the Pandas package offers much more flexibility than Vega-Lite inavailable data manipulations.

The second approach becomes useful when the data source is not a dataframe, but,for example, a URL pointer to a JSON or CSV file. It can also be useful in acompound chart where different views of the dataset require differenttransformations.

If at least one fields in the specified encoding channels contain aggregate,the resulting visualization will show aggregate data. In this case, allfields without aggregation function specified are treated as group-by fieldsin the aggregation process.

The advantage of the top-level transform is that the same named field can beused in multiple places in the chart if desired.Note the slight difference in binning behavior between the encoding-based binnings(which preserve the range of the bins) and the transform-based binnings (whichcollapse each bin to a single representative value.

To streamline building these vega expressions in Python, Altair provides thealtair.expr module which provides constants and functions to allowthese expressions to be constructed with Python syntax; for example:

Altair expressions are designed to output valid Vega expressions. The benefit ofusing them is that proper syntax is ensured by the Python interpreter, and tabcompletion of the expr submodule can be used to explore theavailable functions and constants.

The filter transform removes objects from a data stream based on a providedfilter expression, selection, or other filter predicate. A filter can beadded at the top level of a chart using the Chart.transform_filter()method. The argument to transform_filter can be one of a number ofexpressions and objects:

Selection predicates can be used to filter data based on a selection. Whilethese can be constructed directly using a SelectionPredicate class,in Altair it is often more convenient to construct them using theselection() function. For example, this chart uses a multi-selectionthat allows the user to click or shift-click on the bars in the bottom chartto select the data to be shown in the top chart:

These are not yet part of the Altair interface(see Issue 693)but can be constructed explicitly; for example, here we plot US populationdistributions for all data except the years 1950-1960,by applying a LogicalNotPredicate schema to a FieldRangePredicate:

The lookup transform extends a primary data source by looking up values fromanother data source; it is similar to a one-sided join. A lookup can be addedat the top level of a chart using the Chart.transform_lookup() method.

By way of example, imagine you have two sources of data that you would liketo combine and plot: one is a list of names of people along with their heightand weight, and the other is some information about which groups they belongto. This example data is available in vega_datasets:

If we would like to plot features that reference both datasets (for example, theaverage age within each group), we need to combine the two datasets.This can be done either as a data preprocessing step, using tools availablein Pandas, or as part of the visualization using a LookupTransformin Altair.

Pandas provides a wide range of tools for merging and joining datasets; seeMerge, Join, and Concatenatefor some detailed examples.For the above data, we can merge the data and create a combined chart as follows:

Here lookup names the field in the groups dataset on which we will match,and the from_ argument specifies a LookupData structure wherewe supply the second dataset, the lookup key, and the fields we would like toextract.

Lookup transforms are often particularly important for geographic visualization,where it is common to combine tabular datasets with datasets that specifygeographic boundaries to be visualized; for example, here is a visualizationof unemployment rates per county in the US:

TimeUnit transforms are used to discretize dates and times within Altair.As with the Aggregate Transforms and Bin transformsdiscussed above, they can be defined either as part of the encoding, or as atop-level transform.

The plot is too busy due to the amount of data points squeezed into the shorttime; we can make it a bit cleaner by discretizing it, for example, by monthand plotting only the mean monthly temperature:

Notice that by default timeUnit output is a continuous quantity; if you wouldinstead like it to be a categorical, you can specify the ordinal (O) ornominal (N) type.This can be useful when plotting a bar chart or other discrete chart type:

Multiple time units can be combined within a single plot to yield interestingviews of your data; for example, here we extract both the month and the dayto give a profile of Seattle temperatures through the year:

Other times it is convenient to specify a timeUnit as a top-level transform,particularly when the value may be reused.This can be done most conveniently using the Chart.transform_timeunit()method. For example:

The Window transform performs calculations over sorted groups of data objects.These calculations including ranking, lead/lag analysis, and aggregates suchas running sums and averages. Calculated values are written back to theinput data stream, where they can be referenced in encodings.

You might wish to plot these bars in units of percentage of total time rather thanin units of hours. You can do this by combining a calculate transform with awindow transform, using transform_window():

Window transforms are quite flexible, and are not yet well documented withinAltair. For more information on the arguments of the window transform, seeWindowTransform, or see theVega-Lite window transform examples.

The Vega-Lite specification includes the ability to apply awide range of transformations to input data within the chartspecification. As an example, here is a sliding window averageof a Gaussian random walk, implemented in Altair:

This is where altair_transform comes in. It includes a (nearly)complete Python implementation of Vega-Lite's transform layer, sothat you can easily extract a pandas dataframe with the computedvalues shown in the chart:

Altair creates chart specifications containing the full dataset.The advantage of this is that the data used to make the chart is entirely transparent; the disadvantage is that it causes issues as datasets grow large.To prevent users from inadvertently crashing their browsers by trying to send too much data to the frontend, Altair limits the data size by default.For example, a histogram of 20000 points:

There are several possible ways around this, as mentioned in Altair's FAQ.Altiar-transform provides another option via the transform_chart() function, which will pre-transform the data according to the chart specification, so that the final chart specification holds the aggregated data rather than the full dataset:

Matplotlib has been enormously successful at making Python viable as a standard language for scientific computing and data analysis. In recent years, however, there have been new developments both in terms of computation and in the data visualization world, and alternatives have emerged.

3a8082e126