How to Use asfreq() Function in Pandas


Often you may want to convert a time series to a difference frequency in pandas.

The most efficient way to do so is by using the asfreq() function, which is designed to perform this exact task.

The asfreq() function uses the following syntax:

DataFrame.asfreq(freq, method=None, how=None, normalize=False, fill_value=None)

where:

  • freq: The frequency to use
  • method: Method to use for filling in holes in reindexed Series (ffill=forward fill, bfill=backward fill)
  • how: For PeriodIndex only (‘start’ or ‘end’)
  • normalize: Whether to reset output index to midnight
  • fill_value: Values to use for filling in missing values

The following example shows how to use the asfreq() function in practice with a pandas DataFrame.

Example: How to Use the asfreq() Function in Pandas

Suppose we create the following pandas DataFrame that contains information about the total sales made by an employee at a company during 10 consecutive days:

import pandas as pd

#create DataFrame
df = pd.DataFrame({'sales': [2, 5, 5, 4, 7, 8, 9, 12, 10, 14]},
                  index=pd.date_range('2024-01-01', '2024-01-10'))

#view DataFrame
print(df)

            sales
2024-01-01      2
2024-01-02      5
2024-01-03      5
2024-01-04      4
2024-01-05      7
2024-01-06      8
2024-01-07      9
2024-01-08     12
2024-01-09     10
2024-01-10     14

Currently the index of the DataFrame is represented by individual days.

However, suppose that we would like to create an even more frequent time value to measure sales on, such as 12-hour intervals.

We could use the asfreq() function with the following syntax to do so:

#convert frequency of DataFrame to 12-hour intervals
df.asfreq(freq='12h')

	              sales
2024-01-01 00:00:00	2.0
2024-01-01 12:00:00	NaN
2024-01-02 00:00:00	5.0
2024-01-02 12:00:00	NaN
2024-01-03 00:00:00	5.0
2024-01-03 12:00:00	NaN
2024-01-04 00:00:00	4.0
2024-01-04 12:00:00	NaN
2024-01-05 00:00:00	7.0
2024-01-05 12:00:00	NaN
2024-01-06 00:00:00	8.0
2024-01-06 12:00:00	NaN
2024-01-07 00:00:00	9.0
2024-01-07 12:00:00	NaN
2024-01-08 00:00:00	12.0
2024-01-08 12:00:00	NaN
2024-01-09 00:00:00	10.0
2024-01-09 12:00:00	NaN
2024-01-10 00:00:00	14.0

Notice that the index of the DataFrame is now represented as 12-hour intervals.

Also notice that several NaN values are introduced as a result, since we created additional frequency intervals that did not previously have corresponding values in the sales column.

We can use the method  argument of the asfreq() function to specify how we would like to fill in these NaN values.

One way to do so is by specifying method=’ffill’, which allows us to forward-fill missing values:

#convert frequency of DataFrame to 12-hour intervals and forward fill missing values
df.asfreq(freq='12h', method='ffill')


sales
2024-01-01 00:00:00	2
2024-01-01 12:00:00	2
2024-01-02 00:00:00	5
2024-01-02 12:00:00	5
2024-01-03 00:00:00	5
2024-01-03 12:00:00	5
2024-01-04 00:00:00	4
2024-01-04 12:00:00	4
2024-01-05 00:00:00	7
2024-01-05 12:00:00	7
2024-01-06 00:00:00	8
2024-01-06 12:00:00	8
2024-01-07 00:00:00	9
2024-01-07 12:00:00	9
2024-01-08 00:00:00	12
2024-01-08 12:00:00	12
2024-01-09 00:00:00	10
2024-01-09 12:00:00	10
2024-01-10 00:00:00	14

All NaN values in the sales column have now been filled in with the previous value in the column, which is considered to be a form of forward-filling.

The other method we could use to fill in missing values is using the ‘bfill‘ option, which uses backward-filling instead.

We can use the following syntax to use this option:

#convert frequency of DataFrame to 12-hour intervals and backward fill missing values
df.asfreq(freq='12h', method='bfill')

	sales
2024-01-01 00:00:00	2
2024-01-01 12:00:00	5
2024-01-02 00:00:00	5
2024-01-02 12:00:00	5
2024-01-03 00:00:00	5
2024-01-03 12:00:00	4
2024-01-04 00:00:00	4
2024-01-04 12:00:00	7
2024-01-05 00:00:00	7
2024-01-05 12:00:00	8
2024-01-06 00:00:00	8
2024-01-06 12:00:00	9
2024-01-07 00:00:00	9
2024-01-07 12:00:00	12
2024-01-08 00:00:00	12
2024-01-08 12:00:00	10
2024-01-09 00:00:00	10
2024-01-09 12:00:00	14
2024-01-10 00:00:00	14

All NaN values in the sales column have now been filled in with the next available value in the column, which is considered to be a form of backward-filling.

Note that in most cases you will want to use forward-filling because it makes more sense to fill in values with the most recent value from the previous time period as opposed to filling in values with future time period values.

Note: You can find the complete documentation for the asfreq() function in pandas here.

Additional Resources

The following tutorials explain how to perform other common tasks in pandas:

How to Use the Rolling.apply() Function in Pandas
How to Use the nunique() Function in Pandas
How to Use the get_loc() Function in Pandas
How to Use idxmin() Function in Pandas

Featured Posts

Leave a Reply

Your email address will not be published. Required fields are marked *