Developer Documentation¶

Main API Functionality¶

class easymoney.money.EasyPeasy(precision=2, fall_back=True, fuzzy_threshold=False, data_path=None)[source]¶

Tools for Monetary Information and Conversions.

Parameters:

precision (int) – number of places to round to when returning results. Defaults to 2. fall_back (bool) – if True, fall back to closest possible date for which data is available. Defaults to True. fuzzy_match_threshold – a threshold for fuzzy matching confidence (requires the fuzzywuzzy package). The value must be an number between 0 and 100. The suggested minimum values is 85. This will only impact attempts to match on natural names, e.g., attempting to match ‘Canada’ by passing ‘Canadian’. If True, a threshold of 90 will be set. Defaults to False. Warning Fuzzy matching may yield inaccurate results. When possible, use terminology exactly as it appears in options(). data_path (str) – alternative path to the database file(s). Defaults to None.

currency_converter(amount, from_currency, to_currency, date='latest', pretty_print=False)[source]¶

Function to perform currency conversion based on, not directly reported from, data obtained from the European Central Bank (ECB). Base Currency: EUR.

Formulae Used

Let \(LCU\) be defined as:

\[LCU(\phi_{EUR}, CUR) = ExchangeRate_{\phi_{EUR} → CUR}\]

\(where\):

\(CUR\) is some local currency unit.

\(\phi = 1\), as in the ECB data.

That is, less formally:

\[LCU(\phi_{EUR}, CUR) = \dfrac{x \space \space CUR}{1 \space EUR}\]

\(Thus\):

From \(CUR_{1}\) to \(CUR_{2}\):

\[amount_{CUR_{2}} = \dfrac{1}{LCU(\phi_{EUR}, CUR_{1})} \cdot LCU(\phi_{EUR}, CUR_{2}) \cdot amount_{CUR_{1}}\]

Parameters:	amount (float or int) – an amount of money to be converted. from_currency (str) – the currency of the amount. to_currency (str) – the currency the amount is to be converted into. date (str) – date of data to perform the conversion with. Dates must be of the form: DD/MM/YYYY. pretty_print (bool) – if True, pretty prints the table otherwise returns the table as a pandas DataFrame. Defaults to False.
Returns:	converted currency.
Return type:	float

inflation(region, year_a, year_b=None, return_raw_cpi_dict=False, pretty_print=False)[source]¶

Calculator to compute the inflation rate from Consumer Price Index (CPI) information.

Inflation Formula:

\[Inflation_{region} = \dfrac{c_{1} - c_{2}}{c_{2}} \cdot 100\]

\(where\):

\(c_{1}\) = CPI of the region in year_b.

\(c_{2}\) = CPI of the region in year_a.

Parameters:	region (str) – a region. year_a (int) – start year. year_b (int) – end year. Defaults to None – can only be left to this default if return_raw_cpi_dict is True. return_raw_cpi_dict (bool) – If True, returns the CPI information in a dict. Defaults to False. pretty_print (bool) – if True, pretty prints the result otherwise returns the result as a float. Defaults to False.
Returns:	the rate of inflation between year_a and year_h. a dictionary of CPI information with the years as keys, CPI as values.
Return type:	float, dict or NaN

inflation_calculator(amount, region, year_a, year_b, pretty_print=False)[source]¶

Adjusts a given amount of money for inflation.

Parameters:	amount (float or int) – a monetary amount. region (str) – a geographical region. year_a (int) – start year. year_b (int) – end year. pretty_print (bool) – if True, pretty prints the result otherwise returns the result as a float. Defaults to False.
Returns:	\(amount \cdot inflation \space rate\).
Return type:	float or NaN

normalize(amount, region, from_year, to_year='latest', base_currency='EUR', exchange_date='latest', pretty_print=False)[source]¶

Convert a Nominal Amount of money to a Real Amount in the same, or another, currency.

This requires both inflation (for currency) and exchange rate information (currency to base_currency). See options(info = 'all', overlap_only = True) for an exhaustive listing of valid values to pass to this method.

Currency Normalization occurs in two steps:

1. Adjust the currency for inflation, e.g., 100 (2010 \(CUR_{1}\)) → x (2015 \(CUR_{1}\)).

2. Convert the adjusted amount into the base_currency.

Parameters:	amount (float or int) – a numeric amount of money. currency (str) – a region or currency. Legal options: Region Name, ISO Alpha2, Alpha3 or Currency Code (see options()). from_year (int) – a year. For valid values see options(). to_year (str or int) – a year. For valid values see options(). Defaults to ‘latest’ (which will use the most recent data available). base_currency (str) – a region or currency. Legal: Region Name, ISO Alpha2, Alpha3 or Currency Code (see options()). Defaults to ‘EUR’. pretty_print (bool) – Pretty print the result if True; return amount if False. Defaults to False.
Returns:	amount adjusted for inflation and converted into the base currency.
Return type:	float

options(info='all', rformat='table', pretty_print=True, table_overlap_only=False, range_table_dates=True)[source]¶

An easy interface to explore all of the terminology EasyPeasy understands as well the dates for which data is available.

Parameters:	info (str) – ‘exchange’, ‘inflation’ or ‘all’ (‘all’ requires rformat is set to ‘table’). rformat (str) – ‘table’ for a table or ‘list’ for just the currency codes, alone. Defaults to ‘table’. pretty_print (bool) – if True, prints the list or table. If False, returns the list or table (as a Pandas DataFrame). Defaults to True. table_overlap_only (bool) – when info is set to ‘all’, keep only those rows for which exchange rate and inflation data overlap. range_table_dates (bool) – if True, only report the minimum and maximum date for which data is available; if False, all dates for which data is available will be reported. Defaults to True.
Returns:	information table or list
Return type:	Pandas DataFrame or list

region_map(region, map_to='alpha_2')[source]¶

Map a ‘region’ to any one of: ISO Alpha 2, ISO Alpha 3, it’s Name or Offical Name.

Examples:

• EasyPeasy().region_map(region='CA', map_to='alpha_2') \(=\) ‘CA’
• EasyPeasy().region_map(region='Canada', map_to='alpha_3') \(=\) ‘CAN’

Parameters:	region (str) – a ‘region’ in the format of a ISO Alpha2, ISO Alpha3 or currency code, as well as natural name. map_to (str) – for region: ‘alpha_2’, ‘alpha_3’, ‘name’ or ‘official_name’. for currency: ‘currency_alpha_3’, ‘currency_numeric’ or ‘currency_name’. Defaults to ‘alpha_2’.
Returns:	the desired mapping from region to ISO Alpha2.
Return type:	str or tuple

Supporting Pandas Tools¶

easymoney.easy_pandas.align_pandas(data_frame, to_align='right')[source]¶

Align the columns of a Pandas DataFrame by adding whitespace.

Parameters:	data_frame (Pandas DataFrame) – a dataframe. to_align (str) – ‘left’, ‘right’, ‘center’ or a dictionary of the form: {'Column': 'Alignment'}.
Returns:	dataframe with aligned columns.
Return type:	Pandas DataFrame

easymoney.easy_pandas.items_null(element)[source]¶

Check if an object is a NaN, including all the elements in an iterable.

Parameters:	element (any) – a python object.
Returns:	assessment of whether or not element is a NaN.
Return type:	bool

easymoney.easy_pandas.pandas_list_column_to_str(data_frame, columns, join_on=', ', bracket_wrap=False)[source]¶

Tool for converting the columns in a Pandas DataFrame from pd.Series of lists into comma-seperated strings.

Parameters:	data_frame (Pandas DataFrame) – a dataframe. columns (list) – a list of columns in the DataFrame join_on (str) – a string to join on. Defaults to ”, ”.
Returns:	a dataframe with the columns altered in the manner described above.
Return type:	Pandas DataFrame

easymoney.easy_pandas.pandas_null_drop(data_frame, subset=None)[source]¶

Drop rows with NaNs of all, or a subset of, the dataframe’s columns. (Can handle iterables which only contain NaNs).

Parameters:	data_frame (Pandas DataFrame) – a dataframe. subset (iterable) – a subset of columns. Defaults to None, which will apply to all columns.
Returns:	dataframe with NaN dropped.
Return type:	Pandas DataFrame

easymoney.easy_pandas.pandas_pretty_print(data_frame, col_align='right', header_align='center', full_rows=True, full_cols=True)[source]¶

Pretty Print a Pandas DataFrame.

Parameters:	data_frame (Pandas DataFrame) – a dataframe. col_align (str or dict) – ‘left’, ‘right’, ‘center’’ or a dictionary of the form: {'Column': 'Alignment'}. header_align (str or dict) – alignment of headers. Must be one of: ‘left’, ‘right’, ‘center’. full_rows (bool) – print all rows. full_cols (bool) – print all columns.

easymoney.easy_pandas.pandas_print_full(pd_df, full_rows=True, full_cols=True)[source]¶

Print all of a Pandas DataFrame.

Parameters:	pd_df (Pandas DataFrame) – DataFrame to printed in its entirety. full_rows (bool) – print all rows if True. Defaults to True. full_cols (bool) – print all columns side-by-side if True. Defaults to True.

easymoney.easy_pandas.pandas_str_column_to_list(data_frame, columns)[source]¶

Tool for converting the columns in a Pandas DataFrame from comma-seperated strings into a pd.Series of lists.

Parameters:	data_frame (Pandas DataFrame) – a dataframe. columns (list) – a list of columns in the dataframe.
Returns:	a dataframe with the columns altered in the manner described above.
Return type:	Pandas DataFrame

easymoney.easy_pandas.prettify_all_pandas_list_cols(data_frame, join_on=', ', allow_nan=True, exclude=[], bracket_wrap=False)[source]¶

Converts all columns with only lists to list-seperated-strings.

Parameters:	data_frame (Pandas DataFrame) – a dataframe. allow_nan – allow nans join_on (str) – a string to join on. Defaults to ”, ”. exclude (list) – columns to exclude. Defaults to an empty list ([]). bracket_wrap (bool) – wrap in brackets.
Returns:	dataframe with columns lists converted to strings.
Return type:	Pandas DataFrame

easymoney.easy_pandas.pstr(s)[source]¶

Convert to any obect to a string using pandas.

Parameters:	s (any) – item to be converted to a string.
Returns:	a string
Return type:	str

easymoney.easy_pandas.strlist_to_list(to_parse, convert_to_str_first=False)[source]¶

Work around for using eval() for the following conversion: str(list) → list.

For example: "[1992, '221-21', 2102, 'apples']" → ['1992', '221-21', '2102', 'apples'].

Parameters:	to_parse (str) – a string of a list. convert_to_str_first (bool) – convert to a string first (as a precaution). Defaults to False.
Returns:	string of a list to an actual list.
Returns:	list

easymoney.easy_pandas.twoD_nested_dict(data_frame, nest_col_a=None, nest_col_b=None, nest_col_c=None, to_float=None, to_int=None, keys_to_str=True, engine='standard')[source]¶

Generate a nested dictionary from the columns of a pandas dataframe. Defaults to using the first 3 columns.

Parameters:	data_frame (Pandas DateFrame) – a pandas dataframe. nest_col_a (str) – reference to column in the dataframe; to become the master key in dict. Defaults to None (i.e., col 1). nest_col_b (str) – reference to column in the dataframe; to become the sub-key. Defaults to None (i.e., col 2). nest_col_c (str) – reference to column in the dataframe; to become the value to corresponding to the sub-key. Defaults to None (i.e., col 3). to_float (str) – a list items to float. Defaults to None. to_int (str) – a list of the lists to convert to ints. Defaults to None. keys_to_str (bool) – Convert the columns that will become keys to strings. Default to True. WARNING: will OVERRIDE to_float and to_int if they reference nest_col_a or nest_col_b. engine (str) – ‘standard’ for a slower (but well-tested) method of generating a nested dict; ‘fast’ to employ a speedy (but not well-tested) method for generating a nested dict. Default to ‘standard’.
Returns:	nested dict of the form: {nest_col_a: {nest_col_b: nest_col_c}.
Return type:	dict

easymoney.easy_pandas.type_in_series(series)[source]¶

Return the types of objects in a Pandas Series.

Parameters:	series (Pandas Series) – a series.
Returns:	list of the types in a series.
Return type:	list

European Central Bank Data¶

easymoney.sources.ecb_interface.ecb_xml_exchange_data(return_as='dict', ecb_extension='stats/eurofxref/eurofxref-hist.xml')[source]¶

This tool harvests XML data European Central Bank via their generously provided API.

Expects the follwing in the XML data: ‘time’, ‘currency’ and ‘rate’.

Returns either a Pandas DataFrame or nested dictionary of the form: {time: {currency: rate}}.

Please do not write procedures that slam their servers.

Parameters:	return_as (str) – ‘dict’ for dictionary (nested); ‘df’ for Pandas DataFrame OR ‘both’ for both a dict and DataFrame. ecb_extension (str) – URL to the exchange rate XML data on "http://www.ecb.europa.eu". Defaults to '/stats/eurofxref/eurofxref-hist.xml'.
Returns:	exchange rate with EUR as the base-currency.
Return type:	dict or Pandas DataFrame

World Bank Group Data¶

easymoney.sources.world_bank_interface.world_bank_pull(value_true_name=None, indicator='FP.CPI.TOTL', return_as='data_frame')[source]¶

Tool to harvest data for specific indicator from the World Bank Group via their generously provided API.

Extracts world bank information based on a specific indicator and returns a Pandas DataFrame.

Currently, this tools expects the following in the XML data: country, ISO alpha 2 code, an indicator, value name (to be replaced by value_true_name) and year.

Please do not write procedures that slam their servers.

Acknowledgement: this tools is made possible by the wbdata package.¹

¹Sherouse, Oliver (2014). Wbdata. Arlington, VA.

Parameters:	value_true_name (str) – reable name for the indicator. If None, this information will be extract from indicator. Defaults to None. indicator (str) – World Bank Indicator. Defaults to “FP.CPI.TOTL”. return_as (str) – ‘data_frame’ or ‘dict’
Returns:	DataFrame with the requested indicator information or a dictionary
Return type:	dict or Pandas DateFrame