series_collection module

The series_collection module contains the SeriesCollection implementation.

SeriesCollection is meant to make handling multiple series easier. Often users of the FRED API will want analyze multiple economic series. This can be done with FredSeries alone, but can be tedious and cumbersome. pyfredapi offers the SeriesCollection class to streamline the process of collecting and munging the data for plotting and analysis.

SeriesCollection

A collection of pyfredapi.SeriesData objects.

Useful when you need to collect and manage multiple economic series. Provides methods for listing metadata, collecting data, and merging data together in long or wide formats.

data property

data: list[SeriesData]

Returns data in the SeriesCollection.

Returns:

Type	Description
list[SeriesData]

__init__

__init__(series_id: Union[Sequence[str], str], api_key: Union[str, None] = None, rename: Union[Dict[str, str], Callable[[str], str], None] = None, drop_realtime: bool = True, sleep: float = 0.1, **kwargs)

Create an instance of SeriesCollection.

Parameters:

Name	Type	Description	Default
series_id	Sequence[str] | str	Sequence of series IDs to add to collection.	required
api_key	str | None	FRED API key. Defaults to None. If None, will search for FRED_API_KEY in environment variables.	None
drop_realtime	bool	Indicates if you want to drop the realtime columns.	True
rename	Union[Dict[str, str], Callable[[str], str], None]	Label to give series. Defaults to series ID.	None
sleep	float	Time to sleep between requests. Defaults to 0.1.	0.1
**kwargs	dict	Additional parameters to FRED API series/ endpoint. Refer to the FRED documentation for a list of all possible parameters.	{}

add

add(series_id: Union[str, Sequence[str]], **kwargs) -> None

Add series to the collection.

A request to the FRED api will be made for the series. The data will be formatted as as pandas dataframe.

After adding a series, you can access it via an attribute or in the responses dict.

Parameters:

Name	Type	Description	Default
series_id	Union[str, Sequence[str]]	Series to add to collection.	required
**kwargs	dict	Additional parameters to FRED API series/ endpoint. Refer to the FRED documentation for a list of all possible parameters.	{}

list_end_date

list_end_date() -> None

List the series' latest date.

list_frequency

list_frequency() -> None

List the series' frequency.

list_seasonality

list_seasonality() -> None

List the series' seasonality.

list_series

list_series() -> None

List the series' id and title.

list_start_date

list_start_date() -> None

List the series' earliest date.

list_units

list_units() -> None

List the series' measurement units.

merge_asof

merge_asof(base_series_id: str) -> pd.DataFrame

Merge the series in the collection into a wide pandas dataframe based on nearest date.

Uses pandas merge_asof methods to merge the data based on nearest date.

Parameters:

Name	Type	Description	Default
base_series_id	str	Series ID of the series to serve of the basis for joining.	required

Returns:

Type	Description
DataFrame	Wide pandas dataframe.

merge_long

merge_long(col_name: Union[str, None] = None, include_info_attrs: bool = False) -> pd.DataFrame

Merge the series in the collection into a long pandas dataframe.

Parameters:

Name	Type	Description	Default
col_name	str | None	Name to give columns holding the series id/label.	None
include_info_attrs	bool	If True, all the attributes from the SeriesInfo will be included on the dataframe.	False

Returns:

Type	Description
DataFrame	Long pandas dataframe.

merge_wide

merge_wide() -> pd.DataFrame

Merge the series in the collection into a wide pandas dataframe. Only works if all the series in the collection share the same date index.

Returns:

Type	Description
DataFrame	Wide pandas dataframe.

remove

remove(series_id: Union[str, Sequence[str]]) -> None

Remove series from collection.

Parameters:

Name	Type	Description	Default
series_id	Union[str, Sequence[str]]	Series ids to remove from collection.	required

rename_series

rename_series(rename)

Rename series columns.

series_info_to_df

series_info_to_df() -> pd.DataFrame

Concatenate SeriesInfo into pandas DataFrame.

SeriesData dataclass

Represents the response from series/observations endpoint.

Parameters:

Name	Type	Description	Default
info	SeriesInfo	A series info object.	required
df	DataFrame	Series data in a pandas dataframe.	required

plot

plot() -> Figure

Create a plotly <https://plotly.com/python/>_ time series plot.

Raises:

Type	Description
ValueError	If data format is not a pandas dataframe.

Returns:

Type	Description
Figure	A plotly figure <https://plotly.com/python-api-reference/generated/plotly.graph_objects.Figure.html>_.