★★实用方法推荐★★

数据读写

读取单个文件

备注

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

ricco.etl.extract.rdf(file_path: str, *, sheet_name=0, sheet_contains: str = None, encoding: str = None, info: bool = False, dtype=None, columns: (<class 'list'>, <class 'str'>) = None, nrows: int = None, recursive: bool = True) → 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 – 指定读取的列名
nrows – 指定读取的行数
recursive – 是否循环遍历更深层级的文件夹，默认为True，仅当路径为文件夹时生效

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: (<class 'list'>, <class 'str'>) = None, nrows: int = None, recursive: bool = True) → 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 – 指定读取的列名
nrows – 指定读取的行数
recursive – 是否循环遍历更深层级的文件夹，默认为True，仅当路径为文件夹时生效

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

保存文件

备注

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

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

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

参数:

df – 要保存的Dataframe
filepath – 文件路径，包含扩展名
index – 是否保存索引，默认不保存
log – 是否打印保存信息
encoding – 保存文件的编码

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

文件处理

文件拆分

备注

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

ricco.etl.file.split2x(filename: str, *, chunksize: int | None = None, parts: int | None = 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: (<class 'geopandas.geodataframe.GeoDataFrame'>, <class 'pandas.core.frame.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 = None, city: str | None = None, crs=None) → GeoDataFrame

投影变换

参数:

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

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 = None, decimals=2) → DataFrame

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

参数:

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

近邻分析

备注

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

ricco.geometry.df.nearest_kdtree(df: ~pandas.core.frame.DataFrame, df_poi: ~pandas.core.frame.DataFrame, /, *, c_count: str = 'count', c_min_distance: str = 'min_distance', agg: dict = None, limit: int = None, r: (<class 'int'>, <class '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 = None) → DataFrame

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

参数:

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

buffer计算

备注

生成指定半径的buffer的geometry列

ricco.geometry.df.buffer(df: DataFrame, radius: int | float, city: str | None = 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(point_df: DataFrame, polygon_df: DataFrame, by: str | List[str], agg: dict, polygon_geometry: str = 'geometry') → DataFrame

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

参数:

point_df – pd.DataFrame, 点数据dataframe;
polygon_df – pd.DataFrame, 面数据dataframe;
by – Union[str, List[str]], 空间统计单位字段；
agg – dict, 空间统计操作。格式为{‘被统计字段名’: ‘操作名’, …}的字典。如{‘poi’:’sum’};
polygon_geometry – str, 面数据geometry字段名，默认”geometry”;

返回:

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

空间连接打标签

ricco.geometry.df.mark_tags_v2(point_df: ~pandas.core.frame.DataFrame, polygon_df: ~pandas.core.frame.DataFrame, col_list: (<class 'list'>, <class 'str'>) = None, *, predicate='intersects', drop_geometry=False, geometry_format='wkb', warning=True, point_lng='lng', point_lat='lat', point_geometry='geometry', polygon_geometry='geometry', warning_message=None, ensure_point=True)

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

参数:

point_df – 点数据
polygon_df – 面数据
col_list – 面数据中要关联到结果中的列，若为空则全部关联
predicate – 关联方法，默认 ‘intersects’
drop_geometry – 结果是否删除geometry，默认不删除
geometry_format – 输出的geometry格式，支持wkb,wkt,shapely,geojson，默认wkb
warning – 是否输出警告信息
point_lng – 指定点数据的经度列名
point_lat – 指定点数据的经度列名
point_geometry – 指定点数据的geometry列名
polygon_geometry – 指定面数据的geometry列名
warning_message – 是否输出警告信息，已弃用
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')