Tax scales#

The policyengine_core.taxscales module contains classes used to represent tax scales (parameters that are numeric functions of a variable).

TaxScaleLike#

class policyengine_core.taxscales.tax_scale_like.TaxScaleLike(name: Optional[str] = None, option: Optional[Any] = None, unit: Optional[Any] = None)[source]#

Bases: ABC

Base class for various types of tax scales: amount-based tax scales, rate-based tax scales…

RateTaxScaleLike#

class policyengine_core.taxscales.rate_tax_scale_like.RateTaxScaleLike(name: Optional[str] = None, option: Optional[Any] = None, unit: Optional[Any] = None)[source]#

Bases: TaxScaleLike, ABC

Base class for various types of rate-based tax scales: marginal rate, linear average rate…

bracket_indices(tax_base: NumericalArray, factor: float = 1.0, round_decimals: Optional[int] = None) → numpy.int_[source]#

Compute the relevant bracket indices for the given tax bases.

Parameters:

  • tax_base (ndarray) – Array of the tax bases.

  • factor (float) – Factor to apply to the thresholds.

  • round_decimals (int) – Decimals to keep when rounding thresholds.

Returns:

Integer array with relevant bracket indices for the given tax bases.

For instance:

>>> tax_scale = LinearAverageRateTaxScale()
>>> tax_scale.add_bracket(0, 0)
>>> tax_scale.add_bracket(100, 0.1)
>>> tax_base = array([0, 150])
>>> tax_scale.bracket_indices(tax_base)
[0, 1]
threshold_from_tax_base(tax_base: NumericalArray) → NumericalArray[source]#

Compute the relevant thresholds for the given tax bases.

Param:

ndarray tax_base: Array of the tax bases.

Returns:

Floating array with relevant thresholds for the given tax bases.

For instance:

>>> import numpy
>>> from policyengine_core import taxscales
>>> tax_scale = taxscales.MarginalRateTaxScale()
>>> tax_scale.add_bracket(0, 0)
>>> tax_scale.add_bracket(200, 0.1)
>>> tax_scale.add_bracket(500, 0.25)
>>> tax_base = numpy.array([450, 1_150, 10])
>>> tax_scale.threshold_from_tax_base(tax_base)
array([200, 500,   0])

AbstractTaxScale#

class policyengine_core.taxscales.abstract_tax_scale.AbstractTaxScale(name: Optional[str] = None, option: Any = None, unit: numpy.int_ = None)[source]#

Bases: TaxScaleLike

Base class for various types of tax scales: amount-based tax scales, rate-based tax scales…

AbstractRateTaxScale#

class policyengine_core.taxscales.abstract_rate_tax_scale.AbstractRateTaxScale(name: Optional[str] = None, option: Optional[Any] = None, unit: Optional[Any] = None)[source]#

Bases: RateTaxScaleLike

Base class for various types of rate-based tax scales: marginal rate, linear average rate…

bracket_indices(tax_base: NumericalArray, factor: float = 1.0, round_decimals: Optional[int] = None) → numpy.int_#

Compute the relevant bracket indices for the given tax bases.

Parameters:

  • tax_base (ndarray) – Array of the tax bases.

  • factor (float) – Factor to apply to the thresholds.

  • round_decimals (int) – Decimals to keep when rounding thresholds.

Returns:

Integer array with relevant bracket indices for the given tax bases.

For instance:

>>> tax_scale = LinearAverageRateTaxScale()
>>> tax_scale.add_bracket(0, 0)
>>> tax_scale.add_bracket(100, 0.1)
>>> tax_base = array([0, 150])
>>> tax_scale.bracket_indices(tax_base)
[0, 1]
threshold_from_tax_base(tax_base: NumericalArray) → NumericalArray#

Compute the relevant thresholds for the given tax bases.

Param:

ndarray tax_base: Array of the tax bases.

Returns:

Floating array with relevant thresholds for the given tax bases.

For instance:

>>> import numpy
>>> from policyengine_core import taxscales
>>> tax_scale = taxscales.MarginalRateTaxScale()
>>> tax_scale.add_bracket(0, 0)
>>> tax_scale.add_bracket(200, 0.1)
>>> tax_scale.add_bracket(500, 0.25)
>>> tax_base = numpy.array([450, 1_150, 10])
>>> tax_scale.threshold_from_tax_base(tax_base)
array([200, 500,   0])

AmountTaxScaleLike#

class policyengine_core.taxscales.amount_tax_scale_like.AmountTaxScaleLike(name: Optional[str] = None, option: Optional[Any] = None, unit: Optional[Any] = None)[source]#

Bases: TaxScaleLike, ABC

Base class for various types of amount-based tax scales: single amount, marginal amount…

SingleAmountTaxScale#

class policyengine_core.taxscales.single_amount_tax_scale.SingleAmountTaxScale(name: Optional[str] = None, option: Optional[Any] = None, unit: Optional[Any] = None)[source]#

Bases: AmountTaxScaleLike

calc(tax_base: NumericalArray, right: bool = False) → numpy.float_[source]#

Matches the input amount to a set of brackets and returns the single cell value that fits within that bracket.

MarginalRateTaxScale#

class policyengine_core.taxscales.marginal_rate_tax_scale.MarginalRateTaxScale(name: Optional[str] = None, option: Optional[Any] = None, unit: Optional[Any] = None)[source]#

Bases: RateTaxScaleLike

bracket_indices(tax_base: NumericalArray, factor: float = 1.0, round_decimals: Optional[int] = None) → numpy.int_#

Compute the relevant bracket indices for the given tax bases.

Parameters:

  • tax_base (ndarray) – Array of the tax bases.

  • factor (float) – Factor to apply to the thresholds.

  • round_decimals (int) – Decimals to keep when rounding thresholds.

Returns:

Integer array with relevant bracket indices for the given tax bases.

For instance:

>>> tax_scale = LinearAverageRateTaxScale()
>>> tax_scale.add_bracket(0, 0)
>>> tax_scale.add_bracket(100, 0.1)
>>> tax_base = array([0, 150])
>>> tax_scale.bracket_indices(tax_base)
[0, 1]
calc(tax_base: NumericalArray, factor: float = 1.0, round_base_decimals: Optional[int] = None) → numpy.float_[source]#

Compute the tax amount for the given tax bases by applying a taxscale.

Parameters:

  • tax_base (ndarray) – Array of the tax bases.

  • factor (float) – Factor to apply to the thresholds of the taxscale.

  • round_base_decimals (int) – Decimals to keep when rounding thresholds.

Returns:

Float array with tax amount for the given tax bases.

For instance:

>>> tax_scale = MarginalRateTaxScale()
>>> tax_scale.add_bracket(0, 0)
>>> tax_scale.add_bracket(100, 0.1)
>>> tax_base = array([0, 150])
>>> tax_scale.calc(tax_base)
[0.0, 5.0]
inverse() → MarginalRateTaxScale[source]#

Returns a new instance of MarginalRateTaxScale.

Invert a taxscale:

Assume tax_scale composed of bracket whose thresholds are expressed in terms of gross revenue.

The inverse is another MarginalRateTaxScale whose thresholds are expressed in terms of net revenue.

If net = gross_revenue - tax_scale.calc(gross_revenue) Then gross = tax_scale.inverse().calc(net)

marginal_rates(tax_base: NumericalArray, factor: float = 1.0, round_base_decimals: Optional[int] = None) → numpy.float_[source]#

Compute the marginal tax rates relevant for the given tax bases.

Parameters:

  • tax_base (ndarray) – Array of the tax bases.

  • factor (float) – Factor to apply to the thresholds of a tax scale.

  • round_base_decimals (int) – Decimals to keep when rounding thresholds.

Returns:

Float array with relevant marginal tax rate for the given tax bases.

For instance:

>>> tax_scale = MarginalRateTaxScale()
>>> tax_scale.add_bracket(0, 0)
>>> tax_scale.add_bracket(100, 0.1)
>>> tax_base = array([0, 150])
>>> tax_scale.marginal_rates(tax_base)
[0.0, 0.1]
rate_from_bracket_indice(bracket_indice: int64) → float64[source]#

Compute the relevant tax rates for the given bracket indices.

Param:

ndarray bracket_indice: Array of the bracket indices.

Returns:

Floating array with relevant tax rates for the given bracket indices.

For instance:

>>> import numpy
>>> tax_scale = MarginalRateTaxScale()
>>> tax_scale.add_bracket(0, 0)
>>> tax_scale.add_bracket(200, 0.1)
>>> tax_scale.add_bracket(500, 0.25)
>>> tax_base = numpy.array([50, 1_000, 250])
>>> bracket_indice = tax_scale.bracket_indices(tax_base)
>>> tax_scale.rate_from_bracket_indice(bracket_indice)
array([0.  , 0.25, 0.1 ])
rate_from_tax_base(tax_base: NumericalArray) → numpy.float_[source]#

Compute the relevant tax rates for the given tax bases.

Param:

ndarray tax_base: Array of the tax bases.

Returns:

Floating array with relevant tax rates for the given tax bases.

For instance:

>>> import numpy
>>> tax_scale = MarginalRateTaxScale()
>>> tax_scale.add_bracket(0, 0)
>>> tax_scale.add_bracket(200, 0.1)
>>> tax_scale.add_bracket(500, 0.25)
>>> tax_base = numpy.array([1_000, 50, 450])
>>> tax_scale.rate_from_tax_base(tax_base)
array([0.25, 0.  , 0.1 ])
scale_tax_scales(factor: float) → MarginalRateTaxScale[source]#

Scale all the MarginalRateTaxScales in the node.

threshold_from_tax_base(tax_base: NumericalArray) → NumericalArray#

Compute the relevant thresholds for the given tax bases.

Param:

ndarray tax_base: Array of the tax bases.

Returns:

Floating array with relevant thresholds for the given tax bases.

For instance:

>>> import numpy
>>> from policyengine_core import taxscales
>>> tax_scale = taxscales.MarginalRateTaxScale()
>>> tax_scale.add_bracket(0, 0)
>>> tax_scale.add_bracket(200, 0.1)
>>> tax_scale.add_bracket(500, 0.25)
>>> tax_base = numpy.array([450, 1_150, 10])
>>> tax_scale.threshold_from_tax_base(tax_base)
array([200, 500,   0])

MarginalAmountTaxScale#

class policyengine_core.taxscales.marginal_amount_tax_scale.MarginalAmountTaxScale(name: Optional[str] = None, option: Optional[Any] = None, unit: Optional[Any] = None)[source]#

Bases: AmountTaxScaleLike

calc(tax_base: NumericalArray, right: bool = False) → numpy.float_[source]#

Matches the input amount to a set of brackets and returns the sum of cell values from the lowest bracket to the one containing the input.

LinearAverageRateTaxScale#

class policyengine_core.taxscales.linear_average_rate_tax_scale.LinearAverageRateTaxScale(name: Optional[str] = None, option: Optional[Any] = None, unit: Optional[Any] = None)[source]#

Bases: RateTaxScaleLike

bracket_indices(tax_base: NumericalArray, factor: float = 1.0, round_decimals: Optional[int] = None) → numpy.int_#

Compute the relevant bracket indices for the given tax bases.

Parameters:

  • tax_base (ndarray) – Array of the tax bases.

  • factor (float) – Factor to apply to the thresholds.

  • round_decimals (int) – Decimals to keep when rounding thresholds.

Returns:

Integer array with relevant bracket indices for the given tax bases.

For instance:

>>> tax_scale = LinearAverageRateTaxScale()
>>> tax_scale.add_bracket(0, 0)
>>> tax_scale.add_bracket(100, 0.1)
>>> tax_base = array([0, 150])
>>> tax_scale.bracket_indices(tax_base)
[0, 1]
threshold_from_tax_base(tax_base: NumericalArray) → NumericalArray#

Compute the relevant thresholds for the given tax bases.

Param:

ndarray tax_base: Array of the tax bases.

Returns:

Floating array with relevant thresholds for the given tax bases.

For instance:

>>> import numpy
>>> from policyengine_core import taxscales
>>> tax_scale = taxscales.MarginalRateTaxScale()
>>> tax_scale.add_bracket(0, 0)
>>> tax_scale.add_bracket(200, 0.1)
>>> tax_scale.add_bracket(500, 0.25)
>>> tax_base = numpy.array([450, 1_150, 10])
>>> tax_scale.threshold_from_tax_base(tax_base)
array([200, 500,   0])