国家转换器 (coco) - 一个 Python 包，用于在不同分类方案之间转换国家名称。
项目描述
国家转换器
国家转换器（coco）是一个Python包，用于在不同分类之间和不同命名版本之间转换和匹配国家名称。在内部，它使用正则表达式来匹配国家名称。Coco 还可以用于构建不同分类方案之间的聚合一致性矩阵。
动机
迄今为止，对于如何在（元）数据描述中命名或指定各个国家/地区，还没有统一的标准。虽然一些数据源遵循 ISO 3166，但该标准除了数字分类外还定义了两个和三个字母代码。使问题进一步复杂化的是，许多数据库没有使用现有标准之一，而是使用非标准化的国家名称对国家进行分类。
国家转换器 (coco) 自动转换不同标准和版本的国家名称。在内部，coco 基于一个表格，其中指定了每个国家的不同 ISO 和 UN 标准以及官方名称和正则表达式，旨在匹配特定国家名称的所有英文版本。此外，coco 还包括基于联合国、欧盟、经合组织成员资格、联合国区域规范、大陆和各种 MRIO 和 IAM 数据库的分类（参见 下面的分类方案）。
安装
Country_converter 在 PyPI 注册。从命令行：
pip install country_converter --upgrade
国家/地区转换器也可以从conda forge 获得，并且可以使用 conda 安装（如果您没有将 conda_forge 频道添加到您的 conda 配置添加“-c conda-forge”，请参阅此处的安装说明）：
conda install country_converter
或者，源代码可在 GitHub 上获得。
该软件包取决于Pandas；测试 pytest是必需的。有关运行测试的更多信息，请参阅CONTRIBUTING.md。
用法
基本用法
在 Python 中使用
将各种国家名称转换为一些标准名称：
import country_converter as coco
some_names = ['United Rep. of Tanzania', 'DE', 'Cape Verde', '788', 'Burma', 'COG',
'Iran (Islamic Republic of)', 'Korea, Republic of',
"Dem. People's Rep. of Korea"]
standard_names = coco.convert(names=some_names, to='name_short')
print(standard_names)
结果是['坦桑尼亚'，'德国'，'佛得角'，'突尼斯'，'缅甸'，'刚果共和国'，'伊朗'，'韩国'，'朝鲜']。输入格式是根据 ISO 两个字母、ISO 三个字母、ISO 数字或正则表达式匹配自动确定的。如果有任何歧义，可以使用参数“src”指定源格式。
在多次转换的情况下，通过为所有转换实例化单个 CountryConverter 对象可以获得更好的性能：
import country_converter as coco
cc = coco.CountryConverter()
some_names = ['United Rep. of Tanzania', 'Cape Verde', 'Burma',
'Iran (Islamic Republic of)', 'Korea, Republic of',
"Dem. People's Rep. of Korea"]
standard_names = cc.convert(names = some_names, to = 'name_short')
UNmembership = cc.convert(names = some_names, to = 'UNmember')
print(standard_names)
print(UNmembership)
在分类方案之间转换：
iso3_codes = ['USA', 'VUT', 'TKL', 'AUT', 'XXX' ]
iso2_codes = coco.convert(names=iso3_codes, to='ISO2')
print(iso2_codes)
这导致 ['US', 'VU', 'TK', 'AT', 'not found']
可以指定未找到指示（例如 not_found = 'not there'），如果为 'not_found' 传递 None，则通过原始条目：
iso2_codes = coco.convert(names=iso3_codes, to='ISO2', not_found=None)
print(iso2_codes)
结果 ['US', 'VU', 'TK', 'AT', 'XXX']
在内部，数据存储在 Pandas DataFrame 中，可以直接访问。例如，这可用于过滤会员组织的国家（每年）。注意：为此，需要 CountryConverter 的实例。
import country_converter as coco
cc = coco.CountryConverter()
some_countries = ['Australia', 'Belgium', 'Brazil', 'Bulgaria', 'Cyprus', 'Czech Republic',
'Denmark', 'Estonia', 'Finland', 'France', 'Germany', 'Greece', 'Hungary',
'India', 'Indonesia', 'Ireland', 'Italy', 'Japan', 'Latvia', 'Lithuania',
'Luxembourg', 'Malta', 'Romania', 'Russia', 'Turkey', 'United Kingdom',
'United States']
oecd_since_1995 = cc.data[(cc.data.OECD >= 1995) & cc.data.name_short.isin(some_countries)].name_short
eu_until_1980 = cc.data[(cc.data.EU <= 1980) & cc.data.name_short.isin(some_countries)].name_short
print(oecd_since_1995)
print(eu_until_1980)
所有分类都可以通过以下方式直接访问：
cc.EU28
cc.OECD
cc.EU27as('ISO3')
和可用的分类方案：
cc.valid_class
还有一种仅获取国家分类的方法（因此省略了任何国家分组）：
cc.valid_country_classifications
如果您更需要一本描述分类/成员资格的字典，请使用：
import country_converter as coco
cc = coco.CountryConverter()
cc.get_correspondence_dict('EXIO3', 'ISO3')
还包括未指定为特定分类用途的国家：
cc.get_correspondence_dict('EU27', 'ISO2', replace_nan='NonEU')
正则表达式还可用于将任何国家/地区列表与任何其他国家/地区匹配。例如：
match_these = ['norway', 'united_states', 'china', 'taiwan']
master_list = ['USA', 'The Swedish Kingdom', 'Norway is a Kingdom too',
'Peoples Republic of China', 'Republic of China' ]
matching_dict = coco.match(match_these, master_list)
如果未找到匹配项，默认情况下，国家/地区转换器会向 python日志记录器提供警告。以下示例演示了如何配置coco日志记录行为。
import logging
import country_converter as coco
logging.basicConfig(level=logging.INFO)
coco.convert("asdf")
# WARNING:country_converter.country_converter:asdf not found in regex
# Out: 'not found'
coco_logger = coco.logging.getLogger()
coco_logger.setLevel(logging.CRITICAL)
coco.convert("asdf")
# Out: 'not found'
有关更多信息，请参阅 IPython Notebook ( country_converter_examples.ipynb )。
命令行使用
country 转换器包还提供了一个名为 coco 的命令行界面。
最小的例子：
coco Cyprus DE Denmark Estonia 4 'United Kingdom' AUT
根据输入与 ISO2、ISO3、ISOnumeric 或正则表达式匹配的匹配，将给定名称转换为 ISO3 代码。名称列表必须用空格分隔，由多个单词组成的国家名称必须放在引号（''）中。
输入分类可以用“--src”或“-s”指定（或将自动确定），目标分类用“--to”或“-t”指定。
默认输出是一个空格分隔的列表，这可以通过'--output_sep' 或'-o' （例如-o '|'）传递分隔符来更改。
因此，要将 ISO3 转换为联合国编号代码并以逗号分隔列表的形式接收输出，请使用：
coco AUT DEU VAT AUS -s ISO3 -t UNcode -o ', '
命令行工具还允许为未找到的条目指定输出，包括通过传递 None 将它们传递到输出：
coco CAN Peru US Mexico Venezuela UK Arendelle --not_found=None
并指定一个额外的数据文件，它将覆盖现有的国家匹配
coco Congo --additional_data path/to/datafile.csv
有关附加数据文件的示例，请参阅 https://github.com/konstantinstadler/country_converter/tree/master/tests/custom_data_example.txt 。
标志 --UNmember_only (-u) 和 --include_obsolete (-i) 将搜索限制在仅联合国成员国或将其扩展到还包括当前过时的国家。例如，荷属安的列斯群岛于 2010 年解散。
因此：
coco "Netherlands Antilles"
导致“未找到”。但是，可以通过以下方式将搜索扩展到最近解散的国家：
coco "Netherlands Antilles" -i
这导致'ANT'。
除了国家，coco命令行工具还接受各种国家分类（EXIO1, EXIO2, EXIO3, WIOD, Eora, MESSAGE, OECD, EU27, EU28, UN, obsolete, Cecilia2050, BRIC, APEC, BASIC, CIS, G7 , G20)。其中之一可以通过
coco G20
其中列出了该分类中的所有国家/地区。
对于几乎涵盖所有国家的分类（MRIO 和 IAM 分类）
coco EXIO3
列出唯一的分类名称。传递 --to 参数时，将打印所选分类的简化对应关系：
coco EXIO3 --to ISO3
如需更多信息，请致电帮助
coco -h
在 Matlab 中使用
较新（在 2016a 中测试）版本的 Matlab 允许直接调用 Python 函数和库。这需要在系统路径中安装 Python 版本 >= 3.4（例如通过 Anaconda）。
要测试，请在 Matlab 中尝试：
py.print(py.sys.version)
如果可行，您也可以在通过 pip 安装 coco 后使用它（在 windows 命令行 - 请参阅上面的安装说明）：
pip install country_converter --upgrade
在matlab中：
coco = py.country_converter.CountryConverter()
countries = {'The Swedish Kingdom', 'Norway is a Kingdom too', 'Peoples Republic of China', 'Republic of China'};
ISO2_pythontype = coco.convert(countries, pyargs('to', 'ISO2'));
ISO2_cellarray = cellfun(@char,cell(ISO2_pythontype),'UniformOutput',false);
或者，作为长单线：
short_names = cellfun(@char, cell(py.country_converter.convert({56, 276}, pyargs('src', 'UNcode', 'to', 'name_short'))), 'UniformOutput',false);
上述 coco 的所有属性在 Matlab 中也可用：
coco = py.country_converter.CountryConverter();
coco.EU27
EU27ISO3 = coco.EU27as('ISO3');
这些函数返回一个 Pandas DataFrame。可以使用 .values 访问基础值（例如
EU27ISO3.values
我把它留给专业的 Matlab 用户来弄清楚如何进一步处理它们。
另请参阅 IPython Notebook ( country_converter_examples.ipynb ) 以获取更多信息 - Python 中可用的所有函数（例如传递附加数据文件，在丢失数据的情况下指定输出）也可以在 Matlab 中通过 pyargs 函数传递参数。
为国家聚合建立索引
Coco 提供了一个函数，用于在不同的分类之间构建索引向量、矩阵和字典。这可以在 python 和 matlab 中使用。有关详细信息，请参阅 ( country_converter_aggregation_helper.ipynb )
分类方案
目前有以下分类方案可用（有关更多信息，另请参见下面的数据源）：
- ISO2（ISO 3166-1 alpha-2）
- ISO3（ISO 3166-1 alpha-3）
- ISO - 数字（ISO 3166-1 数字）
- 联合国数字代码（M.49 - 在很大程度上遵循 ISO 数字）
- 标准名称或简称
- “官方”名称
- 大陆
- 联合国区域
- EXIOBASE 1 分类
- EXIOBASE 2 分类
- EXIOBASE 3 分类
- WIOD分类
- 伊奥拉
- 经合组织 成员（每年）
- MESSAGE 11 区域分类
- 图片
- 提醒
- 联合国会员国（每年）
- 欧盟 成员国（包括EU12、EU15、EU25、EU27、EU27_2007、EU28）
- 欧洲经济区 成员
- 申根区
- 塞西莉亚 2050分类
- 亚太经合组织
- 金砖四国
- 基本的
- 独联体 （截至 2019 年，不包括土库曼斯坦）
- 七国集团
- G20（将所有欧盟成员国列为个人成员）
- 粮农组织代码（数字）
- GBDcode（数字 - 全球疾病负担国家代码）
- IEA（2021 年世界能源平衡表）
- DACcode （数字 - 经合组织发展援助委员会）
Coco 包含官方认可的代码以及有争议或解散国家的非标准代码。要将集合仅限于官方认可的联合国成员或包括过时的国家，请通过
import country_converter as coco
cc = coco.CountryConverter()
cc_UN = coco.CountryConverter(only_UNmember=True)
cc_all = coco.CountryConverter(include_obsolete=True)
cc.convert(['PSE', 'XKX', 'EAZ', 'FRA'], to='name_short')
cc_UN.convert(['PSE', 'XKX', 'EAZ', 'FRA'], to='name_short')
cc_all.convert(['PSE', 'XKX', 'EAZ', 'FRA'], to='name_short')
cc 结果为 ['Palestine', 'Kosovo', 'not found', 'France']，而 cc_UN 转换为 ['not found', 'not found', 'not found', 'France'] 和 cc_all 转换为['Palestine', 'Kosovo', 'Zanzibar', 'France'] 请注意，底层数据框在属性 .data 中可用（例如 cc_all.data）。
数据来源和进一步阅读
大多数基础数据可以在 Wikipedia 中找到，描述ISO 3166-1的页面是一个很好的起点。联合国区域/代码在联合国统计司 ( unstats ) 网页上提供。ISO 数字和联合国 (M.49) 代码之间的区别 也在 wikipedia 中进行了说明。 EXIOBASE、WIOD和 Eora分类是从各自的数据库中提取的。对于Eora，名称基于网页上提供的“国家名称”csv 文件，但已针对 Eora26 数据库中使用的不同名称进行了更新。MESSAGE 分类遵循 MESSAGE 模型区域描述中给出的 11 区域聚合。这 IMAGE 分类基于“区域分类图”，对于 REMIND ， 我们从模型开发者那里获得了国家映射。
经合组织 和联合国的成员 可以在成员组织的网页上找到， Statoids网页上有关过时的国家代码的信息。
由于英国脱欧进程，欧盟的局势 变得复杂。对于命名，coco 遵循欧盟统计局的词汇表，因此 EU27 是指没有英国的欧盟，而 EU27_2007 是指没有克罗地亚的欧盟（2007 年扩大后的状态）。快捷方式 EU 始终链接到最新的分类。EEA协议对 英国仍然有效（状态 2020 年 9 月，Brexit 过渡期 - 如此处所述），因此英国目前已包含在 EEA 中。
全球疾病负担国家代码是从此处提供的 GBD 代码簿中提取的。
沟通、问题、错误和改进
请使用问题跟踪器来记录错误、提出改进建议以及与 coco 相关的所有其他通信。
您可以在twitter上关注我，以获取有关我所有开源和研究项目的最新消息（偶尔还会有一些随机转推）。
贡献
想贡献？伟大的！如果您想帮助改进 coco 以及如何添加分类的一些提示，请查看 CONTRIBUTING.md 。
相关软件
pycountry包提供对历史国家、国家细分、语言和货币的官方 ISO 数据库的访问。如果您需要转换非英语国家名称， countrynames包含一个广泛的不同语言的国家名称数据库，并具有将它们转换为不同 ISO 3166 标准的功能。 Python-iso3166专注于 ISO 3166 标准中定义的两字母、三字母和三位数代码之间的转换。
如果你使用 R，你应该看看 countrycode。
引用国家转换器
国家转换器的 0.5 版本发表在Journal of Open Source Software上。要在出版物中引用国家/地区转换器，请使用：
Stadler, K. (2017)。国家转换器 coco - 用于在不同分类方案之间转换国家名称的 Python 包。开源软件杂志。doi: 10.21105/joss.00332
有关完整的 bibtex 密钥，请参阅CITATION
致谢
这个包的灵感来自（并且正则表达式主要基于） Vincent Arel-Bundock的R 包国家代码和他的（已失效的）Python 端口（pycountrycode）。非常感谢Robert Gieseke对源代码和论文的审查，以便在Journal of Open Source Software上发表。
