Tax-Brain Utilities

utils

taxbrain.utils

Helper functions for the various taxbrain modules

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

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[int | float, int | float] = (6, 4), title: str = 'default', include_text: bool = False)

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: str | Mapping[int, Any] | List[ValueObject])

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[int | float, int | float] = (6, 4), xlabel: str = 'Cummulative Percentage of Tax Units', ylabel: str = 'Cummulative Percentage of Income', base_color: str | Tuple[float, float, float] = 'blue', base_linestyle: str = '-', reform_color: str | Tuple[float, float, float] = 'red', reform_linestyle: str = '--', dpi: int | float = 100)

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

Return type:

None

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

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: Policy, reform: str | Mapping[int, Any] | List[ValueObject], **kwargs)

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: int | float = 0.01, max_y: int | float = 9e+99, log_scale: bool = True, increase_color: str | Tuple[float, float, float] = '#F15FE4', decrease_color: str | Tuple[float, float, float] = '#41D6C2', dotsize: int | float = 0.75, alpha: float = 0.5, figsize: Tuple[int | float, int | float] = (6, 4), dpi: int | float = 100, xlabel: str = 'Change in Tax Liability', ylabel: str = 'Expanded Income')

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')

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