★★实用方法推荐★★

数据读写

读取单个文件

备注

自动识别文件类型并选择合适的方法读取，日常使用中99%以上的数据都可以用这一个方法读取

ricco.etl.extract.rdf(file_path: str, *, sheet_name=0, sheet_contains: str = None, encoding: str = None, info: bool = False, dtype=None, columns: list | str = None, only: list | str = None, nrows: int = None, limit: int = None, recursive: bool = True, access_key=None, secret_key=None) → DataFrame

常用文件读取函数，支持 .csv/.xlsx/.xls/.shp/.parquet/.pickle/.feather/.kml/.ovkml/ .geojson/.shp/.json等

参数:

file_path -- 文件或文件夹路径
sheet_name -- 数据所在sheet的名称，仅对.xlsx/.xls生效
sheet_contains -- 筛选sheet名称中包含此字符串的sheet，仅对.xlsx/.xls生效
encoding -- 编码
info -- 是否打印数据集情况（shape & columns）
dtype -- 指定读取列的类型
columns -- 指定读取的列名
only -- 同columns，columns优先
nrows -- 指定读取的行数
limit -- 同nrows，nrows优先
recursive -- 是否循环遍历更深层级的文件夹，默认为True，仅当路径为文件夹时生效
access_key -- 阿里云OSS访问密钥
secret_key -- 阿里云OSS访问密钥

from ricco import rdf
df = rdf('/path/test.csv')

读取文件夹

备注

自动识别文件类型并选择合适的方法读取整个文件夹的数据

ricco.etl.extract.rdf(file_path: str, *, sheet_name=0, sheet_contains: str = None, encoding: str = None, info: bool = False, dtype=None, columns: list | str = None, only: list | str = None, nrows: int = None, limit: int = None, recursive: bool = True, access_key=None, secret_key=None) → DataFrame

常用文件读取函数，支持 .csv/.xlsx/.xls/.shp/.parquet/.pickle/.feather/.kml/.ovkml/ .geojson/.shp/.json等

参数:

file_path -- 文件或文件夹路径
sheet_name -- 数据所在sheet的名称，仅对.xlsx/.xls生效
sheet_contains -- 筛选sheet名称中包含此字符串的sheet，仅对.xlsx/.xls生效
encoding -- 编码
info -- 是否打印数据集情况（shape & columns）
dtype -- 指定读取列的类型
columns -- 指定读取的列名
only -- 同columns，columns优先
nrows -- 指定读取的行数
limit -- 同nrows，nrows优先
recursive -- 是否循环遍历更深层级的文件夹，默认为True，仅当路径为文件夹时生效
access_key -- 阿里云OSS访问密钥
secret_key -- 阿里云OSS访问密钥

from ricco import rdf_by_dir
df = rdf_by_dir('/path_dir/', exts=['.csv'])

保存文件

备注

根据扩展名自动识别文件类型，并保存至对应的文件类型

ricco.etl.load.to_file(df: DataFrame, filepath: str, *, index=False, log=True, encoding=None, access_key=None, secret_key=None)

根据文件扩展名，将Dataframe保存为文件

参数:

df -- 要保存的Dataframe
filepath -- 文件路径，包含扩展名
index -- 是否保存索引，默认不保存
log -- 是否打印保存信息
encoding -- 保存文件的编码
access_key -- 阿里云OSS访问密钥
secret_key -- 阿里云OSS访问密钥

import pandas as pd
from ricco import to_file
df = pd.DataFrame()
to_file(df, '/path/test.csv')

文件处理

文件拆分

备注

将文件拆分为多个文件，放置在与文件同名目录下；可按数据量和文件数量进行拆分；可自定义文件类型

ricco.etl.file.split2x(filename: str, to_dir=None, *, chunksize: int = None, parts: int = None, to_ext='.csv', log=True, fn=None)

将文件拆分为多个文件，放置在与文件同名目录下

参数:

filename -- 输入的文件路径
chunksize -- 每份文件的数据量
parts -- 输出的文件个数
to_ext -- 输出的文件扩展名
log -- 是否输出文件保存信息
fn -- 处理函数

from ricco import split2x
split2x('/path/test.csv', chunksize=1000)
split2x('/path/test.csv', parts=3)

文件批量处理reshape

备注

将文件夹的文件大小进行统一拆分，并可传入自定义处理函数

ricco.etl.file.reshape_files(from_dir, to_dir, from_ext=None, to_ext=None, chunksize: int = 100000, func=None, log=False, **kwargs)

将文件拆分成小文件，并保存到to_dir中

参数:

from_dir -- 读取的目录
to_dir -- 保存的目录
from_ext -- 读取的扩展名，默认为None，全部读取
to_ext -- 保存的扩展名，默认为None，若读取文件的扩展名唯一，则使用读文文件的扩展名，反之需要指定
chunksize -- 每个文件的大小
func -- 自定义处理函数
log -- 是否打印日志

from ricco import reshape_files

def process(df):
  return df

# 将'/path_dir/'中的文件，拆分为大小为1000的 csv 文件，并保存在'/path_dir_to/'目录下，
# 处理过程中调用 'process' 方法进行处理
reshape_files(
    from_dir='/path_dir/',
    to_dir='/path_dir_to/',
    to_ext='.csv',
    chunksize=1000,
    func=process,
)

万能格式转换

备注

批量转换可使用 dir_file_to_x()

ricco.etl.file.file_to_x(filepath, to_ext, to_dir=None, delete=False, overwrite=False, log=True, **kwargs)

文件格式转换，整体读取并转换，将文件整体加载到内存中再保存为另一种文件格式

参数:

filepath -- 待转换的文件路径
to_ext -- 要保存的文件扩展名
to_dir -- 要写入的文件路径，默认存放在原目录
delete -- 是否删除原文件，默认不删除
overwrite -- 是否覆盖原文件，默认不覆盖
log -- 是否输出文件保存、删除日志

from ricco import file_to_x
# 将csv转为Excel文件，保存在相同目录下
file_to_x('/path/test.csv', to_ext='.xlsx')

地理处理

自动转为shapely格式

备注

将带有地理信息的数据，自动转为 shapely 格式的GeoDataframe，地理格式可以为wkb/wkt/geojson等

ricco.geometry.df.auto2shapely(df, geometry='geometry') → GeoDataFrame: 自动识别地理格式并转换为shapely格式

from ricco import auto2shapely
from ricco import rdf

df = rdf('./test.csv')
auto2shapely(df)  # Return: GeoDataframe

shapely转为任意格式

ricco.geometry.df.shapely2x(df: GeoDataFrame | DataFrame, geometry_format: str, geometry='geometry')

将shapely转为指定的格式

参数:

df -- 要转换的GeoDataFrame
geometry_format -- 支持wkb,wkt,shapely,geojson
geometry -- geometry列的列名，默认“geometry”

from ricco import rdf
from ricco import shapely2x

df = rdf('./test.csv')
# 转为wkb格式的Dataframe
shapely2x(df, geometry_format='wkb')

shapely转为任意格式

ricco.geometry.df.auto2x(df, geometry_format: str, geometry='geometry')

将geometry转为指定格式

参数:

df -- 要转换的Dataframe
geometry_format -- 要转换为的geometry类型，支持shapely,wkb,wkt,geojson
geometry -- geometry列的列名，默认为“geometry”

from ricco import rdf
from ricco import auto2x

df = rdf('./test.csv')
# 转为wkb格式的Dataframe
auto2x(df, geometry_format='wkb')

空间计算

投影变换

备注

根据经纬度自动获取 epsg code 进行投影，也可以指定城市和 epsg code 进行投影，该方法是对geometry列进行投影；如需要对经纬度进行投影，请使用`projection_lnglat()`方法

ricco.geometry.df.projection(df: GeoDataFrame, epsg: int = None, city: str = None, crs=None, c_geometry='geometry') → GeoDataFrame

投影变换

参数:

df -- 输入的GeomDataFrame格式的数据
epsg -- epsg code, 第一优先级
city -- 城市名称，未传入epsg的情况下将通过城市名称获取epsg，若二者都为空则根据经纬度获取
crs -- 投影坐标系，第二优先级
c_geometry -- geometry的列名

ricco.geometry.df.projection_lnglat(df: DataFrame, epsg=None, city=None, crs=None) → DataFrame

直接对经纬度进行投影变换

参数:

df -- 输入的GeomDataFrame格式的数据
epsg -- epsg code, 第一优先级
city -- 城市名称，未传入epsg的情况下将通过城市名称获取epsg，若二者都为空则根据经纬度获取
crs -- 投影坐标系，第二优先级

面积计算

备注

自动地理转换、投影、计算面积，新增面积列`area`，不改变原数据

ricco.geometry.df.get_area(df: DataFrame, c_dst='area', epsg: int = None, decimals=2) → DataFrame

计算面积（单位：平方米）

参数:

df -- 要计算的面数据
c_dst -- 输出面积的列名，默认为“area”
epsg -- 对于跨时区或不在同一个城市的可以指定epsg code，默认会根据经度中位数获取
decimals -- 要保留的小数位数

近邻分析

备注

计算一个数据集中的元素到另一个数据集中全部元素的最短距离（单位：米）,同时可进行其他统计

ricco.geometry.df.nearest_kdtree(df: DataFrame, df_poi: DataFrame, /, *, c_count: str = 'count', c_min_distance: str = 'min_distance', agg: dict = None, limit: int = None, r: int | float = None, keep_origin: bool = False, leaf_size: int = 2, epsg: int = None, city=None, crs=None)

KDTree近邻分析，计算一个数据集中的元素到另一个数据集中全部元素的最短距离（单位：米）, 同时可进行其他运算

参数:

df -- 基础数据集，统计该数据及周边的其他数据集的信息
df_poi -- 被统计的数据集
c_count -- 计数列字段名，默认“count”
c_min_distance -- 最短距离字段名，默认“min_distance”
agg -- 计算 df_poi 中的其他字段，格式如: {'面积': ['sum', 'mean']}，即计算面积的和、均值
limit -- 限制符合条件的 df_poi 中的个数，由近及远
r -- 限制查询半径
keep_origin -- 是否保留匹配后原始的索引信息
leaf_size -- KDTree 叶子节点大小
epsg -- 投影代码，用于投影，epsg/city/crs指定多个时以epsg为准
city -- 城市，用于获取城市中心点，epsg/city/crs指定多个时以epsg为准
crs -- 数据集的 crs，epsg/city/crs指定多个时以epsg为准

ricco.geometry.df.nearest_neighbor(df: DataFrame, df_target: DataFrame, c_dst: str = 'min_distance', epsg: int = None, r=None) → DataFrame

近邻分析，计算一个数据集中的元素到另一个数据集中全部元素的最短距离（单位：米）

参数:

df
df_target
c_dst -- 输出最短距离的列名，默认为“min_distance”
epsg -- 对于跨时区或不在同一个城市的可以指定epsg code，默认会根据经度中位数获取
r -- 限制查询半径

buffer计算

备注

生成指定半径的buffer的geometry列

ricco.geometry.df.buffer(df: DataFrame, radius: int | float, city: str = None, geo_type: str = 'point', geometry: str = 'geometry', buffer_geometry: str = 'buffer_geometry', geo_format='wkb') → DataFrame

获得一定半径的缓冲区

参数:

df -- pd.DataFrame, 包含地理信息的DataFrame
radius -- numeric, 缓冲区半径（单位米）
city -- str, 可选, 投影城市，可提高数据精度
geo_type -- str, 地理数据类型，可选point, line或polygon(包括multipolygon)，默认point
geometry -- str, geometry字段名，默认"geometry"
buffer_geometry -- 输出的缓冲区geometry字段名，默认"buffer_geometry"
geo_format -- str, 输出的缓冲区geometry格式，支持wkb,wkt,shapely,geojson，默认wkb

返回:

包含缓冲区geometry的DataFrame

空间统计

备注

对面数据覆盖范围内的点数据进行空间统计

ricco.geometry.df.spatial_agg(df: DataFrame, polygon_df: DataFrame, by: str | list[str], agg: dict, c_polygon_geometry: str = 'geometry') → DataFrame

对面数据覆盖范围内的点数据进行空间统计

参数:

df -- 点数据dataframe;
polygon_df -- 面数据dataframe;
by -- 空间统计单位字段；
agg -- 空间统计操作。格式为{'被统计字段名': '操作名', ...}的字典。如{'poi':'sum'};
c_polygon_geometry -- 面数据geometry字段名，默认"geometry";

返回:

pd.DataFrame, 包含空间统计单位字段和被统计字段和面数据geometry的DataFrame

空间连接打标签

ricco.geometry.df.mark_tags_v2(df: DataFrame, polygon_df: DataFrame, c_tags: list | str = None, col_list=None, *, predicate='intersects', drop_geometry=False, geometry_format='wkb', warning=True, c_lng='lng', c_lat='lat', c_geometry='geometry', c_polygon_geometry='geometry', ensure_point=True)

使用面数据通过空间关联（sjoin）给数据打标签

参数:

df -- 要打标签的数据，一般为点数据，如为面数据，则会自动提取面内点计算
polygon_df -- 标签列所在的数据集，一般为面数据
c_tags -- 面数据中要关联到结果中的标签字段名，若为空则全部关联
col_list -- (已弃用)，同c_tags
predicate -- 关联方法，默认 'intersects'
drop_geometry -- 结果是否删除point_df中的geometry，默认不删除
geometry_format -- 输出的geometry格式，支持wkb,wkt,shapely,geojson，默认wkb
warning -- 是否输出警告信息
c_lng -- 指定点数据的经度列名
c_lat -- 指定点数据的经度列名
c_geometry -- 指定点数据的geometry列名
c_polygon_geometry -- 指定面数据的geometry列名
ensure_point -- point_df是否强制转换为点数据

from ricco import rdf
from ricco import mark_tags_v2

df_poi = rdf('./poi.csv')
df_plate = rdf('./plate.csv')

# 给POI数据打上plate_name的标签
mark_tags_v2(df_poi, df_plate, col_list='plate_name')