pandas Index 对象 API 完全指南从基础索引到 MultiIndex 与时间索引【免费下载链接】pandasFlexible and powerful data analysis / manipulation library for Python, providing labeled data structures similar to R data.frame objects, statistical functions, and much more项目地址: https://gitcode.com/gh_mirrors/pa/pandas导读本文以 pandas 官方 API 参考文档doc/source/reference/indexing.rst为骨架系统梳理 pandas 中全部索引Index对象的公开 API从通用的Index基类属性与方法到RangeIndex、CategoricalIndex、IntervalIndex、MultiIndex再到时间序列场景下的DatetimeIndex、TimedeltaIndex、PeriodIndex并配合仓库源码pandas/core/indexes/说明各方法的底层行为与适用场景。读完本文你将能够按图索骥地选用正确的索引 API 完成标签定位、对齐、合并、切片、时间重采样与多层级选取等实战任务。提示pandas 官方建议——下面列举的许多方法在包含索引的对象Series/DataFrame上同样可用实践中应优先使用对象级方法如Series.loc、DataFrame.reindex再考虑直接调用索引方法。一、Index所有索引对象的基石Index是 pandas 中所有索引类型的抽象基类定义在 pandas/core/indexes/base.py。它是不可变的、可哈希的、有序的标签集合其实现混合了 NumPy 数组语义继承IndexOpsMixin与 pandas 对象语义继承PandasObject。其余所有具体索引类型RangeIndex、CategoricalIndex、IntervalIndex、MultiIndex、DatetimeIndex、TimedeltaIndex、PeriodIndex都继承自Index因此本节列出的属性和方法对全部索引类型通用。1.1 基础属性Properties官方 API 参考中Index一节列出的属性按功能可归为以下几组分组属性含义底层数据values、array、dtype标签的底层 NumPy 数组 / 扩展数组表示及其 dtype结构信息shape、ndim、size、empty、nbytes、T维度、长度、是否为空、内存占用字节、转置唯一性 / 单调性is_unique、has_duplicates、is_monotonic_increasing、is_monotonic_decreasing是否唯一、是否含重复项、是否单调递增/递减缺失值hasnans是否含 NaN类型推断inferred_type推断出的元素类型如integer、string、datetime64等名称name、names索引名称MultiIndex有多个名称内存memory_usage索引占用的内存字节数源码佐证与实战建议is_monotonic_increasing/is_monotonic_decreasing直接决定了get_loc在重复标签下返回slice还是布尔掩码见下文 3.1 节has_duplicates与is_unique则在Index.get_indexer、Index.join等对齐逻辑中被广泛依赖用于选择哈希查找还是线性查找路径。判断一个索引是否为内存友好的稀疏表示可用memory_usage(deepTrue)统计真实占用。1.2 修改与计算Modifying and computations类别方法说明聚合与归约all、any、min、max、argmin、argmax逻辑归约与极值定位复制与重命名copy、rename复制索引 / 修改name返回新对象删除与去重delete、drop、drop_duplicates、duplicated、unique、nunique、value_counts按位置/标签删除、去重、计数插入与填充insert、repeat、replace、where、putmask、take插入新标签、重复元素、替换值、条件填充、按位置选取对齐与相等equals、identical、factorize、reindex值级比较equals与identical的区别见下、因子化编码、按新标签重排容易混淆的两个方法equals仅比较值是否相等忽略名称与 dtype 的细微差异返回boolidentical要求索引对象完全一致包括name、dtype 等元数据源码见 pandas/core/indexes/base.py 同文件中的实现。1.3 MultiIndex 兼容与缺失值处理MultiIndex 兼容set_names批量/按层级设置名称、droplevel移除指定层级返回层级更少的索引或MultiIndex。缺失值fillna用给定值填充 NaN 标签、dropna剔除 NaN 标签、isna、notna返回布尔数组。1.4 类型转换Conversion方法说明astype转换 dtype如Index([1,2,3]).astype(str)infer_objects尝试将 object 数组推断为更具体的类型item当索引恰好只有一个元素时返回该标量map用映射函数/字典批量变换标签返回新Indexravel展平为一维数组to_list转为 Python list同tolistto_series转为以自身为索引的Seriesto_frame转为单列DataFrameto_numpy转为 NumPy 数组view以不同 dtype 视图查看底层数据通常用于int64→timedelta64等1.5 排序Sortingargsort返回排序后的位置索引数组sort_values返回排序后的新Index默认升序可用ascendingFalsesearchsorted在有序索引中二分查找插入位置返回整数数组sideleft/right控制重复值时的插入边界。1.6 合并 / 连接 / 集合操作Combining / joining / set operations方法语义append追加另一个索引返回新索引重复项保留join按标签对齐合并how支持left、right、inner、outerintersection交集union并集默认排序difference差集出现在自身、不出现在对方symmetric_difference对称差集1.7 标签定位与切片Selecting这是Index最核心的一组方法直接支撑Series.loc/DataFrame.loc的底层实现方法返回典型场景get_loc(key)int/slice/ 布尔数组单个标签的整数位置get_indexer(target)np.ndarray[np.intp]批量标签对齐未匹配返回-1get_indexer_for(target)np.ndarray[np.intp]允许非唯一索引无条件返回位置get_indexer_non_unique(target)(indexer, missing)非唯一索引下的批量定位get_level_values(level)Index取指定层级的全部标签get_slice_bound(label, side)int切片边界整数slice_indexer(start, end)slice构造标签区间切片slice_locs(start, end)(int, int)切片起止位置isin(values)布尔数组判断每个标签是否属于给定集合asof(label)标量返回小于等于label的最大标签时间序列场景常用asof_locs(where, mask)位置数组asof的向量化版本源码解析get_locpandas/core/indexes/base.py 中get_loc的返回类型完全取决于索引特征唯一索引 → 返回int含重复但单调的索引 → 返回slice含重复且非单调的索引 → 返回布尔掩码数组。 unique_index pd.Index(list(abc)) unique_index.get_loc(b) 1 monotonic_index pd.Index(list(abbc)) monotonic_index.get_loc(b) slice(1, 3, None) non_monotonic_index pd.Index(list(abcb)) non_monotonic_index.get_loc(b) array([False, True, False, True])其内部实现为self._engine.get_loc(casted_key)——每种索引类型都绑定了一个底层的哈希/区间查找引擎Index._engine_typeget_loc的性能与语义均由此引擎决定。源码解析get_indexerpandas/core/indexes/base.py 中get_indexer支持三个关键参数methodNone仅精确匹配默认、pad/ffill取前一个值、backfill/bfill取后一个值、nearest取最近值平局时偏向更大的标签limit非精确匹配时连续匹配的最大标签数tolerance非精确匹配的最大距离要求abs(index[indexer] - target) tolerance可为标量或与索引等长的列表类对象。返回值中未匹配的目标标签位置标记为-1 index pd.Index([c, a, b]) index.get_indexer([a, b, x]) array([ 1, 2, -1])二、Numeric IndexRangeIndexRangeIndex定义在 pandas/core/indexes/range.py是不可变的单调整数区间索引仅在 64 位整数范围内表示单调区间是内存最省、速度最快的一种索引当用户未显式提供索引时DataFrame与Series默认使用它作为行索引。它的构造与 Python 内置range完全一致start省略时默认为 0、stop开区间不含终点、step步长。dtype与copy参数仅为了与其他索引类型接口统一而保留实际不生效。 list(pd.RangeIndex(5)) [0, 1, 2, 3, 4] list(pd.RangeIndex(0, 10, 2)) [0, 2, 4, 6, 8] list(pd.RangeIndex(2, -10, -3)) [2, -1, -4, -7]与RangeIndex相关的公开 API 还包括start/stop/step三个只读属性直接返回区间的起止与步长from_range(rng, nameNone)类方法从 Pythonrange对象构造RangeIndex。性能要点由于只保存(start, stop, step)三元组而非全部元素RangeIndex的内存占用不随长度增长且其底层引擎固定为libindex.Int64Engine见 pandas/core/indexes/range.py查找与切片均为 O(1)/O(log n) 级别。三、CategoricalIndex分类索引CategoricalIndex定义于 pandas/core/indexes/category.py底层由Categorical数据支撑用于值域很小但重复度极高的标签场景。它的 dtype 不再是普通 NumPy dtype而是CategoricalDtype因此被归类为扩展数组支持的索引NDArrayBackedExtensionIndex。3.1 分类组件Categorical components属性 / 方法说明codes每个元素对应的整数编码指向categories的位置categories分类类别去重后的取值集合ordered是否为有序分类rename_categories重命名类别长度必须与类别数一致reorder_categories重排类别顺序集合相同仅改变顺序add_categories追加新类别remove_categories移除类别已使用的值会变为 NaNremove_unused_categories删除未被实际使用的类别set_categories整体替换类别集合as_ordered/as_unordered切换有序 / 无序状态3.2 修改与计算CategoricalIndex.map按映射字典或函数转换每个标签CategoricalIndex.equals分类语义下的相等比较忽略类别顺序差异。适用场景当一列标签是有限的枚举值如省份、状态码且需要按类别顺序排序、做类别级聚合时优先使用CategoricalIndex可显著节省内存并让排序语义与业务一致。四、IntervalIndex区间索引IntervalIndex定义于 pandas/core/indexes/interval.py用于表示左闭右开、左开右闭等形式的数值区间每个元素是一个Interval。它是 pandas 区间分箱如pd.cut、Interval列的索引载体。4.1 构造与组件三个常用类方法构造器构造器语义from_arrays(left, right, closedright)由左右端点数组构造from_tuples(intervals)由(left, right)元组序列构造from_breaks(breaks, closedright)由有序断点数组构造自动生成相邻区间组件属性属性 / 方法说明left/right左端点数组 / 右端点数组mid区间中点closed开闭约定left、right、both、neitherlength区间长度values底层IntervalArrayis_empty是否存在空区间is_overlapping区间是否存在重叠会触发完整检测is_non_overlapping_monotonic是否互不重叠且单调可启用快速查找4.2 定位、包含与变换get_loc/get_indexer对区间索引做标签定位精确匹配区间端点set_closed切换开闭约定返回新索引contains(value)判断标量是否落在任一区间内返回布尔数组overlaps(other)判断区间与给定区间是否重叠to_tuples将区间转为(left, right)元组数组。典型用例配合pd.cut生成分组区间后用IntervalIndex作为分组键或DataFrame的索引可基于get_indexer快速完成数值 → 所属区间的映射查找。五、MultiIndex多层级索引MultiIndex定义于 pandas/core/indexes/multi.py是 pandas 处理多维标签的核心结构本质是若干层标签的笛卡尔组合。它同样继承自Index因此 1.11.7 节的通用属性和方法values、dropna、join、get_indexer等同样适用。5.1 构造器MultiIndex constructors官方 API 列出四个类方法构造器说明from_arrays(arrays, sortorderNone, namesNone)由若干等长数组构造第 i 个数组构成第 i 层from_tuples(tuples, namesNone)由(level0, level1, ...)元组序列构造from_product(iterables, namesNone)由若干可迭代对象的笛卡尔积构造from_frame(df, namesNone)由DataFrame的列构造源码示例from_arrayspandas/core/indexes/multi.py 中每个输入数组对应一层各数组第 i 个元素共同组成第 i 个元组 arrays [[1, 1, 2, 2], [red, blue, red, blue]] pd.MultiIndex.from_arrays(arrays, names(number, color)) MultiIndex([(1, red), (1, blue), (2, red), (2, blue)], names[number, color])from_tuples适用于元组列表形态的数据from_product则适合生成因子实验式的全组合标签 pd.MultiIndex.from_product([[a, b], [1, 2]]) MultiIndex([(a, 1), (a, 2), (b, 1), (b, 2)])5.2 属性MultiIndex properties属性说明names各层名称元组levels各层去重后的标签列表codes各层标签在levels中的整数编码nlevels层级数量levshape各层大小组成的元组dtypes各层 dtype5.3 组件操作MultiIndex components方法说明set_levels/set_codes替换层级标签 / 编码to_flat_index展平为普通Index元素为元组to_frame转为每层一列的DataFramesortlevel(level)按指定层级排序返回(MultiIndex, indexer)droplevel(level)移除一个或多个层级swaplevel(i-2, j-1)交换两个层级的顺序源码见 pandas/core/indexes/multi.pyreorder_levels(order)按给定顺序重排层级源码见 pandas/core/indexes/multi.pyremove_unused_levels移除codes中未使用的层级值drop/copy/append/truncate删除、复制、追加、截断5.4 选取MultiIndex selecting方法说明get_loc(key)对完整元组键做精确定位get_locs(seq)支持跨层级的切片/列表/布尔组合式定位见 pandas/core/indexes/multi.py是df.loc[(slice(None), x), :]的底层支撑get_loc_level(key, level0, drop_levelTrue)同时返回位置与剩余层级部分标签选取的核心实现见 pandas/core/indexes/multi.pyget_indexer(target)批量对齐未匹配返回-1get_level_values(level)返回指定层级的全部标签5.5 IndexSlice多层切片利器pd.IndexSlice即pd.IndexSlice pd.IndexSlice语法糖也可写作pd.IndexSlice[:]用于在.loc中表达跨层级的混合切片 idx pd.MultiIndex.from_product([[a, b], [1, 2, 3]]) df pd.DataFrame({v: range(6)}, indexidx) df.loc[pd.IndexSlice[a, 1:2], :] v a 1 0 2 1IndexSlice让第一层选 a第二层切 1:2这样的混合选取一行写出避免嵌套元组的繁琐。六、DatetimeIndex日期时间索引DatetimeIndex定义于 pandas/core/indexes/datetimes.py是时间序列分析的主角底层以纳秒/微秒等整数编码存储支持时区、频率推断与丰富的日期组件访问。其基础能力get_loc、reindex、join等全部继承自Index此处只列出时间特有的 API。6.1 时间 / 日期组件Time/date components分组属性日历字段year、month、day、quarter、dayofyear/day_of_year、dayofweek/day_of_week、weekday时刻字段hour、minute、second、microsecond、nanosecond日期对象datedatetime.date数组、timedatetime.time数组、timetz带时区的time边界判断is_month_start、is_month_end、is_quarter_start、is_quarter_end、is_year_start、is_year_end、is_leap_year频率与时区freq、freqstr、inferred_freq、tz底层编码asi8int64 纳秒编码、unit时间单位如ns、us注意dayofyear/day_of_year、dayofweek/day_of_week是新旧命名并存官方推荐使用带下划线的day_of_year、day_of_week形式。6.2 选取Selectingindexer_at_time(time)返回一天中指定时刻所在位置的整数数组用于日内切片indexer_between_time(start_time, end_time, include_startTrue, include_endTrue)返回介于两个时刻之间的位置数组。两者是df.between_time(...)的底层实现适合每天 09:30-15:00这类日内时段过滤。6.3 时间特有操作Time-specific operations方法说明normalize时间归零到当天 00:00:00strftime按格式串转字符串数组snap(freq)将时间吸附到最近的一个频率边界tz_convert/tz_localize时区转换 / 时区本地化tz_localize可用ambiguous、nonexistent参数处理歧义时刻round/floor/ceil按频率取整如h、5minround的ambiguous与nonexistent参数处理边界情况month_name/day_name返回月份 / 星期名称支持locale参数6.4 转换Conversionas_unit(unit)切换底层时间单位s、ms、us、ns可避免超大范围数据溢出to_period(freq)转为PeriodIndex例如把日级时间转为M月周期to_pydatetime转为 Pythondatetime.datetime数组to_series/to_frame转为Series/DataFrameto_julian_date转为儒略日数值。6.5 统计方法DatetimeIndex.mean()时间平均值需单调且有频率或显式给出skipnaDatetimeIndex.std()时间标准差。七、TimedeltaIndex时间差索引TimedeltaIndex定义于 pandas/core/indexes/timedeltas.py表示相对时间间隔如1 day 02:00:00底层同样以 int64 编码存储。7.1 组件Components属性说明days天数部分不含时分秒换算seconds秒部分086399microseconds微秒部分nanoseconds纳秒部分0999components返回一个DataFrame含days/hours/minutes/seconds/...各列inferred_freq推断的频率字符串asi8int64 底层编码unit底层时间单位7.2 转换与方法as_unit(unit)切换单位s、ms、us、nsto_pytimedelta转为 Pythondatetime.timedelta数组to_series/to_frame转为Series/DataFrameround/floor/ceil按频率取整mean()时间差均值。典型场景对耗时/间隔数据建索引或把DataFrame中两列时间相减得到TimedeltaIndex后进行区间分箱与重采样。八、PeriodIndex周期索引PeriodIndex定义于 pandas/core/indexes/period.py表示离散的时间周期如 2024-01 这个月、某个季度与DatetimeIndex连续时间点互补。每个元素是一个Period含固定的freq。8.1 属性Properties属性说明year、month、day、hour、minute、second日历/时刻字段quarter、qyear季度序号、所属年度财年week、weekofyear、weekday、dayofweek/day_of_week周相关字段dayofyear/day_of_year年内第几天days_in_month/daysinmonth当月天数start_time/end_time周期起止时刻freq、freqstr频率对象 / 频率字符串is_leap_year是否闰年asi8int64 周期序号编码8.2 方法Methods方法说明asfreq(freq)频率转换如D→M支持howstart/end指定对齐方式strftime(fmt)按格式转字符串to_timestamp(freqNone, howstart)转为DatetimeIndex周期起点或终点from_fields(year, month, dayNone, ...)由字段数组构造类方法from_ordinals(ordinals, freq)由周期序号构造类方法典型场景df.resample(M).mean()后索引即为PeriodIndex财务季度统计、同比/环比聚合时常用asfreq在日/月/季/年频率间切换。九、索引选择速查表数据类型推荐索引关键 API默认整数行号RangeIndexstart/stop/step、from_range小值域重复标签CategoricalIndexcategories/codes、rename_categories、set_categories数值区间分箱IntervalIndexfrom_breaks、contains、overlaps、get_indexer多维复合标签MultiIndexfrom_arrays/from_product、get_loc_level、get_locs、IndexSlice时间点序列DatetimeIndextz_localize/tz_convert、floor/ceil、to_period、indexer_between_time时间间隔序列TimedeltaIndexcomponents、round/floor/ceil、as_unit离散周期序列PeriodIndexasfreq、to_timestamp、from_fields选择原则先判断标签是整数区间、分类、区间、多维、时间点、时间差还是周期再决定索引类型DatetimeIndex偏重连续时间点运算PeriodIndex偏重离散周期聚合两者可通过to_period/to_timestamp双向转换。十、深入阅读路径API 参考原文档doc/source/reference/indexing.rstIndex至PeriodIndex全部条目索引核心实现pandas/core/indexes/base.pyIndex类get_loc见 L3757get_indexer见 L3818各索引子类pandas/core/indexes/range.py、pandas/core/indexes/category.py、pandas/core/indexes/interval.py、pandas/core/indexes/multi.py、pandas/core/indexes/datetimes.py、pandas/core/indexes/timedeltas.py、pandas/core/indexes/period.py索引对象如何被 Series/DataFrame 使用可对照 pandas/core/series.py 与 pandas/core/frame.py 中的.index相关入口继续阅读。本文以当前仓库中的 API 参考文档为骨架结合源码验证各方法的签名与语义示例代码基于仓库所示签名整理实际使用前请以仓库内对应版本的 docstring 为准。【免费下载链接】pandasFlexible and powerful data analysis / manipulation library for Python, providing labeled data structures similar to R data.frame objects, statistical functions, and much more项目地址: https://gitcode.com/gh_mirrors/pa/pandas创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考