Tax-Brain Utilities

utils

taxbrain.utils

Helper functions for the various taxbrain modules

taxbrain.utils.differences_plot(tb, tax_type: str, figsize: Tuple[Union[int, float], Union[int, float]] = (6, 4), title: str = 'default')[source]

Create a bar chart that shows the change in total liability for a given tax

Parameters
  • tb (TaxBrain object) – TaxBrain object for analysis

  • tax_type (str) – tax for which to show the change in liability options: ‘income’, ‘payroll’, ‘combined’

  • figsize (tuple) – representing the size of the figure (width, height) in inches

  • title (str) – title for plot

Returns

fig – differences plot

Return type

Matplotlib.pyplot figure object

taxbrain.utils.distribution_plot(tb, year: int, figsize: Tuple[Union[int, float], Union[int, float]] = (6, 4), title: str = 'default', include_text: bool = False)[source]

Create a horizontal bar chart to display the distributional change in after tax income

Parameters
  • tb (TaxBrain object) – TaxBrain object for analysis

  • year (int) – year to report distribution for

  • figsize (tuple) – representing the size of the figure (width, height) in inches

  • title (str) – title for plot

  • include_text (bool) – whether to include text for labels

Returns

fig – distribution plot

Return type

Matplotlib.pyplot figure object

taxbrain.utils.is_paramtools_format(reform: Union[str, Mapping[int, Any], List[ValueObject]])[source]

Check first item in reform to determine if it is using the ParamTools adjustment or the Tax-Calculator reform format.

If first item is a dict, then it is likely be a Tax-Calculator reform: {

param: {2020: 1000}

}

Otherwise, it is likely to be a ParamTools format.

Parameters

reform (str or dict) – parameters for tax policy

Returns

True if reform is likely to be in ParamTools format

Return type

bool

taxbrain.utils.lorenz_curve(tb, year: int, var: str = 'aftertax_income', figsize: Tuple[Union[int, float], Union[int, float]] = (6, 4), xlabel: str = 'Cummulative Percentage of Tax Units', ylabel: str = 'Cummulative Percentage of Income', base_color: Union[str, Tuple[float, float, float]] = 'blue', base_linestyle: str = '-', reform_color: Union[str, Tuple[float, float, float]] = 'red', reform_linestyle: str = '--', dpi: Union[int, float] = 100)[source]

Generate a Lorenz Curve

Parameters
  • tb (TaxBrain class object) – TaxBrain object for analysis

  • year (int) – year of data you want to use for the lorenz curve

  • var (str) – name of the variable to use

  • figsize (tuple) – representing the size of the figure (width, height) in inches

  • xlabel (str) – x axis label

  • ylabel (str) – y axis label

  • base_color (str) – color used for the base line

  • base_linestyle (str) – linestyle for the base line

  • reform_color (str) – color used for the reform line

  • reform_linestyle (str) – linestyle for the reform line

  • dpi (int) – dots per inch in the figure image

Returns

Return type

None

taxbrain.utils.lorenz_data(tb, year: int, var: str = 'aftertax_income')[source]

Pull data used for the lorenz curve plot

Parameters
  • tb (TaxBrain class object) – TaxBrain object for analysis

  • year (int) – year of data to use

  • var (str) – name of the variable to use

Returns

final_data – DataFrame with Lorenz curve for baseline and reform

Return type

Pandas DataFrame

taxbrain.utils.update_policy(policy_obj: taxcalc.policy.Policy, reform: Union[str, Mapping[int, Any], List[ValueObject]], **kwargs)[source]

Convenience method that updates the Policy object with the reform dict using the appropriate method, given the reform format.

Parameters
  • policy_obj (Tax-Calculator Policy class object) – Policy object for tax parameterization used for analysis

  • reform (str or dict) – parameters for tax policy

Returns

modifies the Policy object

Return type

None

taxbrain.utils.volcano_plot(tb, year: int, y_var: str = 'expanded_income', x_var: str = 'combined', min_y: Union[int, float] = 0.01, max_y: Union[int, float] = 9e+99, log_scale: bool = True, increase_color: Union[str, Tuple[float, float, float]] = '#F15FE4', decrease_color: Union[str, Tuple[float, float, float]] = '#41D6C2', dotsize: Union[int, float] = 0.75, alpha: float = 0.5, figsize: Tuple[Union[int, float], Union[int, float]] = (6, 4), dpi: Union[int, float] = 100, xlabel: str = 'Change in Tax Liability', ylabel: str = 'Expanded Income')[source]

Create a volcano plot to show change in tax tax liability

Parameters
  • tb (TaxBrain class object) – TaxBrain object for analysis

  • year (int) – year for the plot

  • min_y (float) – minimum amount for the y variable to be included in the plot

  • max_y (float) – maximum amount for the y variable to be included in the plot

  • y_var (str) – variable on the y axis

  • x_var (str) – variable on the x axis

  • log_scale (bool) – whether the y-axis should use a log scale. If this is true, min_inc must be >= 0

  • increase_color (str) – color to use for dots when x increases

  • decrease_color (str) – color to use for dots when x decrease

  • dotsize (int) – size of the dots in the scatter plot

  • alpha (float) – attribute for transparency of the dots

  • figsize (tuple) – the figure size of the plot (width, height) in inches

  • dpi (int) – dots per inch in the figure

  • xlabel (str) – label on the x axis

  • ylabel (str) – label on the y axis

Returns

fig – volcano plot figure

Return type

Matplotlib.pyplot figure object

taxbrain.utils.weighted_sum(df, var, wt='s006')[source]

Return the weighted sum of specified variable

Parameters
  • df (Pandas DataFrame) – data overwhich to compute weighted sum

  • var (str) – variable name from df for which to computer weighted sum

  • wt (str) – name of weight variable in df

Returns

weighted sum

Return type

float