|
| 1 | +# pytask-stata |
| 2 | + |
| 3 | +[](https://pypi.org/project/pytask-stata) |
| 4 | +[](https://pypi.org/project/pytask-stata) |
| 5 | +[](https://anaconda.org/conda-forge/pytask-stata) |
| 6 | +[](https://anaconda.org/conda-forge/pytask-stata) |
| 7 | +[](https://pypi.org/project/pytask-stata) |
| 8 | +[](https://github.com/pytask-dev/pytask-stata/actions?query=branch%3Amain) |
| 9 | +[](https://codecov.io/gh/pytask-dev/pytask-stata) |
| 10 | +[](https://results.pre-commit.ci/latest/github/pytask-dev/pytask-stata/main) |
| 11 | +[](https://github.com/psf/black) |
| 12 | + |
| 13 | +------------------------------------------------------------------------ |
| 14 | + |
| 15 | +Run Stata\'s do-files with pytask. |
| 16 | + |
| 17 | +## Installation |
| 18 | + |
| 19 | +pytask-stata is available on |
| 20 | +[PyPI](https://pypi.org/project/pytask-stata) and |
| 21 | +[Anaconda.org](https://anaconda.org/conda-forge/pytask-stata). Install |
| 22 | +it with |
| 23 | + |
| 24 | +``` console |
| 25 | +$ pip install pytask-stata |
| 26 | + |
| 27 | +# or |
| 28 | + |
| 29 | +$ conda install -c conda-forge pytask-stata |
| 30 | +``` |
| 31 | + |
| 32 | +You also need to have Stata installed on your system and have the |
| 33 | +executable on your system\'s PATH. If you do not know how to do it, |
| 34 | +[here](https://superuser.com/a/284351) is an explanation. |
| 35 | + |
| 36 | +## Usage |
| 37 | + |
| 38 | +Similarly to normal task functions which execute Python code, you define |
| 39 | +tasks to execute scripts written in Stata with Python functions. The |
| 40 | +difference is that the function body does not contain any logic, but the |
| 41 | +decorator tells pytask how to handle the task. |
| 42 | + |
| 43 | +Here is an example where you want to run `script.do`. |
| 44 | + |
| 45 | +``` python |
| 46 | +import pytask |
| 47 | + |
| 48 | + |
| 49 | +@pytask.mark.stata(script="script.do") |
| 50 | +@pytask.mark.produces("auto.dta") |
| 51 | +def task_run_do_file(): |
| 52 | + pass |
| 53 | +``` |
| 54 | + |
| 55 | +When executing a do-file, the current working directory changes to the |
| 56 | +directory where the script is located. This allows you, for example, to |
| 57 | +reference every data set you want to read with a relative path from the |
| 58 | +script. |
| 59 | + |
| 60 | +### Dependencies and Products |
| 61 | + |
| 62 | +Dependencies and products can be added as with a normal pytask task |
| 63 | +using the `@pytask.mark.depends_on` and `@pytask.mark.produces` |
| 64 | +decorators. which is explained in this |
| 65 | +[tutorial](https://pytask-dev.readthedocs.io/en/stable/tutorials/defining_dependencies_products.html). |
| 66 | + |
| 67 | +### Accessing dependencies and products in the script |
| 68 | + |
| 69 | +The decorator can be used to pass command line arguments to your Stata |
| 70 | +executable. For example, pass the path of the product with |
| 71 | + |
| 72 | +``` python |
| 73 | +@pytask.mark.stata(script="script.do", options="auto.dta") |
| 74 | +@pytask.mark.produces("auto.dta") |
| 75 | +def task_run_do_file(): |
| 76 | + pass |
| 77 | +``` |
| 78 | + |
| 79 | +And in your `script.do`, you can intercept the value with |
| 80 | + |
| 81 | +``` do |
| 82 | +* Intercept command line argument and save to macro named 'produces'. |
| 83 | +args produces |
| 84 | +
|
| 85 | +sysuse auto, clear |
| 86 | +save "`produces'" |
| 87 | +``` |
| 88 | + |
| 89 | +The relative path inside the do-file works only because the pytask-stata |
| 90 | +switches the current working directory to the directory of the do-file |
| 91 | +before the task is executed. |
| 92 | + |
| 93 | +To make the task independent from the current working directory, pass |
| 94 | +the full path as an command line argument. Here is an example. |
| 95 | + |
| 96 | +``` python |
| 97 | +# Absolute path to the build directory. |
| 98 | +from src.config import BLD |
| 99 | + |
| 100 | + |
| 101 | +@pytask.mark.stata(script="script.do", options=BLD / "auto.dta") |
| 102 | +@pytask.mark.produces(BLD / "auto.dta") |
| 103 | +def task_run_do_file(): |
| 104 | + pass |
| 105 | +``` |
| 106 | + |
| 107 | +### Repeating tasks with different scripts or inputs |
| 108 | + |
| 109 | +You can also parametrize the execution of scripts, meaning executing |
| 110 | +multiple do-files as well as passing different command line arguments to |
| 111 | +the same do-file. |
| 112 | + |
| 113 | +The following task executes two do-files which produce different |
| 114 | +outputs. |
| 115 | + |
| 116 | +``` python |
| 117 | +for i in range(2): |
| 118 | + |
| 119 | + @pytask.mark.task |
| 120 | + @pytask.mark.stata(script=f"script_{i}.do", options=f"{i}.dta") |
| 121 | + @pytask.mark.produces(f"{i}.dta") |
| 122 | + def task_execute_do_file(): |
| 123 | + pass |
| 124 | +``` |
| 125 | + |
| 126 | +## Configuration |
| 127 | + |
| 128 | +pytask-stata can be configured with the following options. |
| 129 | + |
| 130 | +*`stata_keep_log`* |
| 131 | + |
| 132 | +Use this option to keep the `.log` files which are produced for |
| 133 | +every task. This option is useful to debug Stata tasks. Set the |
| 134 | +option via the configuration file with |
| 135 | + |
| 136 | +```toml |
| 137 | +[tool.pytask.ini_options] |
| 138 | +stata_keep_log = true |
| 139 | +``` |
| 140 | + |
| 141 | +The option is also available in the command line interface via the |
| 142 | +`--stata-keep-log` flag. |
| 143 | + |
| 144 | + |
| 145 | +*`stata_check_log_lines`* |
| 146 | + |
| 147 | +Use this option to vary the number of lines in the log file which |
| 148 | +are checked for error codes. It also controls the number of lines |
| 149 | +displayed on errors. Use any integer greater than zero. Here is the |
| 150 | +entry in the configuration file |
| 151 | + |
| 152 | +```toml |
| 153 | +[tool.pytask.ini_options] |
| 154 | +stata_check_log_lines = 10 |
| 155 | +``` |
| 156 | + |
| 157 | +and here via the command line interface |
| 158 | + |
| 159 | +``` console |
| 160 | +$ pytask build --stata-check-log-lines 10 |
| 161 | +``` |
| 162 | + |
| 163 | +## Changes |
| 164 | + |
| 165 | +Consult the [release notes](CHANGES.md) to find out about what is new. |
0 commit comments