Python API

Warning

Please note that salamanca is still in early developmental stages, thus all interfaces are subject to change.

Inequality Calculations: salamanca.ineq

class salamanca.ineq.LogNormal(**kwargs)

An interfrace to the log-normal distribution.

For mathematical descriptions see ScipyLogNorm.

Parameters

incnumeric, optional, default: 1

meanbool, optional, default: True

whether income is representative of mean (True) or median (False)

gininumeric, optional

theilnumeric, optional

Methods

below_threshold(threshold, **kwargs)	Returns the fraction of population below a given income threshold (equivalent to cdf).
cdf(x, **kwargs)	See ScipyLogNorm
lorenz(x, **kwargs)	The Lorenz curve for log-normal distributions is defined as:
mean(**kwargs)	See ScipyLogNorm
median(**kwargs)	See ScipyLogNorm
params(**kwargs)	Returns (shape, scale) tuple for use in scipy.stats.lognorm
pdf(x, **kwargs)	See ScipyLogNorm
ppf(x, **kwargs)	See ScipyLogNorm
std(**kwargs)	See ScipyLogNorm
var(**kwargs)	See ScipyLogNorm

below_threshold(threshold, **kwargs)

Returns the fraction of population below a given income threshold (equivalent to cdf).

Parameters

thresholdnumeric

income threshold

cdf(x, **kwargs)

See ScipyLogNorm

lorenz(x, **kwargs)

The Lorenz curve for log-normal distributions is defined as:

\[L(x) = \Phi \left( \Phi^{-1} (x) - \sigma \right)\]

Where \(\Phi\) is cumulative distribution function (CDF) of the standard normal distribution.

mean(**kwargs)

See ScipyLogNorm

median(**kwargs)

See ScipyLogNorm

params(**kwargs)

Returns (shape, scale) tuple for use in scipy.stats.lognorm

pdf(x, **kwargs)

See ScipyLogNorm

ppf(x, **kwargs)

See ScipyLogNorm

std(**kwargs)

See ScipyLogNorm

var(**kwargs)

See ScipyLogNorm

class salamanca.ineq.LogNormalData(**kwargs)

Object for storing and updating LogNormal distribution data

Methods

update([copy, override])

Update attributes.

add_defaults
check

salamanca.ineq.gini_to_std(g)

Returns \(\sigma = 2 * erf^{-1}(g)\)

salamanca.ineq.gini_to_theil(g, empirical=False)

Translate gini to theil

\[t(g) = \sqrt{2} \Phi^{-1} \left( \frac{1 + g}{2} \right)\]

Where \(\Phi\) is cumulative distribution function (CDF) of the standard normal distribution.

Parameters

gnumeric or array-like

gini coefficient(s)

empiricalbool, optional, default: False

whether to use empirical relationship for theil

salamanca.ineq.std_to_gini(s)

Returns \(g = erf( \frac{\sigma}{2} )\)

salamanca.ineq.std_to_theil(s)

Returns \(t = \frac{\sigma^2}{2}\)

salamanca.ineq.theil_to_gini(t, empirical=False)

Translate theil to gini

\[t(g) = \sqrt{2} \Phi^{-1} \left( \frac{1 + g}{2} \right)\]

Where \(\Phi\) is cumulative distribution function (CDF) of the standard normal distribution.

Parameters

tnumeric or array-like

theil coefficient(s)

empiricalbool, optional, default: False

whether to use empirical relationship for theil

salamanca.ineq.theil_to_std(t)

Returns \(\sigma = \sqrt{2t}\)

Currency Translation: salamanca.currency

class salamanca.currency.Translator

An object to translate between national currencies in different years

By default, inflation is calculated using GDP Deflators (though CPI is available as well).

Currencies are assumed to be in MER. If in PPP, ‘units’ must be set appropriately.

Calculation is formulated based on: http://www.iiasa.ac.at/web/home/research/Flagship-Projects/Global-Energy-Assessment/GEA_Annex_II.pdf

Methods

exchange(x[, iso, yr, units, fromiso, …])	Exchange currency from one country/year to another.
inflation(iso, fromyr, toyr[, method])	Calculate inflation for a country

mer_to_ppp
ppp_to_mer

exchange(x, iso=None, yr=None, units='MER', fromiso=None, fromyr=None, toiso=None, toyr=None, inusd=False, inflation_method='deflator')

Exchange currency from one country/year to another.

Parameters

x: float

quantity of currency

iso: str, optional

a 3-letter ISO code

yr: int, optional

the year

units: str, optional

current currency units one of: PPP or MER

fromiso: str, optional

a 3-letter ISO code for the origin country

fromyr: int, optional

the year initial year

toiso: str, optional

a 3-letter ISO code for the destination country

fromyr: int, optional

the year final year

inusd: bool, optional

return currency in USD of the final year

inflation_method: str, optional

the argument to provide to inflation()

inflation(iso, fromyr, toyr, method='deflator')

Calculate inflation for a country

Parameters

iso: str

a 3-letter ISO code

fromyr: int

the starting year

toyr: int

the ending year

method: str

one of: cpi, deflator (default: deflator)

Economic Indicators: salamanca.data

A module for querying datasources (e.g., the World Bank Indicators). They can optionally be stored locally to reduce internet queries.

class salamanca.data.WorldBank

A simple object for querying the World Bank’s REST API

Methods

query(indicator[, tries, use_cache, overwrite])

kwargs include iso ‘date’, ‘MRV’, ‘Gapfill’, ‘frequency’

cpi
exchange_rate
gdp_deflator
household_fraction_gdp
iso_metadata
ppp_to_mer
to_long
to_wide

query(indicator, tries=5, use_cache=True, overwrite=False, **kwargs)

kwargs include iso ‘date’, ‘MRV’, ‘Gapfill’, ‘frequency’

salamanca.data.query_rest_api(url, params=None, tries=5)

Query a REST API online

Parameters

urlstr

url to query

triesint, optional

number of times to try query before raising an IOError