mars.dataframe.read_csv#

mars.dataframe.read_csv(path, names=None, sep: 字符串 = ',', index_col=None, compression=None, header='infer', dtype=None, usecols=None, nrows=None, chunk_bytes='64M', gpu=None, head_bytes='100k', head_lines=None, incremental_index: 布尔型 = True, use_arrow_dtype: 可选[布尔型] = None, storage_options: 可选[字典] = None, memory_scale: 可选[整型] = None, merge_small_files: 布尔型 = True, merge_small_file_options: 可选[字典] = None, **kwargs)[来源]#

将逗号分隔值（csv）文件读取到DataFrame中。 还支持选择性地对文件进行迭代或分块。

Parameters

  • path (str) – 任何有效的字符串路径都是可以接受的。该字符串可以是一个URL。有效的URL协议包括http、ftp、s3和file。对于文件URL，期望有一个主机。一个本地文件可以是：file://localhost/path/to/table.csv，你也可以使用类似于以下的URL从外部资源读取： hdfs://localhost:8020/test.csv。 如果你想传入一个路径对象，pandas接受任何os.PathLike。 通过类文件对象，我们指的是具有read()方法的对象，例如文件处理器（例如通过内置的open函数）或StringIO。

  • sep (str, default ',') – 使用的分隔符。如果 sep 为 None，C 引擎无法自动检测分隔符，但 Python 解析引擎可以，这意味着后者将被使用，并通过 Python 内置的嗅探工具 csv.Sniffer 自动检测分隔符。此外，长度超过 1 个字符且不同于 '\s+' 的分隔符将被解释为正则表达式，也将强制使用 Python 解析引擎。请注意，正则表达式分隔符容易忽略引号内的数据。正则表达式示例： '\r\t'。

  • delimiter（字符串，默认 None）– sep 的别名。

  • header (int, list of int, 默认 'infer') – 用作列名的行号，以及数据的开始。默认情况下会推断列名：如果没有传递名字，行为与 header=0 相同，列名从文件的第一行推断，如果明确传递列名，则行为与 header=None 相同。明确传递 header=0 以便可以替换现有名称。Header 可以是一个整数列表，指定多级索引的列的行位置，例如 [0,1,3]。未指定的中间行将被跳过（例如，在这个例子中，2 会被跳过）。请注意，如果 skip_blank_lines=True，该参数会忽略注释行和空行，因此 header=0 表示数据的第一行，而不是文件的第一行。

  • names (类似数组, 可选) – 要使用的列名列表。如果文件包含标题行， 那么您应该明确传递 header=0 来覆盖列名。 此列表中不允许重复。

  • index_col (int, str, 整数/字符串序列或 False，默认 None) – 用作 DataFrame 行标签的列，可以作为字符串名称或列索引给出。如果给出一个整数/字符串序列，将使用 MultiIndex。注意：index_col=False 可以强制 pandas 不 将第一列作为索引，例如，当你有一个在每行末尾有分隔符的格式错误的文件时。

  • usecols (类似列表 或 可调用对象, 可选) – 返回列的一个子集。如果是类似列表的，所有元素必须是位置性的（即文档列的整数索引）或者是对应用户在 names 中提供的列名的字符串，或者是从文档头行推导出来的。例如，一个有效的类似列表的 usecols 参数可以是 [0, 1, 2] 或 ['foo', 'bar', 'baz']。元素顺序会被忽略，因此 usecols=[0, 1] 和 [1, 0] 是相同的。如果要从 data 实例化一个保持元素顺序的 DataFrame，请使用 pd.read_csv(data, usecols=['foo', 'bar'])[['foo', 'bar']] 来按 ['foo', 'bar'] 的顺序获取列，或 pd.read_csv(data, usecols=['foo', 'bar'])[['bar', 'foo']] 按 ['bar', 'foo'] 的顺序获取列。如果是可调用对象，将根据列名评估可调用函数，返回可调用函数评估为 True 的列名。一个有效的可调用参数的例子可以是 lambda x: x.upper() in ['AAA', 'BBB', 'DDD']。使用此参数会导致更快的解析时间和更低的内存使用。

  • squeeze (bool, default False) – 如果解析的数据只包含一列，则返回一个序列。

  • prefix (str, optional) – 当没有表头时，添加到列号的前缀，例如‘X’表示X0, X1, …

  • mangle_dupe_cols (bool, default True) – 重复的列将被指定为‘X’，‘X.1’，…’X.N’，而不是 ‘X’…’X’。如果传入 False，如果列中有重复的名称，则数据将被覆盖。

  • dtype (类型名 或 字典 of 列 -> 类型, 可选) – 数据或列的数据类型。例如 {‘a’: np.float64, ‘b’: np.int32, ‘c’: ‘Int64’} 使用 str 或 object 以及合适的 na_values 设置 以保留而不解读 dtype。 如果指定了转换器，它们将应用于而不是 dtype 转换。

  • engine ({'c', 'python'}, 可选) – 使用的解析器引擎。C引擎更快，而python引擎目前功能更完整。

  • 转换器 (字典, 可选) – 用于转换某些列中值的函数的字典。键可以是整数或列标签。

  • true_values (list, 可选) – 视为真值的值。

  • false_values (list, optional) – 被视为假值的值。

  • skipinitialspace (bool, 默认值为 False) – 在分隔符后跳过空格。

  • skiprows (列表类型, 整数 或 可调用的, 可选) – 要跳过的行号（0索引）或要跳过的行数（整数） 在文件开始时。 如果是可调用的，则可调用函数将对行 索引进行评估，如果该行应被跳过则返回 True，否则返回 False。 有效的可调用参数的一个例子是 lambda x: x in [0, 2]。

  • skipfooter (int, default 0) – 文件底部要跳过的行数（在 engine=’c’ 时不支持）。

  • nrows (int, 可选) – 要读取的文件行数。对于读取大型文件的部分非常有用。

  • na_values (标量, 字符串, 类似列表, 或 字典, 可选) – 额外的字符串被识别为 NA/NaN。如果传入字典，则每列的特定 NA 值。默认情况下，以下值被解释为 NaN: ‘’, ‘#N/A’, ‘#N/A N/A’, ‘#NA’, ‘-1.#IND’, ‘-1.#QNAN’, ‘-NaN’, ‘-nan’, ‘1.#IND’, ‘1.#QNAN’, ‘’, ‘N/A’, ‘NA’, ‘NULL’, ‘NaN’, ‘n/a’, ‘nan’, ‘null’.

  • keep_default_na (bool, 默认值为 True) –

    解析数据时是否包含默认的 NaN 值。 根据是否传入 na_values，行为如下： * 如果 keep_default_na 为 True，并且指定了 na_values，则 na_values

    会被附加到用于解析的默认 NaN 值中。

    • 如果 keep_default_na 为 True，并且未指定 na_values，则仅使用默认的 NaN 值进行解析。

    • 如果 keep_default_na 为 False，并且指定了 na_values，则仅使用指定的 NaN 值 na_values 进行解析。

    • 如果 keep_default_na 为 False，并且未指定 na_values，则没有字符串会被解析为 NaN。

    注意，如果 na_filter 被传入为 False，则 keep_default_na 和 na_values 参数将被忽略。

  • na_filter (bool, default True) – 检测缺失值标记（空字符串和na_values的值）。在没有任何NA的数据中，传递na_filter=False可以提高读取大文件的性能。

  • verbose (bool, 默认值为 False) – 指示放置在非数字列中的 NA 值的数量。

  • skip_blank_lines (bool, default True) – 如果为真，则跳过空行，而不是将其解释为NaN值。

  • parse_dates (布尔值 或 整数列表 或 名称 或 列表 的 列表 或 字典, 默认为 False) –

    行为如下： * 布尔值。如果为 True -> 尝试解析索引。 * 整数或名称的列表。例如。如果是 [1, 2, 3] -> 尝试解析列 1、2、3

    每个作为一个单独的日期列。

    • 列表的列表。例如。如果是 [[1, 3]] -> 合并列 1 和 3，并解析为单个日期列。

    • 字典，例如 {‘foo’ : [1, 3]} -> 将列 1、3 解析为日期，并将结果称为 ‘foo’

    如果某一列或索引无法表示为日期时间数组， 例如由于无法解析的值或时区混合，则该列 或索引将以对象数据类型不变的形式返回。对于 非标准的日期时间解析，请在 pd.read_csv 之后使用 pd.to_datetime。要解析具有时区混合的索引或列， 请指定 date_parser 为一个部分应用的 pandas.to_datetime()，并设置 utc=True。请参见 解析具有混合时区的 CSV 获取更多信息。 注意：iso8601 格式的日期有一个快速路径。

  • infer_datetime_format (bool, default False) – 如果为True并且 parse_dates 被启用，pandas将尝试推断列中日期时间字符串的格式，如果可以推断，将切换到更快的解析方法。在某些情况下，这可以将解析速度提高5-10倍。

  • keep_date_col (bool, 默认值 False) – 如果为 True，并且 parse_dates 指定了组合多个列，则保留原始列。

  • date_parser (函数, 可选) – 用于将一系列字符串列转换为日期时间实例数组的函数。默认情况下使用 dateutil.parser.parser 来进行转换。Pandas 将尝试以三种不同的方式调用 date_parser，如果发生异常则继续下一个方式：1) 将一个或多个数组（由 parse_dates 定义）作为参数传递；2) 将由 parse_dates 定义的列中的字符串值按行连接成一个单一数组并传递；3) 使用一个或多个字符串（对应于 parse_dates 定义的列）作为参数，对每一行调用 date_parser 一次。

  • dayfirst (bool, 默认值为 False) – DD/MM 格式日期，国际和欧洲格式。

  • cache_dates (bool, 默认值为 True) – 如果为 True，则使用唯一的、转换过的日期缓存来应用日期时间转换。当解析重复的日期字符串（特别是带有时区偏移的字符串）时，可能会显著提高速度。 .. versionadded:: 0.25.0

  • iterator (bool, 默认值为 False) – 返回用于迭代或获取块的 TextFileReader 对象，使用 get_chunk()。

  • chunksize (int, 可选) – 返回用于迭代的 TextFileReader 对象。 有关 iterator 和 chunksize 的更多信息，请参阅 IO Tools 文档。

  • compression ({'infer', 'gzip', 'bz2', 'zip', 'xz', None}, default 'infer') – 用于对磁盘数据进行即时解压缩。如果为‘infer’且filepath_or_buffer为路径样式，那么从以下扩展名中检测压缩格式：‘.gz’，‘.bz2’，‘.zip’或‘.xz’（否则不进行解压缩）。如果使用‘zip’，ZIP 文件必须只包含一个可读取的数据文件。设置为 None 以不进行解压缩。

  • thousands (str, 可选) – 千位分隔符。

  • decimal (str, default '.') – 用于识别小数点的字符（例如，对于欧洲数据使用‘,’）。

  • lineterminator (str (length 1), optional) – 用于将文件分成行的字符。仅适用于 C 解析器。

  • quotechar (str (length 1), optional) – 用于表示引号项的开始和结束的字符。引号项可以包含分隔符，并且它会被忽略。

  • 引用 (整数 或 csv.QUOTE_* 实例, 默认值 0) – 控制每个 csv.QUOTE_* 常量的字段引用行为。使用其中之一 QUOTE_MINIMAL (0), QUOTE_ALL (1), QUOTE_NONNUMERIC (2) 或 QUOTE_NONE (3)。

  • doublequote (bool, 默认 True) – 当指定了quotechar并且引用不是 QUOTE_NONE 时，指示是否将字段内部的两个连续的quotechar元素视为一个 quotechar 元素。

  • escapechar (str (长度 1), 可选) – 用于转义其他字符的单字符字符串。

  • comment (str, optional) – 表示行的其余部分不应被解析。如果在行的开头发现，它将被完全忽略。该参数必须是一个单字符。像空行一样（只要 skip_blank_lines=True），完全注释的行会被参数 header 忽略，但不会被 skiprows 忽略。例如，如果 comment='#'，使用 header=0 解析 #empty\na,b,c\n1,2,3 将导致 ‘a,b,c’ 被视为标题。

  • encoding (str, 可选) – 读取/写入时使用的UTF编码（例如‘utf-8’）。 Python标准编码列表。

  • 方言 (str 或 csv.Dialect, 可选) – 如果提供，此参数将覆盖以下参数的值（默认为或不为）： 分隔符、双引号、转义字符、跳过初始空格、引用字符 和 引用。如果需要覆盖值，将发出ParserWarning。有关更多详细信息，请参见csv.Dialect文档。

  • error_bad_lines (bool, default True) – 行中字段太多（例如，一个 csv 行中有太多逗号）默认会导致异常被抛出，并且不会返回 DataFrame。如果为 False，这些“坏行”将从返回的 DataFrame 中删除。

  • warn_bad_lines (bool, default True) – 如果 error_bad_lines 为 False，并且 warn_bad_lines 为 True，将会输出每一条“错误行”的警告。

  • delim_whitespace (bool, 默认值是 False) – 指定是否使用空白字符（例如 ' ' 或 '    '）作为分隔符。相当于设置 sep='\s+'。如果此选项设置为 True，则不应在 delimiter 参数中传入任何值。

  • low_memory (bool, 默认 True) – 在内部以块的方式处理文件，从而减少解析时的内存使用，但可能会出现混合类型推断。要确保没有混合类型，可以将其设置为 False，或使用 dtype 参数指定类型。请注意，无论如何，整个文件都会读入到一个单一的 DataFrame 中，使用 chunksize 或 iterator 参数可以分块返回数据。（仅适用于 C 解析器）。

  • float_precision (str, 可选) – 指定 C 引擎应使用哪个转换器来处理浮点值。选项有 None 用于普通转换器，high 用于高精度转换器，以及 round_trip 用于往返转换器。

  • chunk_bytes (int, float 或者 str, 可选) – 块字节数。

  • gpu (bool, 默认值 False) – 如果读取到 cudf DataFrame 中。

  • head_bytes (int, float 或 str, 可选) – 用于文件头的字节数，主要用于数据推断。

  • head_lines (int, optional) – 文件头部使用的行数，主要用于数据推断。

  • incremental_index (bool, 默认 True) – 如果没有指定 index_col，确保范围索引递增，如果设置为 False，将获得稍微更好的性能。

  • use_arrow_dtype (bool, default None) – 如果为True，使用arrow数据类型来存储列。

  • storage_options (dict, optional) – 存储连接的选项。

  • merge_small_files (bool, 默认为 True) – 合并小文件，文件大小较小。

  • merge_small_file_options (dict) – 合并小文件的选项

Returns

返回一个以逗号分隔的值（csv）文件，作为具有标签轴的二维数据结构。

Return type

数据框

另请参阅

to_csv

将数据框写入逗号分隔值（csv）文件。

示例

>>> import mars.dataframe as md
>>> from mars.lib.filesystem.oss import build_oss_path
>>> md.read_csv('data.csv')  
>>> # read from HDFS
>>> md.read_csv('hdfs://localhost:8020/test.csv')  
>>> # read from OSS
>>> auth_path = build_oss_path(file_path, access_key_id, access_key_secret, end_point)
>>> md.read_csv(auth_path)