# rbStata
`rbStata` is a CLI utility to easily convert between (or, roll back) versions of Stata's `.dta`, which are not forward compatible.
* Cross-platform CLI utility: Windows, Mac, Linux.
* No knowledge of Python required (but requires a Python installation).
* Handles Unicode to ASCII transliteration (older versions of Stata do not support Unicode).
* Works with Python 3.6+.
* Handles transferring (where available and possible) of:
- Variable labels
- Data labels
- Value labels
| | |
| --- | --- |
| Package | [](https://pypi.org/project/rbStata/) [](https://pypi.org/project/rbStata/) [](https://github.com/LSYS/rbStata/releases) |
| Testing/build | [](https://codecov.io/gh/lsys/rbStata) [](https://github.com/LSYS/rbStata/actions/workflows/build.yml) [](https://github.com/LSYS/rbStata/actions/workflows/cli-pkg.yml) [](https://github.com/LSYS/rbStata/actions/workflows/Pkg-CLI.yml) [](https://github.com/LSYS/rbStata/actions/workflows/doclinks.yml) |
| Meta | [](https://zenodo.org/doi/10.5281/zenodo.10925080) [](https://choosealicense.com/licenses/mit/) |
## Statement of Need
Stata `.dta` data files are not forward compatible.
This means you cannot use older versions (e.g., `Stata 13`) to read a `.dta` file exported from newer versions (e.g., `Stata 17`).
So what is one to do when you try to open a `dta` file in Stata and get a rude `dta too modern r(601)` error:
<details open><summary><em>...</em></summary>
<p align="center"><img width="100%" src="https://raw.githubusercontent.com/LSYS/rbStata/main/assets/gfy-error.png"></p>
</details>
Roll back to older versions of Stata `.dta` files with `rbStata`.
`rbStata` is a quick and dead simple CLI (command-line interface) to go way back with Stata data (`.dta`) files. You *do not need access to* newer `Stata` versions.
## Quick usage
* **Simple single-line command-line usage:**
* Convert the `auto.dta` file so that you can open it in Stata 13
<pre>$ rbstata auto.dta --target-version 13 --verbose</pre>
* Convert all `dta` files in the path so that you can open it in Stata 13
<pre>$ rbstata --all --target-version 13 --verbose</pre>
* **Let `rbStata` prompt you for relevant settings:** <br>
Type `rbstata` and enter settings (press enter to accept default settings in brackets):
<pre>$ rbstata</pre>
```console
-------------------------------------------------------------
Welcome to the rbStata quickstart command-line utility.
You will be prompted for relevant settings.
Please enter values under the following settings.
(just press Enter to accept the default value in brackets)
-------------------------------------------------------------
Enter the dta file(s) you want to convert (e.g. ''auto.dta'').
(It is not necessary to key in the .dta extension (e.g., just type ''auto'').
Press Enter to include all .dta files in the current directory.)
> .dta file(s) [*]:
...
The Stata version to convert to.
> Target version [13]:
...
File suffix for saving the output file(s).
(For example, the suffix ''-old'' means that auto.dta will be converted and
saved as auto-old.dta. Default is to use ''-rbstata''.)
> File suffix for saving [-rbstata]:
...
Include all .dta files in current directory and its subdirectories.
(Default is to include only the .dta files in the current directory.)
> Include subdirectories (y/n) [n]:
...
> Print all messages (y/n) [y]:
...
```
<details><summary><em>Settings [defaults]</em></summary>
* `.dta file(s)` [*]: .dta files to convert [all .dta files in current directory]
* `Target version [13]`: version to convert to [Stata v13]
* `File suffix for saving [-rbstata]`: Suffix for saving [E.g. save auto.dta to auto-rbstata.dta]
* `Include subdirectories (y/n) [n]`: Include subdirectories if * [no]
* `Print all messages (y/n) [y]`: Print all messages and errors [yes]
</details>
## More about the problem
<details open><summary><em>Assortment of enquires about the error</em></summary>
* [[1]](https://www.stata.com/support/faqs/data-management/save-for-previous-version/) Stata support FAQs: How can I save a Stata dataset so that it can be read by a previous version of Stata?
* [[2]](https://www.statalist.org/forums/forum/general-stata-discussion/general/1440296-how-to-read-a-stata-15-data-file-in-stata-13) how to read a stata 15 data file in stata 13.
* [[3]](https://www.statalist.org/forums/forum/general-stata-discussion/general/1326849-how-to-open-stata-14-files-in-stata-12-13) How to open stata 14 files in Stata 12-13.
* [[4]](https://www.statalist.org/forums/forum/general-stata-discussion/general/1373797-how-to-open-a-new-stata-dataset-version) How to open a new stata dataset version.
* [[5]](https://www.statalist.org/forums/forum/general-stata-discussion/general/1363089-how-to-open-a-file-that-is-more-from-a-more-recent-version-of-stata-into-stata13) How to open a file that is more from a more recent version of Stata into Stata13.
<!-- Deadlink -->
<!-- * [[6]](https://www.reddit.com/r/stata/comments/4ufos2/convert_stata_14_dta_file_t) Convert Stata 14 .dta file to Stata 13. -->
</details>
## Versions and string handling
One major jump in forward compatibility is from Stata 13 to Stata 14, where Stata 14 started adding Unicode compatibility. `rbStata` handles transferring of the data, value, and variable labels. If Unicode in labels exist and the backward target version is 13, `rbStata` will transliterate Unicode to ASCII *and* truncate labels to 80 characters.
<details open><summary><em>Assortment of enquires about the error</em></summary>
* [[1]](https://www.stata.com/support/faqs/data-management/save-for-previous-version/) Stata support FAQs: How can I save a Stata dataset so that it can be read by a previous version of Stata?
* [[2]](https://www.statalist.org/forums/forum/general-stata-discussion/general/1440296-how-to-read-a-stata-15-data-file-in-stata-13) how to read a stata 15 data file in stata 13.
* [[3]](https://www.statalist.org/forums/forum/general-stata-discussion/general/1326849-how-to-open-stata-14-files-in-stata-12-13) How to open stata 14 files in Stata 12-13.
* [[4]](https://www.statalist.org/forums/forum/general-stata-discussion/general/1373797-how-to-open-a-new-stata-dataset-version) How to open a new stata dataset version.
* [[5]](https://www.statalist.org/forums/forum/general-stata-discussion/general/1363089-how-to-open-a-file-that-is-more-from-a-more-recent-version-of-stata-into-stata13) How to open a file that is more from a more recent version of Stata into Stata13.
<!-- Deadlink -->
<!-- * [[6]](https://www.reddit.com/r/stata/comments/4ufos2/convert_stata_14_dta_file_t) Convert Stata 14 .dta file to Stata 13. -->
</details>
## Alternative solutions
Based on proposed solutions in [More about the problem](#more-about-the-problem).
* [[0]](https://www.stata.com/manuals/dsave.pdf) Use Stata's `saveold` (but for this you first need access to the new Stata version. Read in the `dta` file. Save it using `saveold`. Then use the converted `dta` file in your older Stata version).
* [[1]](https://stattransfer.com/) Stat/Transfer (proprietary).
* [[2]](https://cran.r-project.org/web/packages/haven/index.html) R's `Haven`.
## About this utility
`rbStata` is an open source utility that wraps around [`click`](https://click.palletsprojects.com/) and [`pandas`](https://github.com/pandas-dev/pandas)'s [`DataFrame.to_Stata`](https://pandas.pydata.org/docs/reference/api/pandas.DataFrame.to_stata.html) utility. Using `rbStata`, easily convert new Stata `dta` files to older versions.
<details><summary><em>Expose CLI help reference</em></summary>
```console
$ rbstata -h
Usage: rbstata [OPTIONS] <dta files>
Find your way back to older versions of dta files.
Convert newer Stata .dta files to older versions so that you can open them in older
Stata versions.
Options:
-a, --all Convert all dta files in path.
-v, --version <int> Which version of Stata to convert to.
-s, --suffix <text> Suffix to be added to converted file.
-o, --output <text> Name of converted .dta file (Single file conversion only).
Supercedes [suffix].
-r, --recursive Convert all .dta files in directory and subdirectories.
-w, --overwrite Over[w]rite original input .dta files.
-ve, --verbose Print messages.
-h, --help Show this message and exit.
```
</details>
Raw data
{
"_id": null,
"home_page": "https://github.com/lsys/rbStata",
"name": "rbstata",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "Stata, Python, cli, compatibility, version",
"author": "Lucas Shen",
"author_email": "lucas@lucasshen.com",
"download_url": "https://files.pythonhosted.org/packages/a5/da/3dfdf02a307721ee06cb9e8b4fcd48d09b84541c9ce372d2b420735010f8/rbstata-0.1.1.tar.gz",
"platform": null,
"description": "# rbStata\n\n`rbStata` is a CLI utility to easily convert between (or, roll back) versions of Stata's `.dta`, which are not forward compatible. \n* Cross-platform CLI utility: Windows, Mac, Linux.\n* No knowledge of Python required (but requires a Python installation).\n* Handles Unicode to ASCII transliteration (older versions of Stata do not support Unicode).\n* Works with Python 3.6+.\n* Handles transferring (where available and possible) of:\n - Variable labels\n - Data labels\n - Value labels\n\n| | |\n| --- | --- |\n| Package | [](https://pypi.org/project/rbStata/) [](https://pypi.org/project/rbStata/) [](https://github.com/LSYS/rbStata/releases) |\n| Testing/build | [](https://codecov.io/gh/lsys/rbStata) [](https://github.com/LSYS/rbStata/actions/workflows/build.yml) [](https://github.com/LSYS/rbStata/actions/workflows/cli-pkg.yml) [](https://github.com/LSYS/rbStata/actions/workflows/Pkg-CLI.yml) [](https://github.com/LSYS/rbStata/actions/workflows/doclinks.yml) |\n| Meta | [](https://zenodo.org/doi/10.5281/zenodo.10925080) [](https://choosealicense.com/licenses/mit/) |\n\n## Statement of Need\n\nStata `.dta` data files are not forward compatible. \nThis means you cannot use older versions (e.g., `Stata 13`) to read a `.dta` file exported from newer versions (e.g., `Stata 17`).\n\nSo what is one to do when you try to open a `dta` file in Stata and get a rude `dta too modern r(601)` error:\n<details open><summary><em>...</em></summary>\n <p align=\"center\"><img width=\"100%\" src=\"https://raw.githubusercontent.com/LSYS/rbStata/main/assets/gfy-error.png\"></p>\n</details>\n\nRoll back to older versions of Stata `.dta` files with `rbStata`.\n`rbStata` is a quick and dead simple CLI (command-line interface) to go way back with Stata data (`.dta`) files. You *do not need access to* newer `Stata` versions.\n\n\n## Quick usage\n\n* **Simple single-line command-line usage:**\n * Convert the `auto.dta` file so that you can open it in Stata 13\n <pre>$ rbstata auto.dta --target-version 13 --verbose</pre>\n \n * Convert all `dta` files in the path so that you can open it in Stata 13\n <pre>$ rbstata --all --target-version 13 --verbose</pre>\n \n\n* **Let `rbStata` prompt you for relevant settings:** <br>\n \n Type `rbstata` and enter settings (press enter to accept default settings in brackets):\n <pre>$ rbstata</pre>\n ```console\n -------------------------------------------------------------\n Welcome to the rbStata quickstart command-line utility.\n\n You will be prompted for relevant settings.\n\n Please enter values under the following settings.\n (just press Enter to accept the default value in brackets)\n -------------------------------------------------------------\n\n Enter the dta file(s) you want to convert (e.g. ''auto.dta'').\n (It is not necessary to key in the .dta extension (e.g., just type ''auto'').\n Press Enter to include all .dta files in the current directory.)\n > .dta file(s) [*]:\n ...\n\n The Stata version to convert to.\n > Target version [13]:\n ...\n \n File suffix for saving the output file(s).\n (For example, the suffix ''-old'' means that auto.dta will be converted and\n saved as auto-old.dta. Default is to use ''-rbstata''.)\n > File suffix for saving [-rbstata]:\n ...\n \n Include all .dta files in current directory and its subdirectories.\n (Default is to include only the .dta files in the current directory.)\n > Include subdirectories (y/n) [n]:\n ...\n \n > Print all messages (y/n) [y]:\n ...\n ```\n<details><summary><em>Settings [defaults]</em></summary>\n\n * `.dta file(s)` [*]: .dta files to convert [all .dta files in current directory]\n * `Target version [13]`: version to convert to [Stata v13] \n * `File suffix for saving [-rbstata]`: Suffix for saving [E.g. save auto.dta to auto-rbstata.dta]\n * `Include subdirectories (y/n) [n]`: Include subdirectories if * [no]\n * `Print all messages (y/n) [y]`: Print all messages and errors [yes]\n</details>\n\n## More about the problem\n<details open><summary><em>Assortment of enquires about the error</em></summary>\n \n * [[1]](https://www.stata.com/support/faqs/data-management/save-for-previous-version/) Stata support FAQs: How can I save a Stata dataset so that it can be read by a previous version of Stata?\n * [[2]](https://www.statalist.org/forums/forum/general-stata-discussion/general/1440296-how-to-read-a-stata-15-data-file-in-stata-13) how to read a stata 15 data file in stata 13.\n * [[3]](https://www.statalist.org/forums/forum/general-stata-discussion/general/1326849-how-to-open-stata-14-files-in-stata-12-13) How to open stata 14 files in Stata 12-13.\n * [[4]](https://www.statalist.org/forums/forum/general-stata-discussion/general/1373797-how-to-open-a-new-stata-dataset-version) How to open a new stata dataset version.\n * [[5]](https://www.statalist.org/forums/forum/general-stata-discussion/general/1363089-how-to-open-a-file-that-is-more-from-a-more-recent-version-of-stata-into-stata13) How to open a file that is more from a more recent version of Stata into Stata13.\n <!-- Deadlink -->\n <!-- * [[6]](https://www.reddit.com/r/stata/comments/4ufos2/convert_stata_14_dta_file_t) Convert Stata 14 .dta file to Stata 13. -->\n</details> \n\n## Versions and string handling\n\nOne major jump in forward compatibility is from Stata 13 to Stata 14, where Stata 14 started adding Unicode compatibility. `rbStata` handles transferring of the data, value, and variable labels. If Unicode in labels exist and the backward target version is 13, `rbStata` will transliterate Unicode to ASCII *and* truncate labels to 80 characters.\n\n<details open><summary><em>Assortment of enquires about the error</em></summary>\n \n * [[1]](https://www.stata.com/support/faqs/data-management/save-for-previous-version/) Stata support FAQs: How can I save a Stata dataset so that it can be read by a previous version of Stata?\n * [[2]](https://www.statalist.org/forums/forum/general-stata-discussion/general/1440296-how-to-read-a-stata-15-data-file-in-stata-13) how to read a stata 15 data file in stata 13.\n * [[3]](https://www.statalist.org/forums/forum/general-stata-discussion/general/1326849-how-to-open-stata-14-files-in-stata-12-13) How to open stata 14 files in Stata 12-13.\n * [[4]](https://www.statalist.org/forums/forum/general-stata-discussion/general/1373797-how-to-open-a-new-stata-dataset-version) How to open a new stata dataset version.\n * [[5]](https://www.statalist.org/forums/forum/general-stata-discussion/general/1363089-how-to-open-a-file-that-is-more-from-a-more-recent-version-of-stata-into-stata13) How to open a file that is more from a more recent version of Stata into Stata13.\n <!-- Deadlink -->\n <!-- * [[6]](https://www.reddit.com/r/stata/comments/4ufos2/convert_stata_14_dta_file_t) Convert Stata 14 .dta file to Stata 13. -->\n</details> \n\n## Alternative solutions\nBased on proposed solutions in [More about the problem](#more-about-the-problem).\n* [[0]](https://www.stata.com/manuals/dsave.pdf) Use Stata's `saveold` (but for this you first need access to the new Stata version. Read in the `dta` file. Save it using `saveold`. Then use the converted `dta` file in your older Stata version).\n* [[1]](https://stattransfer.com/) Stat/Transfer (proprietary).\n* [[2]](https://cran.r-project.org/web/packages/haven/index.html) R's `Haven`.\n\n## About this utility\n`rbStata` is an open source utility that wraps around [`click`](https://click.palletsprojects.com/) and [`pandas`](https://github.com/pandas-dev/pandas)'s [`DataFrame.to_Stata`](https://pandas.pydata.org/docs/reference/api/pandas.DataFrame.to_stata.html) utility. Using `rbStata`, easily convert new Stata `dta` files to older versions.\n\n<details><summary><em>Expose CLI help reference</em></summary>\n \n ```console\n $ rbstata -h\n Usage: rbstata [OPTIONS] <dta files>\n\n Find your way back to older versions of dta files.\n\n Convert newer Stata .dta files to older versions so that you can open them in older\n Stata versions.\n\n Options:\n -a, --all Convert all dta files in path.\n -v, --version <int> Which version of Stata to convert to.\n -s, --suffix <text> Suffix to be added to converted file.\n -o, --output <text> Name of converted .dta file (Single file conversion only).\n Supercedes [suffix].\n -r, --recursive Convert all .dta files in directory and subdirectories.\n -w, --overwrite Over[w]rite original input .dta files.\n -ve, --verbose Print messages.\n -h, --help Show this message and exit.\n ```\n</details>\n \n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A command-line utility that converts (or roll back) versions of Stata dta data files.",
"version": "0.1.1",
"project_urls": {
"Homepage": "https://github.com/lsys/rbStata"
},
"split_keywords": [
"stata",
" python",
" cli",
" compatibility",
" version"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "a5da3dfdf02a307721ee06cb9e8b4fcd48d09b84541c9ce372d2b420735010f8",
"md5": "758ee64173c82b14ad4817d5690446be",
"sha256": "d627217a2a759ed19baedce07250345d5aad6e1a6014b2c82638218f26d533fc"
},
"downloads": -1,
"filename": "rbstata-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "758ee64173c82b14ad4817d5690446be",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 13723,
"upload_time": "2024-04-04T07:38:31",
"upload_time_iso_8601": "2024-04-04T07:38:31.656898Z",
"url": "https://files.pythonhosted.org/packages/a5/da/3dfdf02a307721ee06cb9e8b4fcd48d09b84541c9ce372d2b420735010f8/rbstata-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-04 07:38:31",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "lsys",
"github_project": "rbStata",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "rbstata"
}
JSON
