What is the DataFrame.pivot() function in Polars?

Polars is an efficient DataFrame library whose primary purpose is to offer fast and efficient data processing. The Polars library achieves this by employing various functions designed to select and manipulate table data. These functions are accessible through the DataFrame object, and one example is the pivot() function.

The DataFrame.pivot function

The DataFrame.pivot function provides the functionality of generating a spreadsheet-style table as a DataFrame. It allows for the restructuring of the table and changing its shape. Additionally, an aggregate function can be used to calculate aggregates of values in addition to the restructuring.

Let’s look at an example:

The example above takes a table with columns “Class,” “Subject,” and “Score.” The table uses the pivot function to transform the table. This transformation takes place by making the “Subject” data into the columns, making the “Class” data the index, and making the “Score” data the values of the table.

Syntax

The syntax for the function is as follows:

There are more parameters that the function provides for generating even more specific tables. Let’s discuss all of these parameters.

Parameters

• values: This parameter indicates the column values that are to be aggregated. It can be multiple columns as well.

• index: This parameter is for the keys to group by (it can be one or many).

• columns: This represents the name of the columns whose values would be the header of the output DataFrame.

• aggregate_function: This is the aggregate function that would be applied. It can be a pre-defined function or a custom expression.

• maintain_order: This parameter takes a boolean value of true or false. If true, the grouped keys are sorted to make the output order predictable.

• sort_columns: This sorts the order of the transposed columns. The default order is that of discovery.

• separator: This is used as a separator or delimiter in column names. 

Code example

Let’s look at an example of using the function in code.

Let’s look at a detailed explanation of the code above.

• Line 1: We are importing the Polars library as pl.

• Line 3: We are creating a new DataFrame and storing it in df.

• Lines 4–8: This is the definition of the new DataFrame that we are creating. The DataFrame we’ve created is of two classes, the subjects they offer, and the score of the class in those subjects. We have three columns Class, Subject, and Score that illustrate the score of these classes in each subject.

• Line 11: We are now pivoting this table. The values that are to be aggregated (though we are not using an aggregate function) are the scores. The new index is derived from the Class column, while the Subject column serves as the header of the output DataFrame. The values for this new table are taken from the Score column. We are storing this new pivoted table in new_df.

• Line 12: We are displaying the new pivoted table, new_df.

Let’s look at another complex example, which also uses an aggregate function.

We’ll now look at the code for the pivoted table above.

• Lines 4–8: This is the definition of the new DataFrame that we’re creating. The DataFrame we have created is for the sales of two products across two months. We have three columns Month, Subject, and Sales that illustrate the sales of the two products: Chocolate and Biscuit across Jan and Feb.

• Lines 12–16: This is values on which df is being pivoted. The new index is derived from the Month column, while the Product column serves as the header of the output DataFrame. The values for this new table are taken from the Sales column. The values are summed by setting the value of the aggregate_function to sum. The sort_columns is set to False to not order the new table.

Conclusion

There are various functions that allow us to manipulate table data and retrieve results according to our needs. The pivot() function is an example of such a function. It allows the transformation of the table by restructuring the table and changing its shape.