【Pandas】pandas DataFrame first_valid_index
Pandas2.2 DataFrame
Time Series-related
| 方法 | 描述 |
|---|---|
| DataFrame.asfreq(freq[, method, how, …]) | 用于**将时间序列数据转换为指定频率（resample to frequency）**的方法 |
| DataFrame.asof(where[, subset]) | 用于查找时间序列中最接近指定时间点的非 NaN 值的方法 |
| DataFrame.shift([periods, freq, axis, …]) | 用于**将 DataFrame 的数据沿着指定轴移动（平移）**的方法 |
| DataFrame.first_valid_index() | 用于获取 DataFrame 中第一个非空（非 NaN）值所在的行索引的方法 |
pandas.DataFrame.first_valid_index()
pandas.DataFrame.first_valid_index() 是一个用于获取 DataFrame 中第一个非空（非 NaN）值所在的行索引的方法。它常用于时间序列或一般数据中，查找第一个有效观测值的位置。
📌 方法签名
DataFrame.first_valid_index()
🔧 参数说明：
- 无参数。
✅ 返回值
- 返回一个标量值，表示第一个非空值所在的行索引；
- 如果整个 DataFrame 都是
NaN，则返回None。
🧪 示例代码及结果
示例 1：基本用法
import pandas as pd
import numpy as npdf = pd.DataFrame({'A': [np.nan, np.nan, 3, 4, 5],'B': [np.nan, 2, np.nan, 4, 5],'C': [1, 2, 3, np.nan, np.nan]
})print("Original DataFrame:")
print(df)
输出：
A B C
0 NaN NaN 1.0
1 NaN 2.0 2.0
2 3.0 NaN 3.0
3 4.0 4.0 NaN
4 5.0 5.0 NaN
# 获取第一个非空值的索引
result = df.first_valid_index()
print("\nFirst valid index:", result)
输出：
First valid index: 0
解释：列
'C'的第一行（索引0）是第一个出现非空值的行。
示例 2：每列的第一个有效索引不同
df = pd.DataFrame({'A': [np.nan, np.nan, np.nan, 4, 5],'B': [np.nan, np.nan, 3, 4, 5],'C': [1, 2, 3, 4, 5]
})print("Original DataFrame:")
print(df)result = df.first_valid_index()
print("\nFirst valid index:", result)
输出：
A B C
0 NaN NaN 1
1 NaN NaN 2
2 NaN 3.0 3
3 4.0 4.0 4
4 5.0 5.0 5First valid index: 0
即使
'A'和'B'的第一个非空值出现在后面，但'C'在第一行就有有效值，因此整体返回索引0。
示例 3：所有值都是 NaN 的情况
df_all_nan = pd.DataFrame({'A': [np.nan, np.nan],'B': [np.nan, np.nan]
})result = df_all_nan.first_valid_index()
print("\nFirst valid index when all are NaN:", result)
输出：
First valid index when all are NaN: None
🧠 应用场景
| 场景 | 说明 |
|---|---|
| 时间序列分析 | 查找最早的有效观测时间点 |
| 数据清洗 | 定位数据起始位置，去除前面的空值 |
| 缺失值处理 | 确定从哪一行开始有有效数据 |
| 数据对齐 | 找出多个时间序列中最早的数据起点 |
| 特征工程 | 判断某个变量何时开始有记录 |
⚠️ 注意事项
- 返回的是行索引，不是具体的列名或位置；
- 只要某一行中任意一列有非空值，该行就被视为“有效”；
- 不会修改原始数据；
- 对于时间序列数据，返回的时间索引可以直接用于切片或筛选。
✅ 总结对比
| 方法 | 是否返回索引 | 是否考虑整行有效 | 是否支持时间索引 |
|---|---|---|---|
.first_valid_index() | ✅ | ❌（只要有一列非空即可） | ✅ |
.notna().idxmax() | ✅ | ✅（可按列使用） | ✅ |
.dropna().index[0] | ✅ | ✅（整行非空） | ✅ |
如果你希望快速定位 DataFrame 中最早出现有效数据的行索引，.first_valid_index() 是非常简洁高效的选择。