The following assumes successful installation of the OSPC-ACA project as described here. And it also assumes that you have read the documentation about how to specify and use your own sample input files.
In addition to reading a sample file that contains ACA-relevant information for one or more federal income tax filing units, the ptc.py script reads a policy file that contains ACA-relevant projection assumptions (such as the inflation rate in future years) and policy parameters (such as those that describe the shape of the function that translates a filing unit's modified AGI as a percent of the federal poverty level into the fraction of modified AGI that the filing unit is expected to pay for health insurance, which IRS Form 8962 calls the "applicable figure"). A policy file must be written in JSON and the file may include //-style trailing comments that provide extra documentation but are never read by the ptc.py script. Read the aca_current_law.json file to see an example of a policy input file.
Parametric Reforms
The current version of the ptc.py script can read a limited number of assumption and policy parameters. If you want to change one or more of those parameters, proceed as follows: (a) copy the baseline policy file to a new alternative policy file, (b) edit the alternative policy file to have different parameter values, (c) save the ptc.py script output files generated by using the same sample input file with the baseline policy file and with the alternative policy file, and (d) compare the two output files to see the implications for tax filing units of the parameter differences between the baseline and the alternative policy files.
A common situation is when the baseline policy file represents current-law policy (that is, aca_current_law.json) and the baseline policy file represents some kind of policy reform. In that case, the differences between the two output files show the impact of the policy reform on the tax filing units included in the sample file.
Another common situation is when there is no change in policy parameters, but there is a difference in assumption parameters. For example, both the baseline and alternative policy files contain current-law policy parameters, but contain different assumed rates of future inflation in second-lowest-cost Silver plan premiums.
When you specify a new policy file, be sure that you understand the rules that the ptc.py script uses to compute parameter values in years that are not explicitly specified in a policy file. There are two simple rules. First, the value of a parameter in the last year specified in the policy file is project forward to the end of the simulation at that last specified value. And second, the value of a parameter in an unspecified year that has a subsequent specified year is computed using linear interpolation between the immediately preceding specified year and the immediately subsequent specified year. In summary, unspecified values that have a subsequent value are filled in using linear interpolation and unspecified values that have no subsequent value are filled in by extrapolating the final specified value. If you have any doubts about how these rules work you can read the Python source code to gain a better understanding or you can explicitly specify all the parameters in every simulation year.
Here is an extended example of a parametric reform that shows how to estimate the effect of somewhat higher Silver plan premiums in the future. In this example, we use aca_current_law.json as the baseline policy file. It assumes quite arbitrarily that assumption and policy parameters are projected through calendar year 2018; that the rate of poverty level inflation is two percent per year in every year after 2015; that the rate of increase in second-lowest-cost Silver plan premiums is two and one-half percent from 2015 to 2016, and three percent from 2016 to 2017 and from 2017 to 2018; and that there are no state or federal legislative or judicial changes in policy during the 2016-2018 period.
We copy the baseline aca_current_law.json file to the alternative file named aca_higher_prem.json. Then we edit the leading comment to describe the new alternative policy file and edit the silvprem_inflation_factor parameter values so that the assumed rate of increase in second-lowest-cost Silver plan premiums is somewhat higher: three percent (instead of two and one-half) from 2015 to 2016, four percent (instead of three) from 2016 to 2017, and five percent (instead of three) from 2017 to 2018.
When you are doing this kind of work, your productivity will be much higher if you use a graphical difference program that shows you the two policy files side-by-side with the differences highlighted. There are many such programs that are freely-available on whatever operating system you are using. Reviewing your work with such a program helps find typos and other mistakes that would produce ptc.py error messages or potentially confusing ptc.py output.
Now that we have both the baseline and alternative policy files prepared, let us specify a sample file that contains just one tax filing unit in 2018, when second-lowest-cost Silver plan premiums will be slightly more than 3.4 percent higher in the alternative simulation than in the baseline simulation. This sample_18_example file contains a single sixty-year-old person who lives in Denver (which is in Colorado rating area three), has a 2018 income of twenty-four thousand dollars and no employer-sponsored health insurance. The contents of the sample_18_example file are as follows:
1 2018 CO 3 1 24000 0 1 60
The ptc.py script output for this sample file and the two policy files described above are as follows:
OSPC-ACA-<version>$ python ptc.py sample_18_example
aca_current_law.json
1 4397.92 194 6.02 1444.80 1 5842.72
OSPC-ACA-<version>$ python ptc.py sample_18_example
aca_higher_prem.json
1 4598.54 194 6.02 1444.80 1 6043.34
The output shows that this individual has income equal to 194 percent of the federal poverty level, which implies that under current-law ACA policy this individual is expected to pay slightly more than six percent of income on health insurance, which comes to almost 1445 dollars. These results are the same in the two runs because the assumed poverty-level inflation rate is the same in the two runs. The difference between the two runs is in the projected 2018 value of the second-lowest-cost Silver plan premium, which is almost 201 dollars more in the alternative simulation than in the baseline simulation. The ACA premium tax credit is correspondingly almost 201 dollars more in the alternative simulation than in the baseline simulation (assuming that this individual buys a health insurance plan whose premium is at least as large as the premium tax credit).
Structural Reforms
If the current version of the ptc.py script does not read a parameter that represents an aspect of policy that you want to change, you are considering a reform that requires structural changes in the modules used by the ptc.py script. You can make these changes because all the all the ptc.py-related source code has been made publicly available. The basic steps involve creating a parameter in the source code that represents the aspect of policy you want to change, and then adding that policy parameter to the policy input file so that the ptc.py script can read its annual values. Probably the easiest way to begin doing this is to read the source code to see how an existing policy parameter is represented in the policy input file, how it is read by the source code, and how that parameter affects the premium tax credit calculation.
While it is possible to undertake structural changes to the ptc.py-related source code using the files you downloaded following the directions here, it is far better to clone the whole version-control repository and use this local copy of the OSPC-ACA source-code repository to make your structural changes. This is a better approach for at least two reasons. First, making your structural changes will typically involve several steps and, if you are human, missteps. Committing each small change to the local version-control repository will allow you to document each step and to revert to a prior version after a misstep. This is reason enough to learn how to use a version-control repository. But there is an important second reason for using the version-control repository to manage your changes to the source code. When you have finished making and testing the structural changes, you will have the option to contribute your changes, in the spirit of the open-source community, to the OSPC-ACA project. To learn how to clone the version-control repository, to begin making structural changes in the OSPC-ACA PTC calculator, and to contribute your changes to the broader community, finish reading the User Documents (see below) and then read the Contributor Documents listed on the Documentation page.
Next Step in Reading User Documents
The historical state data that is automatically read by the ptc.py script is described here.