Tax-Calculator Records

Tax-Calculator Records

taxcalc.records

class taxcalc.records.Records(data='puf.csv', start_year=2011, gfactors=<taxcalc.growfactors.GrowFactors object>, weights='puf_weights.csv.gz', adjust_ratios='puf_ratios.csv', exact_calculations=False, weights_scale=0.01)

Records is a subclass of the abstract Data class, and therefore, inherits its methods (none of which are shown here).

Constructor for the tax-filing-unit Records class.

Parameters:

• data (string or Pandas DataFrame) –

  string describes CSV file in which records data reside; DataFrame already contains records data; default value is the string ‘puf.csv’ NOTE: when using custom data, set this argument to a DataFrame. NOTE: to use your own data for a specific year with Tax-Calculator, be sure to read the documentation on creating your own data file and then construct a Records object like this: mydata = pd.read_csv(<mydata.csv>) myrec = Records(data=mydata, start_year=<mydata_year>,

  gfactors=None, weights=None)

  NOTE: data=None is allowed but the returned instance contains only

  the data variable information in the specified VARINFO file.

• start_year (integer) – specifies calendar year of the input data; default value is PUFCSV_YEAR. Note that if specifying your own data (see above NOTE) as being a custom data set, be sure to explicitly set start_year to the custom data’s calendar year.

• gfactors (GrowFactors class instance or None) – containing record data growth (or extrapolation) factors.

• weights (string or Pandas DataFrame or None) – string describes CSV file in which weights reside; DataFrame already contains weights; None creates empty sample-weights DataFrame; default value is filename of the PUF weights. NOTE: when using custom weights, set this argument to a DataFrame. NOTE: see weights_scale documentation below.

• adjust_ratios (string or Pandas DataFrame or None) –

  string describes CSV file in which adjustment ratios reside; DataFrame already contains transposed/no-index adjustment ratios; None creates empty adjustment-ratios DataFrame; default value is filename of the PUF adjustment ratios. NOTE: when using custom ratios, set this argument to a DataFrame. NOTE: if specifying a DataFrame, set adjust_ratios to my_df defined as:

  my_df = pd.read_csv(‘<my_ratios.csv>’, index_col=0).transpose()

• exact_calculations (boolean) – specifies whether or not exact tax calculations are done without any smoothing of stair-step provisions in income tax law; default value is false.

• weights_scale (float) – specifies the weights scaling factor used to convert contents of weights file into the s006 variable. PUF and CPS input data generated in the taxdata repository use a weights_scale of 0.01, while TMD input data generated in the tax-microdata repository use a 1.0 weights_scale value.

Raises:

ValueError: – if data is not the appropriate type. if taxpayer and spouse variables do not add up to filing-unit total. if dividends is less than qualified dividends. if gfactors is not None or a GrowFactors class instance. if start_year is not an integer. if files cannot be found.

Returns:

class instance

Return type:

Records

Notes

Typical usage when using PUF input data is as follows:

recs = Records()

which uses all the default parameters of the constructor, and therefore, imputed variables are generated to augment the data and initial-year grow factors are applied to the data. There are situations in which you need to specify the values of the Record constructor’s arguments, but be sure you know exactly what you are doing when attempting this.

Use Records.cps_constructor() to get a Records object instantiated with CPS input data developed in the taxdata repository.

Use Records.tmd_constructor() to get a Records object instantiated with TMD input data developed in the tax-microdata repository.

_adjust(year)

Adjust value of income variables to match SOI distributions Note: adjustment must leave variables as numpy.ndarray type

_extrapolate(year)

Apply to variables the grow factor values for specified calendar year.

_read_ratios(ratios)

Read Records adjustment ratios from file or use specified transposed/no-index DataFrame as ratios or create empty DataFrame if None

static cps_constructor(data=None, gfactors=<taxcalc.growfactors.GrowFactors object>, exact_calculations=False)

Static method returns a Records object instantiated with CPS input data. This works in a analogous way to Records(), which returns a Records object instantiated with PUF input data. This is a convenience method that eliminates the need to specify all the details of the CPS input data just as the default values of the arguments of the Records class constructor eliminate the need to specify all the details of the PUF input data.

increment_year()

Add one to current year, and also does extrapolation, reweighting, adjusting for new current year.

static read_cps_data()

Return data in cps.csv.gz as a Pandas DataFrame.