pandas.read_csv 詳細介紹

pandas.read_csv 介面用於讀取 CSV 格式數據檔案，由於它使用非常頻繁，功能強大參數衆多，所以在這裏專門做詳細介紹，我們在使用過程中可以查閱。

讀 Excel 檔案等方法會有很多相同的參數，用法基本一致。

語法

它的語法如下：

pd.read_csv(filepath_or_buffer: Union[str, pathlib.Path, IO[~AnyStr]],
sep=',', delimiter=None, header='infer', names=None, index_col=None,
usecols=None, squeeze=False, prefix=None, mangle_dupe_cols=True,
dtype=None, engine=None, converters=None, true_values=None,
false_values=None, skipinitialspace=False, skiprows=None,
skipfooter=0, nrows=None, na_values=None, keep_default_na=True,
na_filter=True, verbose=False, skip_blank_lines=True,
parse_dates=False, infer_datetime_format=False,
keep_date_col=False, date_parser=None, dayfirst=False,
cache_dates=True, iterator=False, chunksize=None,
compression='infer', thousands=None, decimal: str = '.',
lineterminator=None, quotechar='"', quoting=0,
doublequote=True, escapechar=None, comment=None,
encoding=None, dialect=None, error_bad_lines=True,
warn_bad_lines=True, delim_whitespace=False,
low_memory=True, memory_map=False, float_precision=None)

參數

檔案 filepath_or_buffer

這是一個預設參數據，沒有參數名，不能爲空。

可以傳檔案路徑:

# filepath_or_bufferstr, path object or file-like object
# 本地相對路徑：
pd.read_csv('data/data.csv') # 注意目錄層級
pd.read_csv('data.csv') # 如果檔案與程式碼檔案在同目錄下
pd.read_csv('data/my/my.data') # CSV 副檔名不一定是 csv
# 本地絕對路徑：
pd.read_csv('/user/gairuo/data/data.csv')
# 使用網址 url
pd.read_csv('https://www.gairuo.com/file/data/dataset/GDP-China.csv')

需要注意的是，mac 和 windows 的路徑寫法不一樣，上例是 mac 寫法，windows 需要換成類似 data\data.csv 及 'E: \data\data.csv'

可以傳數據字串，即 csv 中的數據字元，以字串直接傳入

from io import StringIO
data = ('col1,col2,col3\n'
        'a,b,1\n'
        'a,b,2\n'
        'c,d,3')

pd.read_csv(StringIO(data))

StringIO

from io import StringIO
pd.read_csv(StringIO(data), dtype=object)

也可以傳入位元組數據：

from io import BytesIO
data = (b'word,length\n'
        b'Tr\xc3\xa4umen,7\n'
        b'Gr\xc3\xbc\xc3\x9fe,5')
pd.read_csv(BytesIO(data))

注：位元組數據經常會放在緩衝中來傳遞。

buf = BytesIO()
# buf 可認爲一個儲存位置來使用
buf.getbuffer()

也可以用 read() 開啓的檔案再傳遞，不過幾乎沒人這麼做。

分隔符 sep

字元型，每行數據內容分隔符號，預設是 , 逗號，另外常見的還有 tab 符 \t，空格等，根據數據實際的情況傳值。

# str, default ‘,’
# 數據分隔轉化是逗號, 如果是其他可以指定
pd.read_csv(data, sep='\t') # 製表符分隔 tab
pd.read_table(data) # read_table 預設是製表符分隔 tab
pd.read_csv(data, sep='|') # 製表符分隔 tab
pd.read_csv(data,sep="(?<!a)\|(?!1)", engine='python') # 使用正則

分隔符 delimiter

str, default None

定界符，備選分隔符，sep 的別名，效果和它一樣。如果指定該參數，則sep參數失效。

支援 int, list of int，第幾行是表頭，預設會自動推斷，會把第一行作爲表頭。

# int, list of int, default ‘infer’
# 預設系統會推斷，如果指定列名會被忽略
pd.read_csv(data, header=0) # 第一行
pd.read_csv(data, header=None) # 沒有表頭
pd.read_csv(data, header=[0,1,3]) # 多層索引 MultiIndex

注意：如果 skip_blank_lines=True，header 參數將忽略空行和註釋行, 因此 header=0 表示第一行數據而非檔案的第一行.

列名 names

如果檔案不包含列名，那麼應該設定 header=None，列名列表中不允許有重複值。

# array-like, optional
pd.read_csv(data, names=['列1', '列2']) # 指定列名列表

索引列 index_col

用作行索引的列編號或者列名，如果給定一個序列則有多個行索引。如果檔案不規則，行尾有分隔符，則可以設定index_col=False 來是的pandas不適用第一列作爲行索引。

# int, str, sequence of int / str, or False, default None
# 預設爲 `None`, 不自動識別索引
pd.read_csv(data, index_col=False) # 不再使用首列作爲索引
pd.read_csv(data, index_col=0) # 第幾列是索引
pd.read_csv(data, index_col='年份') # 指定列名
pd.read_csv(data, index_col=['a','b']) # 多個索引
pd.read_csv(data, index_col=[0, 3]) # 按列索引指定多個索引

使用部分列 usecols

選取部分列，使用這個參數可以加快載入速度並降低記憶體消耗。

# list-like or callable, optional
# 讀取部分列
pd.read_csv(data, usecols=[0,4,3]) # 按索引只讀取指定列，順序無關
pd.read_csv(data, usecols=['列1', '列5']) # 按列名，列名必須存在
# 指定列順序，其實是 df 的篩選功能
pd.read_csv(data, usecols=['列1', '列5'])[['列5', '列1']]
# 以下用 callable 方式可以巧妙指定順序, in 後邊的是我們要的順序
pd.read_csv(data, usecols=lambda x: x.upper() in ['COL3', 'COL1'])

返回序列 squeeze

如果檔案值包含一列，則返回一個 Series，如果多個列無論如何還是 DataFrame。

# bool, default False
# 下例只取一個列會返回一個 Series
pd.read_csv(data, usecols=[0], squeeze=True)
# 有兩列則還是 df
pd.read_csv(data, usecols=[0, 2], squeeze=True)

表頭字首 prefix

如沒列名，自動指定一個字首下劃線線序數的名稱，如 n0、n1。

# str, optional
# 表頭爲 c_0、c_2
pd.read_csv(data, prefix='c_', header=None)

處理重複列名 mangle_dupe_cols

當列名有重複時，解析列名將變爲 ‘X’, ‘X.1’…’X.N’而不是 ‘X’…’X’。如果該參數爲 False ，那麼當列名中有重複時，前列將會被後列覆蓋。

# bool, default True
data = 'a,b,a\n0,1,2\n3,4,5'
pd.read_csv(StringIO(data), mangle_dupe_cols=True)
# 表頭爲 a b a.1
# False 會報 ValueError 錯誤

數據型別 dtype

pandas 的數據型別可參考 dtypes。

# Type name or dict of column -> type, optional
pd.read_csv(data, dtype=np.float64) # 所有數據均爲此數據型別
pd.read_csv(data, dtype={'c1':np.float64, 'c2': str}) # 指定欄位的型別
pd.read_csv(data, dtype=[datetime, datetime, str, float]) # 依次指定

引擎 engine

使用的分析引擎，可以選擇C或者是python。C 語言速度最快，python 的功能最爲完善。

# engine=None, {'c', 'python'}, optional
pd.read_csv(data, engine='c')

列數據處理 converters

對列的數據進行轉換，列名與函陣列成的字典。key 可以是列名或者列的序號。

# dict, default None
data = 'x,y\na,1\nb,2'
def foo(p):
    return p+'s'
# x 應用函數, y 使用 lambda
pd.read_csv(StringIO(data), converters={'x': foo,
                                        'y': lambda x: x*3})
# 使用列索引
pd.read_csv(StringIO(data),
            converters={0: foo, 1: lambda x: x*3})

真值轉換 true_values

將指定的文字轉換爲 True, 可以用列表指定多個值。

# list, default None
data = ('a,b,c\n1,Yes,2\n3,No,4')
pd.read_csv(StringIO(data),
            true_values=['Yes'], false_values=['No'])

假值轉換 false_values

同上邊的 true_values

忽略分隔符後空白 skipinitialspace

忽略分隔符後的空白（預設爲False，即不忽略）。

# boolean, default False
data = 'a, b, c\n 1, 2, 3\n 4 ,5, 6'
pd.read_csv(StringIO(data), skipinitialspace=True)

跳過指定行 skiprows

需要忽略的行數（從檔案開始處算起），或需要跳過的行號列表（從0開始）。

# list-like, int or callable, optional
# 跳過前三行
pd.read_csv(data, skiprows=2)
# 跳過前三行
pd.read_csv(data, skiprows=range(2))
# 跳過指定行
pd.read_csv(data, skiprows=[24,234,141])
# 跳過指定行
pd.read_csv(data, skiprows=np.array([2, 6, 11]))
# 隔行跳過
pd.read_csv(data, skiprows=lambda x: x % 2 != 0)

尾部跳過 skipfooter

從檔案尾部開始忽略。 (c引擎不支援)

# int, default 0
pd.read_csv(filename, skipfooter=1) # 最後一行不載入

讀取行數 nrows

需要讀取的行數，從檔案開關算起，經常用於較大的數據，先取部分進行程式碼編寫。

# int, default None
pd.read_csv(data, nrows=1000)

空值替換 na_values

一組用於替換 NA/NaN 的值。如果傳參，需要制定特定列的空值。這些值爲認爲是空值 NaN：['-1.#IND', '1.#QNAN', '1.#IND', '-1.#QNAN', '#N/A N/A', '#N/A', 'N/A', 'n/a', 'NA', '#NA', 'NULL', 'null', 'NaN', '-NaN', 'nan', '-nan', '']

na_values 的使用需要關注下下邊 keep_default_na 的配合使用和影響。

# scalar, str, list-like, or dict, default None
# 5 和 5.0 會被認爲 NaN
pd.read_csv(data, na_values=[5])
# ? 會被認爲 NaN
pd.read_csv(data, na_values='?')
# 空值爲 NaN
pd.read_csv(data, keep_default_na=False, na_values=[""])
# 字元 NA 字元 0 會被認爲 NaN
pd.read_csv(data, keep_default_na=False, na_values=["NA", "0"])
# Nope 會被認爲 NaN
pd.read_csv(data, na_values=["Nope"])
# a、b、c 均會被認爲 NaN 等於 na_values=['a','b','c']
pd.read_csv(data, na_values='abc')
# 指定列的指定值會被認爲 NaN
pd.read_csv(data, na_values={'c':3, 1:[2,5]})

保留預設空值 keep_default_na

分析數據時是否包含預設的NaN值，是否自動識別。如果指定 na_values 參數，並且 keep_default_na=False，那麼預設的NaN將被覆蓋，否則新增。

和 na_values 的關係是：

keep_default_na	na_values	邏輯
True	指定	na_values 的設定附加處理
True	未指定	自動識別
False	指定	使用 na_values 的設定
False	未指定	不做處理

注：如果 na_filter 爲 False （預設是 True）, 那麼 keep_default_na 和 na_values parameters 均無效。

# boolean, default True
# 不自動識別空值
pd.read_csv(data, keep_default_na=False)

丟失值檢查 na_filter

是否檢查丟失值（空字串或者是空值）。對於大檔案來說數據集中沒有空值，設定na_filter=False 可以提升讀取速度。

# boolean, default True
pd.read_csv(data, na_filter=False) # 不檢查

解析資訊 verbose

是否列印各種解析器的輸出資訊，例如：「非數值列中缺失值的數量」等。

# boolean, default False
# 可以看到解析資訊
pd.read_csv(data, verbose=True)
# Tokenization took: 0.02 ms
# Type conversion took: 0.36 ms
# Parser memory cleanup took: 0.01 ms

跳過空行 skip_blank_lines

是否跳過空行，如果爲 True，則跳過空行，否則數據記爲 NaN。

# boolean, default True
# 不跳過空行
pd.read_csv(data, skip_blank_lines=False)

注意：如果 skip_blank_lines=True，header 參數將忽略空行和註釋行, 因此 header=0 表示第一行數據而非檔案的第一行.

日期時間解析 parse_dates

本參數對時間日期進行解析。

# boolean or list of ints or names or list of lists or dict, default False.
pd.read_csv(data, parse_dates=True) # 自動解析日期時間格式
pd.read_csv(data, parse_dates=['年份']) # 指定日期時間欄位進行解析
# 將 1、4 列合併解析成名爲 時間的 時間型別列
pd.read_csv(data, parse_dates={'時間':[1,4]})

自動識別日期時間 infer_datetime_format

如果設定爲True並且parse_dates 可用，那麼pandas將嘗試轉換爲日期型別，如果可以轉換，轉換方法並解析。在某些情況下會快5~10倍。

# boolean, default False
pd.read_csv(data, parse_dates=True, infer_datetime_format=True)

保留被組合時間列 keep_date_col

如果有多列解析成一個列，自動會合併到新解析的列，去掉此列，如果設定爲 True 則會保留。

# boolean, default False
pd.read_csv(data, parse_dates=[[1, 2], [1, 3]], keep_date_col=True)

日期時間解析器 date_parser

用於解析日期的函數，預設使用dateutil.parser.parser來做轉換。Pandas 嘗試使用三種不同的方式解析，如果遇到問題則使用下一種方式。

使用一個或者多個arrays（由parse_dates指定）作爲參數；
連線指定多列字串作爲一個列作爲參數；
每行呼叫一次date_parser函數來解析一個或者多個字串（由parse_dates指定）作爲參數。

# function, default None
# 指定時間解析庫，預設是 dateutil.parser.parser
date_parser=pd.io.date_converters.parse_date_time
date_parser=lambda x: pd.to_datetime(x, utc=True, format='%d%b%Y')
date_parser = lambda d: pd.datetime.strptime(d, '%d%b%Y')
# 使用
pd.read_csv(data, parse_dates=['年份'], date_parser=date_parser)

日期日在前 dayfirst

DD/MM格式的日期型別，如日期 2000-01-06 如果 dayfirst=True 則會轉換成 2000-06-01。

# boolean, default False
pd.read_csv(data, dayfirst=True, parse_dates=[0])

cache_dates

如果爲 True，則使用唯一的轉換日期快取來應用 datetime 轉換。解析重複的日期字串時，尤其是帶有時區偏移的日期字串時，可能會大大提高速度。

# boolean, default True
pd.read_csv(data, cache_dates=False)

讀檔案物件 iterator

返回一個TextFileReader 物件，以便逐塊處理檔案。

# boolean, default False
pd.read_csv(data, iterator=True)

檔案塊 chunksize

檔案塊的大小，分塊處理大型csv檔案。

# int, default None
pd.read_csv(data, chunksize=100000)

# 分片處理大檔案
df_iterator=pd.read_csv(file,chunksize=50000)
def process_dataframe(df):
    pass
    return processed_df

for index,df_tmp in enumerate(df_iterator):
    df_processed=process_dataframe(df_tmp)
    if index>0:
       df_processed.to_csv(path)
    else:
       df_processed.to_csv(path,mode='a',header=False)

壓縮 compression

用於對磁碟數據進行即時解壓縮。如果爲「推斷 infer」，則如果filepath_or_buffer是分別以「 .gz」，「。bz2」，「。zip」或「 .xz」結尾的字串，則使用gzip，bz2，zip或xz，否則不進行解壓縮。如果使用「 zip」，則ZIP檔案必須僅包含一個要讀取的數據檔案。設定爲「None」將不進行解壓縮。

# {'infer', 'gzip', 'bz2', 'zip', 'xz', None}, default 'infer'
pd.read_csv('sample.tar.gz', compression='gzip')

千分位分割符 thousands

千位分隔符。

# str, default None
pd.read_csv('test.csv', thousands=',') # 逗號分隔

小數點 decimal

識別字元的小數點。例如。對於歐洲數據，請使用「，」。

# str, default '.'
pd.read_csv(data, decimal=",")

行結束符 lineterminator

行結束符，將檔案分成幾行的字元。僅對C解析器有效。

# str (length 1), default None
data = 'a,b,c~1,2,3~4,5,6'
pd.read_csv(StringIO(data), lineterminator='~')

引號 quotechar

用於表示參照數據的開始和結束的字元。參照的專案可以包含定界符，它將被忽略。

# str (length 1)
pd.read_csv(file, quotechar = '"')

引號常數 quoting

控制csv中的引號常數。每個csv.QUOTE_ *常數的控制欄位參照行爲。使用QUOTE_MINIMAL（0），QUOTE_ALL（1），QUOTE_NONNUMERIC（2）或QUOTE_NONE（3）中的一種。

# int or csv.QUOTE_* instance, default 0
import csv
pd.read_csv('input_file.csv', quoting=csv.QUOTE_NONE)

雙引號 doublequote

雙引號，當單引號已經被定義，並且quoting 參數不是QUOTE_NONE的時候，使用雙引號表示引號內的元素作爲一個元素使用。

# boolean, default True
import csv
pd.read_csv('data.csv', quotechar='"', doublequote=True, quoting=csv.QUOTE_NONNUMERIC)

不受分隔符限值 escapechar

當quoting 爲QUOTE_NONE時，指定一個字元使的不受分隔符限值。

# str (length 1), default None
pd.read_csv(StringIO(data), escapechar='\\', encoding='utf-8')

註釋標識 comment

指示不應分析行的部分。如果在一行的開頭找到該行，則將完全忽略該行。此參數必須是單個字元。像空行一樣（只要skip_blank_lines = True），參數視爲header會忽略完全註釋的行，而skiprows 行會忽略。例如，如果comment ='＃'，則解析header= 0的'#empty \ na，b，c \ n1,2,3'會將'a，b，c'視爲header。

# str, default None
s = '# notes\na,b,c\n# more notes\n1,2,3'
pd.read_csv(StringIO(s), sep=',', comment='#', skiprows=1)

編碼 encoding

指定字元集型別，通常指定爲'utf-8'。參見 Python標準編碼列表。

# str, default None
pd.read_csv('gairuo.csv', encoding='utf8')
pd.read_csv("gairuo.csv",encoding="gb2312") # 常見中文

dialect

如果提供，則此參數將覆蓋以下參數的值（預設值或未設定）：delimiter, doublequote, escapechar, skipinitialspace, quotechar 和 quoting。如果有必要覆蓋值，則將發出 ParserWarning。有關更多詳細資訊，請參見 csv.Dialect文件。

# str or csv.Dialect instance, default None
import csv
csv.register_dialect(
    'mydialect',
    delimiter = ',',
    quotechar = '"',
    doublequote = True,
    skipinitialspace = True,
    lineterminator = '\r\n',
    quoting = csv.QUOTE_MINIMAL)

pd.read_csv("gr.csv", encoding="gbk", dialect='mydialect')

壞行處理 error_bad_lines

預設情況下，欄位太多的行（例如，帶有太多逗號的csv行）會引發異常，並且不會返回任何DataFrame。如果爲False，則這些「壞行」將從返回的DataFrame中刪除。請參閱下面下麪的壞行。

# boolean, default True
pd.read_csv(StringIO(data), error_bad_lines=False)

壞行警告 warn_bad_lines

如果error_bad_lines爲False，而warn_bad_lines爲True，則將爲每個「壞行」輸出警告。

# boolean, default True
pd.read_csv(StringIO(data), warn_bad_lines=False)

空格分隔符 delim_whitespace

指定是否將空格（例如''或'\ t'）用作分隔符。等效於設定sep ='\s+'。如果此選項設定爲True，則不應該爲delimiter參數傳遞任何內容。

# boolean, default False
pd.read_csv(StringIO(data), delim_whitespace=False)

低記憶體 low_memory

在內部對檔案進行分塊處理，從而在解析時減少了記憶體使用，但可能是混合型別推斷。要確保沒有混合型別，請設定False或使用dtype參數指定型別。請注意，無論使用chunksize還是iterator參數以塊形式返回數據，整個檔案都將被讀取到單個DataFrame中。（僅對C解析器有效）

# boolean, default True
pd.read_csv(StringIO(data), low_memory=False)

記憶體對映 memory_map

如果爲filepath_or_buffer提供了檔案路徑，則將檔案物件直接對映到記憶體中並直接從那裏存取數據。使用此選項可以提高效能，因爲不再有任何I / O開銷。

# boolean, default False
pd.read_csv('gr.csv', low_memory=False)

高精度轉換 float_precision

指定C引擎應將哪個轉換器用於浮點值。對於普通轉換器，選項爲None；對於高精度轉換器，選項爲high；對於往返轉換器，選項爲round_trip。

# string, default None
val = '0.3066101993807095471566981359501369297504425048828125'
data = 'a,b,c\n1,2,{0}'.format(val)
abs(pd.read_csv(StringIO(data), engine='c',float_precision='high')['c'][0] - float(val))

一般情況下，會將讀取到的數據返回一個 DataFrame，當然按照參數的要求會返回指定的型別。