简介
一个用于提取简体中文字符串中省，市和区并能够进行映射，检验和简单绘图的python模块。
举个例子：
["徐汇区虹漕路461号58号楼5楼", "泉州市洛江区万安塘西工业区"]
↓ 转换
|省 |市 |区 |地址 |
|上海市|上海市|徐汇区|虹漕路461号58号楼5楼 |
|福建省|泉州市|洛江区|万安塘西工业区 |注：“地址”列代表去除了省市区之后的具体地址
安装说明
代码目前仅仅支持python3
pip install cpca
注:cpca是chinese province city area的缩写
如果觉得本模块对你有用的话，施舍个star，谢谢。
常见安装问题：
在 windows 上可能会出现类似如下问题
Building wheel for pyahocorasick (setup.py) ... error先去下载 Microsoft Visual C++ Build Tools， 安装完成后，再重新使用 pip install cpca 安装，即可解决问题
中国行政区划分数据获取
提取自 @Vonng 维护的项目 adcode，里面包含中国的所有行政区划和编码
提取的数据文件在为cpca/resources/adcodes.csv
笔者会定期从 adcode 中同步，如果同步的不及时，可以使用本仓库中的 local-sync.py 脚本进行同步，使用方法如下：
git clone git@github.com:Vonng/adcode.git
python local-sync.py <adcode所在目录>Get Started
本模块中最主要的方法是cpca.transform，该方法可以输入任意的可迭代类型（如list，pandas的Series类型等），然后将其转换为一个DataFrame，下面演示一个最为简单的使用方法：
location_str = ["徐汇区虹漕路461号58号楼5楼", "泉州市洛江区万安塘西工业区", "北京朝阳区北苑华贸城"]
import cpca
df = cpca.transform(location_str)
df输出的结果为(adcode为官方地址编码)：
省 市 区 地址 adcode
0 上海市 上海市 徐汇区 虹漕路461号58号楼5楼 310104
1 福建省 泉州市 洛江区 万安塘西工业区 350504
2 北京市 市辖区 朝阳区 北苑华贸城 110105注：程序输出的df是一个Pandas的DataFrame类型变量，DataFrame可以非常轻易地转化为csv或者excel文件，如果你对DataFrame不熟悉的话，可以参考Pandas的官方文档：http://pandas.pydata.org/pandas-docs/version/0.20/dsintro.html#dataframe
，或者往下翻到"示例与测试用例"大标题，那里我也展示了DataFrame的拼接与转换成csv文件的操作。
地理小提示：在中国行政区划中，直辖市的区都不是直接挂在直辖市下面的，而是挂在唯一的一个市辖区下面，普通的市下面也会有市辖区，但是普通的市辖区只是 三级行政单位，不像直辖市的市辖区，是二级行政单位
如果你想获知程序是从字符串的那个位置提取出省市区名的，可以添加一个pos_sensitive=True参数：
location_str = ["徐汇区虹漕路461号58号楼5楼", "泉州市洛江区万安塘西工业区", "北京朝阳区北苑华贸城"]
import cpca
df = cpca.transform(location_str, pos_sensitive=True)
df输出如下：
省 市 区 地址 adcode 省_pos 市_pos 区_pos
0 上海市 上海市 徐汇区 虹漕路461号58号楼5楼 310104 -1 -1 0
1 福建省 泉州市 洛江区 万安塘西工业区 350504 -1 0 3
2 北京市 市辖区 朝阳区 北苑华贸城 110105 -1 -1 0其中省_pos，市_pos和区_pos三列大于-1的部分就代表提取的位置。-1则表明这个字段是靠程序推断出来的，或者没能提取出来。
有的时候为了方便concat，想要自定义输出表的index，可以选择使用transform函数的index参数(这个参数只要保证长度和data相同即可，可以是list或者pandas中相关的类型)，示例如下：
location_str = ["徐汇区虹漕路461号58号楼5楼", "泉州市洛江区万安塘西工业区", "北京朝阳区北苑华贸城"]
import cpca
df = cpca.transform(location_str, index=["2018年","2017年","2016年"])
df输出结果：
省 市 区 地址 adcode
2018年 上海市 上海市 徐汇区 虹漕路461号58号楼5楼 310104
2017年 福建省 泉州市 洛江区 万安塘西工业区 350504
2016年 北京市 市辖区 朝阳区 北苑华贸城 220104绘图：
模块中还自带一些简单绘图工具，可以在地图上将上面输出的数据以热力图的形式画出来.
这个工具依赖folium，为了减小本模块的体积，所以并不会预装这个依赖，在使用之前请使用pip install folium .
代码如下：
from cpca import drawer
#df为上一段代码输出的df
drawer.draw_locations(df[cpca._ADCODE], "df.html")这一段代码运行结束后会在运行代码的当前目录下生成一个df.html文件，用浏览器打开即可看到 绘制好的地图（如果某条数据'省'，'市'或'区'字段有缺，则会忽略该条数据不进行绘制），速度会比较慢，需要耐心等待，绘制的图像如下：
还有更多的绘图工具请参考文档的大标题为“示例与测试用例”的部分。
到这里就你就已经知道了本模块的基本使用了，接下来我会阐明更多细节。
关于匹配与映射的细节
为了保证匹配与映射的正确性，我做了很多细节上的处理，如果在使用本模块的过程中遇到困惑可以参考这里。
- 能够匹配到省或者市的缩写，比如将"北京市"缩写为"北京"，"江苏省"缩写为"江苏"，依旧能够匹配到并且能够自动补全为全称，示例代码如下：
#测试数据
location_strs = ["江苏省南京市鼓楼区256号", "江苏南京鼓楼区256号"]
import cpca
df = cpca.transform(location_strs)
df输出的结果为：
区 市 省 地址 adcode
0 鼓楼区 南京市 江苏省 256号 320106
1 鼓楼区 南京市 江苏省 256号 320106我不仅做了这些缩写情况处理，还处理了诸如"新疆维吾尔族自治区"缩写为"新疆"，"西藏藏族自治区"缩写为"西藏"等情况，如下：
import cpca
location_str = ["新疆","广西","宁夏","西藏"]
df = cpca.transform(location_str)
df输出：
省 市 区 地址 adcode
0 新疆维吾尔自治区 650000
1 广西壮族自治区 450000
2 宁夏回族自治区 640000
3 西藏自治区 540000- 以先出现的地名为准
#测试数据
location_strs = ["江苏省南京市徐州市鼓楼区256号"]
import cpca
df = cpca.transform(location_strs)
df后出现的徐州市并没有被提取。
- 最后一列的地址字段，本质上是截取最后一个地名后面的文字
import cpca
cpca.transform(["11月15日早上9点到11月18日下班前王大猫。在观山湖区"], pos_sensitive=True)输出为:
省 市 区 地址 adcode 省_pos 市_pos 区_pos
0 贵州省 贵阳市 观山湖区 520115 -1 -1 25"观山湖区" 后面已经没有文字可以截取了，所以 “地址” 部分就是一个空字符串
示例与测试用例
本仓库放了一份大约一万多条地址描述信息tests/addr.csv ，用于测试模块，测试代码如下：
测试基本功能：
#读取数据
import pandas as pd
origin = pd.read_csv("tests/addr.csv")
#转换
import cpca
addr_df = cpca.transform(origin["原始地址"])
#输出
processed = pd.concat([origin, addr_df], axis=1)
processed.to_csv("processed.csv", index=False, encoding="utf-8")注意以上代码运行结束后会打印一句warnning，这些warnning是因为程序无法确定某个区县属于哪个市（因为这些区县存在重名问题而且在umap中又没有指定它属于哪一个市）.
测试绘图函数1（绘制热力图）：
模块中绘制热力图的函数是基于folium编写的，为了减小模块体积，在安装模块时没有安装这些绘图库的依赖，如果需要使用这个函数的话，需要先使用pip install folium 安装folium
from cpca import drawer
#processed为上一段代码的processed
drawer.draw_locations(processed[cpca._ADCODE], "processed.html")用浏览器打开"processed.html"文件，发现绘制的局部图像如下（在国内folium的地图显示速度比较慢，所以需要耐心等待地图显示）：
（注意：本模块在绘图时，只绘制那些可以精确地匹配到省市区的地址，对于省市区有一个或多个字段缺失的则会直接忽略）
测试绘图函数2（绘制echarts热力图）:
因为在国内folium的地图显示速度太慢了，所以添加了echarts的热力图绘图函数.
在使用本函数之前需要先用如下命令安装它的依赖（为了减少本模块的体积，所以这些依赖不会被自动安装）：
pip install pyecharts==0.5.11
pip install echarts-countries-pypkg
pip install pyecharts-snapshot示例代码如下，仍然使用之前的测试数据生成的processed变量：
from cpca import drawer
drawer.echarts_draw(processed[cpca._ADCODE], "echarts.html")该接口的更多参数及其含义如下：
def echarts_draw(locations, file_path, title="地域分布图"
, subtitle="location distribute"):
"""
生成地域分布的echarts热力图的html文件.
:param locations: 样本的省市区, pandas的dataframe类型.
:param file_path: 生成的html文件路径.
:param title: 图表的标题
:param subtitle: 图表的子标题
"""然后会在当前目录下生成一个echarts.html文件，用浏览器打开后即可看到图像：
测试绘图函数3(绘制分类信息图)：
在使用本函数之前需要安装的依赖同上一个绘图函数，如果你是跳过了前面的直接读到这里的话，务必向上翻看一下。
样本分类绘制函数，通过额外传入一个样本的分类信息，能够在地图上以不同的颜色画出属于不同分类的样本散点图，以下代码以“省”作为类别信息绘制分类散点图（可以看到，属于不同省的样本被以不同的颜色标记了出来，这里以“省”作为分类标准只是举个例子，实际应用中可以选取更加有实际意义的分类指标）：
from cpca import drawer
drawer.echarts_cate_draw(processed[cpca._ADCODE], processed["省"], "echarts_cate.html")然后会在当前目录下生成一个echarts_cate.html文件，用浏览器打开后即可看到图像：
该接口更多的参数及其含义如下：
def echarts_cate_draw(locations, labels, file_path, title="地域分布图", subtitle="location distribute",
point_size=7):
"""
依据分类生成地域分布的echarts散点图的html文件.
:param locations: 样本的省市区, pandas的dataframe类型.
:param labels: 长度必须和locations相等, 代表每个样本所属的分类.
:param file_path: 生成的html文件路径.
:param title: 图表的标题
:param subtitle: 图表的子标题
:param point_size: 每个散点的大小
"""How to Contribute
项目代码还很粗糙，如果大家对代码有所改进，欢迎提交回本项目 ，在提交之前，注意以下两点：
- 在
tests添加相应的单元测试 - 使用
python setup.py test来运行所有单元测试，确保所有单测都是通过的
之后即可提交PR
END
如果大家在使用过程中发现一些匹配错误的地址，欢迎提issue来帮助我收集这些错误用例和改善算法，毕竟笔者手头数据有限，难以考虑到所有边界情况