Parameters ============================================== Our do-file and SConstruct file have repeated contents. Instead of having `count_isles.do`, `count_abyss.do`, `count_last.do`, we will call `countWords.do` with arguments. *1.* Instead of calling do-file `count_last.do`, we call `countWords.do` to create a frequency count dataset `isle.dta` from the input text `last.txt`. Here is an example of calling countWords with argument to create `*.dta` in Stata: ~~~~ . type code/countWords.do args inputFileName preserve wordfreq using inputs/txt/`inputFileName'.txt, clear egen totalsum = total(freq) gen share = freq / totalsum drop totalsum gsort - freq save outputs/data/dta/`inputFileName'.dta, replace restore ~~~~ `countWords.do` requires one argument (args): `inputfileName`. In our example, inputfileName is `isles`. `countWords.do` automatically loads `isles.txt` and creates outputfile named `isles.dta`. We call `countWords.do` with an argument in Stata. ~~~~ . do code/countWords.do "isles" . args inputFileName . . preserve . . wordfreq using inputs/txt/`inputFileName'.txt, clear . egen totalsum = total(freq) . gen share = freq / totalsum . drop totalsum . gsort - freq . save outputs/data/dta/`inputFileName'.dta, replace file outputs/data/dta/isles.dta saved . . restore . end of do-file ~~~~ Check the top 5 lines in the output file `isles.dta`: ~~~~ . use outputs/data/dta/isles.dta, clear . li in 1/5 +------------------------+ | word freq share | |------------------------| 1. | the 3315 .0625483 | 2. | of 2185 .0412272 | 3. | and 1530 .0288685 | 4. | to 1323 .0249627 | 5. | a 1132 .0213589 | +------------------------+ . clear ~~~~ And, do not re-create `testZipf.txt` directly in Stata. (We will update the `SConstruct-parameters` and re-create it using `statacons` in the next step.) *2.* Create a copy of `SConstruct-2NewRules` and rename it `SConstruct-parameters-isles`. *3.* Add parameters in SConstruct file. Now, we learn how to include `parameters` in our `SConstruct` file. In your text editor, open the file called `Sconstruct-parameters-isles` you created in step *2*. In `cmd_isles_data`, edit the source to `code/countWords.do` and add `params='"isles"'`. This will lead `statacons` to run the do-file `code/countWords.do` with an argument `"isles"`. ``` cmd_isles_data = env.StataBuild( target = 'outputs/data/dta/isles.dta', source = 'code/countWords.do', params='"isles"') Depends=(cmd_isles_data, ['inputs/txt/isles.txt'] ) ``` Next, to update `testZipf.txt`, include following command in `SConstruct-parameters-isles`. ~~~ cmd_results = env.StataBuild( target = 'outputs/tables/testZipf.txt', source = 'code/testZipf.do' ) Depends(cmd_results, ['outputs/data/dta/last.dta', 'outputs/data/dta/abyss.dta', 'outputs/data/dta/isles.dta'] ) ~~~ *4.* Use `SConstruct-parameters-isles` to see if any of the targets need to be rebuilt. Use option `file(SConstruct-parameters-isles)` to assign the specific `SConstruct` file, and use `dry_run` to get a preview of what `statacons` will do. ~~~~ . statacons, dry_run debug(explain) file(SConstruct-parameters-isles) scons: Reading SConscript files ... Using 'LabelsFormatsOnly' custom_datasignature. Calculates timestamp-independent checksum of dataset, including variable formats, variable labels and value labels. Edit use_custom_datasignature in config_project.ini to change. (other options are Strict, DataOnly, False) scons: done reading SConscript files. scons: Building targets ... scons: rebuilding `outputs\data\dta\abyss.dta' because: `code\countWords.do' is no longer a dependency `code\count_abyss.do' is a new dependency `code\ado\personal\countWords.ado' is a new dependency `code\ado\plus\w\wordfreq.ado' is a new dependency stata_run(["outputs\data\dta\abyss.dta"], ["code\count_abyss.do"]) scons: rebuilding `outputs\data\dta\last.dta' because: `code\countWords.do' is no longer a dependency `code\count_last.do' is a new dependency `code\ado\personal\countWords.ado' is a new dependency `code\ado\plus\w\wordfreq.ado' is a new dependency stata_run(["outputs\data\dta\last.dta"], ["code\count_last.do"]) scons: rebuilding `outputs\tables\testZipf.txt' because: `code\testZipfArgs.do' is no longer a dependency `code\testZipf.do' is a new dependency stata_run(["outputs\tables\testZipf.txt"], ["code\testZipf.do"]) scons: done building targets. ~~~~ Run `statacons`. `statacons` will rebuild `isles.dta` and `textZipf.txt` only. ~~~~ . statacons, file(SConstruct-parameters-isles) scons: Reading SConscript files ... Using 'LabelsFormatsOnly' custom_datasignature. Calculates timestamp-independent checksum of dataset, including variable formats, variable labels and value labels. Edit use_custom_datasignature in config_project.ini to change. (other options are Strict, DataOnly, False) scons: done reading SConscript files. scons: Building targets ... stata_run(["outputs\data\dta\abyss.dta"], ["code\count_abyss.do"]) Running: "C:\Program Files\Stata16\StataMP-64.exe" /e do "code\count_abyss.do". Starting in hidden desktop (pid=35876). stata_run(["outputs\data\dta\last.dta"], ["code\count_last.do"]) Running: "C:\Program Files\Stata16\StataMP-64.exe" /e do "code\count_last.do". Starting in hidden desktop (pid=1248). stata_run(["outputs\tables\testZipf.txt"], ["code\testZipf.do"]) Running: "C:\Program Files\Stata16\StataMP-64.exe" /e do "code\testZipf.do". Starting in hidden desktop (pid=30452). scons: done building targets. ~~~~ Check if `statacons` re-creates `textZipf.txt`. ~~~ . type outputs/tables/testZipf.txt Book First Second Ratio ~~~ ## Parameters: Exercise 1. Create a copy of `SConstruct-parameters-isles` and rename it `SConstruct-parameters-all`. 2. Add `cmd_last_data` and `cmd_abyss_data` in `SConstruct-parameters-all` using `countWords.do` as a source with parameters. 3. Replace `textZipf.do` to `textZipfArg.do` that takes the input file names as arguments. 4. Add a rule in our new SConstruct to build new `textZpif.txt`. 5. Use `SConstruct-parameters-all` to see if any of the targets need to be rebuilt. Hint: See `abyss` and `Two New Rules` solutions. See how `contWords.do` takes arguments in Stata. Apply `param` in `SConstruct` file. ## Parameters: Using statacons with dyndoc in literate programming As a final example of the use of parameters, this web tutorial consists of several web pages, each created from a Markdown `.md` file. Each of these `.md` files was created from a Stata `dyndoc` file. For example, this web page is produced from a Markdown file `parameters.md`, which in turn was created by `parameters.dyndoc`. We used `statacons` to manage this process. See *statacons and Literate Programming* on our project Wiki page for the code.