*! version 1.2.6 07oct2022

Title

pyconvertu -- Convert a string variable to a classification from
a built-in or user-defined JSON file using Python 3 (regular expressions) with
Unicode support, the default being ISO 3166-1 (country codes and names)

Syntax

pyconvertu
varname or string
[, options]

Classification
from(strings:string) is a relative or absolute path
to the JSON file (omittable)

to(strings:string) is a classification from the JSON file,
by default, "iso3", "iso2", "isoN", "name_en",
or "name_fr", or a filepath (see the usage of argument
__dump)

Write to data
* generate(strings:string) specify a new
varname for the a) result of conversion or
b) classification

* replace replace provided varname with
the a) result of conversion or b) classification

* print print the result, do not generate or replace
variables

* One of generate(strings:string), replace or print
is required if varname or "__classification" are specified.

Description

pyconvertu converts a string variable to a classification from a built-in
or user-defined JSON file using Python 3 (regular expressions) with Unicode
support.

By default, country names (in English) or codes are converted to
ISO 3166-1 codes (alpha-2, alpha-3, and numeric) and to full names (in English
and in French).

. pyconvertu varname, to(string)

performs the conversion of varname to the specified
classification and is followed by
generate(string),
replace or
print.

. pyconvertu __classification, to(string)

returns the specified classification as a whole and is followed by
generate(string) or
print.

. pyconvertu __info

prints metadata and sources, no options are required.

. pyconvertu __dump, to(string)

creates a JSON file at filepath provided in
to from data in memory.

Options

from(strings:string) allows the user to work with a user-defined JSON
file to replace the default classification (ISO 3166-1). The file must contain
a list of dictionaries (the terms 'list', 'dictionary' and 'key' are from
Python's vocabulary) where "regex" is a compulsory key in each dictionary. The
default JSON file was prepared with the help of
pyconvertu __dump, to(string).

For it, data in memory must include headings "Data", "Metadata" and
"Sources" in the first variable, immediately followed by content. Alternatively,
the user can recur to Python's built-in json package:
>>> import json; ...; json.dump(...)), consult
https://docs.python.org/3/library/json.html for documentation.

The JSON file should have the following structure:

[

{
"regex": "^(.*afgh.*|\\s*AFG\\s*|\\s*AF\\s*|\\s*4\\s*)$",
"name_en": "Afghanistan", # classification A
"name_fr": "Afghanistan (l')", # classification B
"iso3": "AFG", # ...
"iso2": "AF",
"isoN": "4"
},

...

{
"metadata": {
"name_en": "English short name",
"name_fr": "French short name",
"iso3": "alpha-3 code",
"iso2": "alpha-2 code",
"isoN": "numeric"
}
},

{
"sources": [
"[https://www.iso.org/iso-3166-country-codes.html](ISO 3166 COUNTRY CODES)",
"[https://en.wikipedia.org/wiki/List_of_alternative_country_names](ALTERNATIVE NAMES)"
]
}

]

to(strings:string) is a key from the JSON file which corresponds to
one of the classifications, by default, "iso3" is ISO 3166-1 alpha-3,
"iso2" is ISO 3166-1 alpha-2, "isoN" is ISO 3166-1 numeric,
"name_en" are names in English, and "name_fr" are names in French.

In . pyconvertu __dump, to(string) it is
a relative or absolute path to the JSON file being created.

generate(strings:string) is required to write the a) result of
conversion or b) classification to data in form of a new variable.

replace is required to replace the contents of
varname in
. pyconvertu varname, to(string)
with the a) result of conversion or b) classification.

print negates generate(string) or
replace (if specified) and prints the
a) result of conversion or b) classification instead of writing them to
data. The user can utilize print to check
the result before modifying the data.

Remarks

pyconvertu requires an executable of a Python installation
(Python 3 or higher) set with the help of python set exec command!

No additional Python packages from PyPi are needed.

Still, for Python-savy users there is a pure Python version
https://pypi.org/project/pyconvertu/ with the same functionality.

For detailed information on python set exec, consult python.

Examples

* write the complete default JSON file (ISO 3166-1) to data
. clear
. pyconvertu __classification, to(iso3) gen(iso3)
. foreach s in "iso2" "isoN" "name_en" "name_fr" {
. pyconvertu iso3, to(`s') gen(`s')
. }

* print metadata and sources for the default JSON file
. pyconvertu __info

* generate panel dimensions
* (ISO 3166-1 alpha-3 codes for the years 2000-2020)
. clear
. pyconvertu __classification, to(iso3) gen(iso3)
. expand `=(2020 - 2000) + 1'
. by iso3, sort: gen year = 2000 + (_n - 1)

* convert ISO 3166-1 alpha-3 to ISO 3166-1 numeric (where possible)
* in a dataset
. ssc install wbopendata
. sysuse world-d, clear
. pyconvertu countrycode, to(isoN) replace

* same example, print the result of conversion instead of writing it
* to data
. sysuse world-d, clear
. pyconvertu countrycode, to(isoN) print

Author

Ilya Bolotov

Prague University of Economics and Business

Prague, Czech Republic

ilya.bolotov@vse.cz

Thanks for citing this software and my works on the topic:

Bolotov, I. (2021). PYCONVERTU: Stata module to convert a string variable
into a classification from the default or user-provided JSON file with
the help of Python 3. Available from
https://ideas.repec.org/c/boc/bocode/s458892.html.