API Reference

Inflation

class ausdex.inflation.CPI

A class to manage the Australian Consumer Index (CPI) data.

calc_inflation(value: Union[numbers.Number, numpy.ndarray, pandas.core.series.Series], original_date: Union[datetime.datetime, str], evaluation_date: Optional[Union[datetime.datetime, str]] = None, location: Union[ausdex.location.Location, str] = Location.AUSTRALIA)

Adjusts a value (or list of values) for inflation.

Parameters

  • value (Union[numbers.Number, np.ndarray, pd.Series]) – The value to be converted.

  • original_date (Union[datetime, str]) – The date that the value is in relation to.

  • evaluation_date (Union[datetime, str], optional) – The date to adjust the value to. Defaults to the current date.

  • location (Union[Location, str], optional) – The location for calculating the CPI. Options are ‘Australia’, ‘Sydney’, ‘Melbourne’, ‘Brisbane’, ‘Adelaide’, ‘Perth’, ‘Hobart’, ‘Darwin’, and ‘Canberra’. Default is ‘Australia’.

Returns

The adjusted value.

Return type

Union[float, np.ndarray]

cpi_at(date: Union[datetime.datetime, str, pandas.core.series.Series, numpy.ndarray], location: Union[ausdex.location.Location, str] = Location.AUSTRALIA) → Union[float, numpy.ndarray]

Returns the CPI (Consumer Price Index) for a date (or a number of dates).

If date is a string then it is converted to a datetime using dateutil.parser. If date is a vector then it returns a vector otherwise it returns a single scalar value. If date is before the earliest reference date (i.e. 1948-09-01) then it returns a NaN.

Parameters

  • date (Union[datetime, str, pd.Series, np.ndarray]) – The date(s) to get the CPI(s) for.

  • location (Union[Location, str], optional) – The location for calculating the CPI. Options are ‘Australia’, ‘Sydney’, ‘Melbourne’, ‘Brisbane’, ‘Adelaide’, ‘Perth’, ‘Hobart’, ‘Darwin’, and ‘Canberra’. Default is ‘Australia’.

Returns

The CPI value(s).

Return type

Union[float, np.ndarray]

cpi_series(location: Union[ausdex.location.Location, str] = Location.AUSTRALIA) → pandas.core.series.Series

Returns a Pandas Series with the Australian CPI (Consumer Price Index) per quarter.

This is taken from the latest spreadsheet from the Australian Bureau of Statistics (file id ‘640101’). The index of the series is the relevant date.

Parameters

location (Union[Location, str], optional) – The location for calculating the CPI. Options are ‘Australia’, ‘Sydney’, ‘Melbourne’, ‘Brisbane’, ‘Adelaide’, ‘Perth’, ‘Hobart’, ‘Darwin’, and ‘Canberra’. Default is ‘Australia’.

Returns

The CPIs per quarter.

Return type

pd.Series

latest_cpi_df

Returns a Pandas DataFrame with the latest Australian Consumer Price Index (CPI) data.

Returns

The latest Australian Consumer Price Index (CPI) data. The index of the series is the relevant date for each row.

Return type

pd.DataFrame

ausdex.inflation.calc_inflation(value: Union[numbers.Number, numpy.ndarray, pandas.core.series.Series], original_date: Union[datetime.datetime, str], evaluation_date: Optional[Union[datetime.datetime, str]] = None, location: Union[ausdex.location.Location, str] = Location.AUSTRALIA) → Union[float, numpy.ndarray]

Adjusts a value (or list of values) for inflation.

Parameters

  • value (numbers.Number, np.ndarray, pd.Series) – The value to be converted.

  • original_date (datetime, str) – The date that the value is in relation to.

  • evaluation_date (datetime, str, optional) – The date to adjust the value to. Defaults to the current date.

  • location (Location, str, optional) – The location for calculating the CPI. Options are ‘Australia’, ‘Sydney’, ‘Melbourne’, ‘Brisbane’, ‘Adelaide’, ‘Perth’, ‘Hobart’, ‘Darwin’, and ‘Canberra’. Default is ‘Australia’.

Returns

The adjusted value.

Return type

Union[float, np.ndarray]

ausdex.inflation.latest_cpi_df() → pandas.core.frame.DataFrame

Returns a pandas DataFrame with the latest CPI data from the Australian Bureau of Statistics.

This will contain the data for each quarter going back to 1948.

Returns

The latest dataframe with the CPI data.

Return type

pandas.DataFrame

Visualization

ausdex.viz.format_fig(fig)

Formats a plotly figure in a nicer way.

ausdex.viz.plot_cpi_change(start_date: Optional[Union[datetime.datetime, str]] = None, end_date: Optional[Union[datetime.datetime, str]] = None, output: Optional[Union[pathlib.Path, str]] = None, locations: Optional[List[ausdex.location.Location]] = None, title: Optional[str] = None, rba_target: bool = True) → plotly.graph_objs._figure.Figure

Produces a plot of the percentage change from corresponding quarter of previous year.

Parameters

  • start_date (datetime, str, optional) – Date to set the beginning of the time series graph. Defaults to None, which starts in 1948.

  • end_date (datetime, str, optional) – Date to set the end of the time series graph too. Defaults to None, which will set the end date to the most recent quarter.

  • output (Path, str, None) – If given, then the plot is written to this path.

Returns

The resulting plotly figure.

Return type

go.Figure

ausdex.viz.plot_cpi_timeseries(start_date: Optional[Union[datetime.datetime, str]] = None, end_date: Optional[Union[datetime.datetime, str]] = None, locations: Optional[List[ausdex.location.Location]] = None, title: Optional[str] = None, **kwargs) → plotly.graph_objs._figure.Figure

Plots CPI vs time.

Parameters

  • start_date (datetime, str, optional) – Date to set the beginning of the time series graph. Defaults to None, which starts in 1948.

  • end_date (datetime, str, optional) – Date to set the end of the time series graph too. Defaults to None, which will set the end date to the most recent quarter.

  • locations (List[Location], optional) – The location(s) for calculating the CPI. Options are ‘Australia’, ‘Sydney’, ‘Melbourne’, ‘Brisbane’, ‘Adelaide’, ‘Perth’, ‘Hobart’, ‘Darwin’, and ‘Canberra’. Default is ‘Australia’.

  • title – (str, optional): The title of the figure.

  • kwargs: – additional parameters to feed into plotly.express.line function.:

Returns

plot of cpi vs time

Return type

plotly.graph_objects.Figure

ausdex.viz.plot_inflation_timeseries(compare_date: Union[datetime.datetime, str], start_date: Optional[Union[datetime.datetime, str]] = None, end_date: Optional[Union[datetime.datetime, str]] = None, value: Union[float, int] = 1, location: Union[ausdex.location.Location, str] = Location.AUSTRALIA, **kwargs) → plotly.graph_objs._figure.Figure

Plots a time series of dollar values attached to a particular date’s dollar value

Parameters

  • compare_date (datetime, str) – Date to set relative value of the dollars too.

  • start_date (datetime, str, optional) – Date to set the beginning of the time series graph. Defaults to None, which starts in 1948.

  • end_date (datetime, str, optional) – Date to set the end of the time series graph too. Defaults to None, which will set the end date to the most recent quarter.

  • value (float, int, optional) – Value you in compare_date dollars to plot on the time series. Defaults to 1.

  • location (Location, str, optional) – The location for calculating the CPI. Options are ‘Australia’, ‘Sydney’, ‘Melbourne’, ‘Brisbane’, ‘Adelaide’, ‘Perth’, ‘Hobart’, ‘Darwin’, and ‘Canberra’. Default is ‘Australia’.

  • kwargs – (Optional(dict)): additional parameters to feed into plotly.express.line function

Returns

line graph of inflated dollar values vs time

Return type

plotly.graph_objects.Figure

ausdex.viz.write_fig(fig, output: Union[pathlib.Path, str])

Writes a plotly figure to file.

Parameters

  • fig (plotly figure) – The figure to be written

  • output (Path) – The path to the output file. If the directory does not exist, then it is created. Output can be PDF, SVG, JPG, PNG or HTML based on the extension.

Files

exception ausdex.files.DownloadError
ausdex.files.cached_download(url: str, local_path: Union[str, pathlib.Path], force: bool = False, verbose: bool = False) → None

Downloads a file if a local file does not already exist.

Parameters

  • url (str) – The url of the file to download.

  • local_path (str, Path) – The local path of where the file should be. If this file isn’t there or the file size is zero then this function downloads it to this location.

  • force (bool) – Whether or not the file should be forced to download again even if present in the local path. Default False.

Raises

  • DownloadError – Raises an exception if it cannot download the file.

  • IOError – Raises an exception if the file does not exist or is empty after downloading.

ausdex.files.cached_download_abs(id: str, quarter: str, year: Union[int, str], extension: str, local_path: Optional[Union[pathlib.Path, str]] = None, force: bool = False) → pathlib.Path

Downloads a file from the ABS if a local file does not already exist.

Parameters

  • id (str) – The ABS id for the datafile. For Australian Consumer Price Index the ID is 640101.

  • quarter (str) – The quarter of the file in question. One of “mar”, “jun”, “sep”, or “dec”.

  • year (str, int) – The year for the file in question.

  • extension (str) – The extension of the file in question.

  • local_path (str, Path) – The path to where the file should be downloaded. If None, then it is downloaded in the user’s cache directory.

  • force (bool) – Whether or not the file should be forced to download again even if present in the local path.

  • local_path – The local path of where the file should be. If this file isn’t there or the file size is zero then this function downloads it to this location.

  • force – Whether or not the file should be forced to download again even if present in the local path.

Raises

  • ValueError – If the value for quarter cannot be understood.

  • DownloadError – Raises an exception if it cannot download the file.

  • IOError – Raises an exception if the file does not exist or is empty after downloading.

Returns

The path to the downloaded ABS datafile.

Return type

Path

ausdex.files.cached_download_abs_excel(id: str, quarter: str, year: Union[str, int], local_path: Optional[Union[pathlib.Path, str]] = None, force: bool = False) → pathlib.Path

Gets am Excel file from the Australian Burau of Statistics.

First it tries the extension xlsx and then falls back to xls.

Parameters

  • id (str) – The ABS id for the datafile. For Australian Consumer Price Index the ID is 640101.

  • quarter (str) – The quarter of the file in question. One of “mar”, “jun”, “sep”, or “dec”.

  • year (str, int) – The year for the file in question.

  • local_path (Path, str, optional) – The path to where the file should be downloaded. If None, then it is downloaded in the user’s cache directory.

  • force (bool) – Whether or not the file should be forced to download again even if present in the local path. Default False.

Raises

ValueError – Raises this error if the quarter cannot be understood.

Returns

The path to the cached ABS datafile

Return type

Path

ausdex.files.cached_download_abs_excel_by_date(id: str, date: Optional[datetime.datetime] = None, local_path: Optional[Union[pathlib.Path, str]] = None, force: bool = False) → pathlib.Path

Gets a datafile from the Australian Burau of Statistics before a specific date.

Parameters

  • id (str) – The ABS id for the datafile. For Australian Consumer Price Index (CPI) the ID is 640101.

  • date (datetime, optional) – The date before which the CPI data should be valid. If not provided, then it uses today’s date download get the latest file.

  • local_path (Path, str, optional) – The path to where the file should be downloaded. If None, then it is downloaded in the user’s cache directory.

  • force (bool) – Whether or not the file should be forced to download again even if present in the local path. Default False.

Returns

The path to the cached ABS datafile.

Return type

Path

ausdex.files.cached_download_cpi(*, date: Optional[datetime.datetime] = None, local_path: Optional[Union[pathlib.Path, str]] = None, force: bool = False) → pathlib.Path

Returns the path to the latest cached file with the Australian Consumer Price Index (CPI) data.

It downloads the file if it does not exist already. The ABS id of this file is “640101”.

Parameters

  • date (datetime, optional) – The date before which the CPI data should be valid. If not provided, then it uses today’s date download get the latest file.

  • local_path (Path, str, optional) – The path to where the file should be downloaded. If None, then it is downloaded in the user’s cache directory.

  • force (bool) – Whether or not the file should be forced to download again even if present in the local path. Default False.

Returns

The path to the cached datafile.

Return type

Path

ausdex.files.get_cached_path(filename: str) → pathlib.Path

Returns a path in the ausdex directory in the user’s cache.

File may or may not exist.

Main

ausdex.main.docs(live: bool = True)

Builds the documentation.

Parameters

live (bool, optional) – Whether or not to use sphinx-autobuild to automatically build the documentation as files are edited. Defaults to True.

ausdex.main.inflation(value: float = <typer.models.ArgumentInfo object>, original_date: str = <typer.models.ArgumentInfo object>, evaluation_date: str = <typer.models.OptionInfo object>, location: ausdex.location.Location = <typer.models.OptionInfo object>)

Adjusts Australian dollars for inflation.

Prints output to stdout.

Parameters

  • value (float) – The dollar value to be converted.

  • original_date (str) – The date that the value is in relation to.

  • evaluation_date (str, optional) – The date to adjust the value to. Defaults to the current date.

  • location (Location, optional) – The location for calculating the CPI. Options are ‘Australia’, ‘Sydney’, ‘Melbourne’, ‘Brisbane’, ‘Adelaide’, ‘Perth’, ‘Hobart’, ‘Darwin’, and ‘Canberra’. Default is ‘Australia’.

ausdex.main.main(version: Optional[bool] = <typer.models.OptionInfo object>)

Adjusts Australian dollars for inflation.

ausdex.main.plot_cpi(show: bool = <typer.models.OptionInfo object>, output: pathlib.Path = <typer.models.OptionInfo object>, start_date: str = <typer.models.OptionInfo object>, end_date: str = <typer.models.OptionInfo object>, location: List[ausdex.location.Location] = <typer.models.OptionInfo object>, title: str = <typer.models.OptionInfo object>)

Plot the Australian CPI over time.

Parameters

  • show (bool) – Whether or not to show the figure in a browser. Default True.

  • output (Path) – The path to where the figure will be saved. Output can be PDF, SVG, JPG, PNG or HTML based on the extension.

  • start_date (str, optional) – Date to set the beginning of the time series graph. If empty, it defaults to 1948.

  • end_date (str, optional) – Date to set the end of the time series graph too. If empty, then the end date to the most recent quarter.

  • location (List[location]) – The location for calculating the CPI.

  • title (str, optional) – A custom title of the plot.

ausdex.main.plot_cpi_change(show: bool = <typer.models.OptionInfo object>, start_date: str = <typer.models.OptionInfo object>, end_date: str = <typer.models.OptionInfo object>, output: pathlib.Path = <typer.models.OptionInfo object>, location: List[ausdex.location.Location] = <typer.models.OptionInfo object>, title: str = <typer.models.OptionInfo object>)

Produces a plot of the percentage change from corresponding quarter of previous year.

Parameters

  • show (bool) – Whether or not to show the figure in a browser. Default True.

  • output (Path) – The path to where the figure will be saved. Output can be PDF, SVG, JPG, PNG or HTML based on the extension.

  • location (List[location]) – The location for calculating the CPI.

ausdex.main.plot_inflation(compare_date: str = <typer.models.ArgumentInfo object>, show: bool = <typer.models.OptionInfo object>, output: pathlib.Path = <typer.models.OptionInfo object>, start_date: str = <typer.models.OptionInfo object>, end_date: str = <typer.models.OptionInfo object>, value: float = <typer.models.OptionInfo object>, location: ausdex.location.Location = <typer.models.OptionInfo object>)

Plots a time series of dollar values attached to a particular date’s dollar value.

Parameters

  • compare_date (str) – Date to set relative value of the dollars too.

  • out (Path) – The path to where the figure will be saved. Output can be PDF, JPG, PNG or HTML based on the extension.

  • start_date (str, optional) – Date to set the beginning of the time series graph. Defaults to None, which starts in 1948.

  • end_date (str, optional) – Date to set the end of the time series graph too. Defaults to None, which will set the end date to the most recent quarter.

  • value (float, optional) – Value you in compare_date dollars to plot on the time series. Defaults to 1.

ausdex.main.repo()

Opens the repository in a web browser.