pandas.read_csv 详细介绍

深藏阁楼爱情的钟 2023-09-23 12:57 31阅读 0赞

《Pandas 教程》 修订中，可作为 Pandas 入门进阶课程、Pandas 中文手册、用法大全，配有案例讲解和速查手册。提供建议、纠错、催更等加作者微信: sinbam 和关注公众号「盖若」ID: gairuo。查看更新日志。

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')
    #  Amazon S3, 安装支持库 fsspec
    pd.read_csv(
        "s3://ncei-wcsd-archive/data/processed/SH1305/18kHz/SaKe2013"
        "-D20130523-T080854_to_SaKe2013-D20130523-T085643.csv",
        storage_options={
        "anon": True},
    )

需要注意的是，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参数失效。

表头 header  
支持 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") # 常见中文
    # 其他常用编码 ISO-8859-1 latin-1 gbk

如果不知道文件是什么编码，可以借助 codecs 和 chardet 这两个三方库在检测文件的编码方式。

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”，原始低精度转换器的“legacy”，以及 round-trip 换器的“ 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))

存储选项 storage\_options  
注：pandas 1.2.0 新增。

fsspec 还允许使用复杂的URL，以访问压缩档案中的数据，文件的本地缓存等。 要在本地缓存上面的示例，可以增加参数配置：

#  Amazon S3, 安装支持库 fsspec
    pd.read_csv(
        "simplecache::s3://ncei-wcsd-archive/data/processed/SH1305/18kHz/"
        "SaKe2013-D20130523-T080854_to_SaKe2013-D20130523-T085643.csv",
        storage_options={
        "s3": {
        "anon": True}},
    )

在这里，我们指定“anon”参数用于实现的“ s3”部分，而不是用于缓存实现。 请注意，这仅在会话期间缓存到临时目录，但是您也可以指定永久存储。更多参数可参考fsspec文档

返回  
一般情况下，会将读取到的数据返回一个 DataFrame，当然按照参数的要求会返回指定的类型。