【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() 是非常简洁高效的选择。