TabularDataset 类

表示要在 Azure 机器学习中使用的表格数据集。

TabularDataset 定义一系列延迟求值的不可变操作，用于将数据源中的数据加载到表格表示形式中。 在要求 TabularDataset 传送数据之前，不会从源加载数据。

TabularDataset 是使用 TabularDatasetFactory 类中的 from_delimited_files 之类的方法创建的。

有关详细信息，请参阅 添加 & 注册数据集一文。 若要开始使用表格数据集，请参阅 https://aka.ms/tabulardataset-samplenotebook。

初始化 TabularDataset 对象。

不应直接调用此构造函数。 数据集旨在使用 TabularDatasetFactory 类创建。

继承

AbstractDataset

TabularDataset

构造函数

TabularDataset()

注解

可以使用 TabularDatasetFactory 类的 from_* 方法，从 CSV、TSV、Parquet 文件或 SQL 查询创建 TabularDataset。 可以对 TabularDataset 执行创建子集操作，如拆分、跳过和筛选记录。 创建子集的结果始终是一个或多个新的 TabularDataset 对象。

还可以将 TabularDataset 转换为其他格式，如 pandas 数据帧。 当要求 TabularDataset 将数据传递到另一个存储机制（例如 Pandas 数据帧或 CSV 文件）时，将发生实际的数据加载。

TabularDataset 可用作试验运行的输入。 它还可以用指定名称注册到工作区，并在以后通过该名称进行检索。

方法

download	注意 这是一个实验性的方法，可能会在任何时候更改。 有关详细信息，请参阅 https://aka.ms/azuremlexperimental。 将数据集定义的文件流下载到本地路径。
drop_columns	从数据集中删除指定列。 如果删除了时序列，也会删除返回的数据集的相应功能。
filter	注意 这是一个实验性的方法，可能会在任何时候更改。 有关详细信息，请参阅 https://aka.ms/azuremlexperimental。 筛选数据，仅保留与指定表达式匹配的记录。
get_profile	注意 这是一个实验性的方法，可能会在任何时候更改。 有关详细信息，请参阅 https://aka.ms/azuremlexperimental。 从为工作区中的此数据集或相同数据集提交的最新配置文件运行中获取数据配置文件。
get_profile_runs	注意 这是一个实验性的方法，可能会在任何时候更改。 有关详细信息，请参阅 https://aka.ms/azuremlexperimental。 返回与工作区中的此数据集或相同数据集关联的以前的配置文件运行。
keep_columns	保留指定列并从数据集中删除所有其他列。 如果删除了时序列，也会删除返回的数据集的相应功能。
mount	注意 这是一个实验性的方法，可能会在任何时候更改。 有关详细信息，请参阅 https://aka.ms/azuremlexperimental。 创建一个上下文管理器，用于将数据集定义的文件系统流装载为本地文件。
partition_by	将复制分区的数据并输出到指定的目标。 从带分区格式的输出数据路径创建数据集，在提供名称的情况下注册数据集，并为带分区的新数据路径返回数据集 ds = Dataset.get_by_name('test') # indexed by country, state, partition_date # #1: call partition_by locally new_ds = ds.partition_by(name="repartitioned_ds", partition_keys=['country'], target=DataPath(datastore, "repartition")) partition_keys = newds.partition_keys # ['country'] # new_ds can be passed to PRS as input dataset
random_split	按指定百分比随机并大致地将数据集中的记录拆分为两个部分。 第一个数据集包含总记录的约 percentage，第二个数据集包含剩余记录。
skip	按指定的计数从数据集的顶部起跳过记录。
submit_profile_run	注意 这是一个实验性的方法，可能会在任何时候更改。 有关详细信息，请参阅 https://aka.ms/azuremlexperimental。 提交试验运行以计算数据配置文件。 数据配置文件提供有关数据的有用信息（如列类型、缺少值等），对理解输入数据，识别异常和缺少值非常有用。
take	按指定的计数从数据集的顶部起获取记录示例。
take_sample	按指定的概率大致获取数据集中记录的随机示例。
time_after	在指定的开始时间之后使用时间戳列筛选 TabularDataset。
time_before	在指定的结束时间之前使用时间戳列筛选 TabularDataset。
time_between	在指定开始时间和结束时间之间筛选 TabularDataset。
time_recent	筛选 TabularDataset，以仅包含指定持续时间（量）的最近数据。
to_csv_files	将当前数据集转换为包含 CSV 文件的 FileDataset。 生成的数据集将包含一个或多个 CSV 文件，每个文件对应于当前数据集中的一个数据分区。 在下载或读取这些文件之前，这些文件不会具体化。
to_dask_dataframe	注意 这是一个实验性的方法，可能会在任何时候更改。 有关详细信息，请参阅 https://aka.ms/azuremlexperimental。 返回一个可以延迟读取数据集中数据的 Dask 数据帧。
to_pandas_dataframe	将数据集中的所有记录加载到 pandas 数据帧。
to_parquet_files	将当前数据集转换为包含 Parquet 文件的 FileDataset。 生成的数据集将包含一个或多个 Parquet 文件，每个文件对应于当前数据集中的一个数据分区。 在下载或读取这些文件之前，这些文件不会具体化。
to_spark_dataframe	将数据集中的所有记录加载到 Spark 数据帧。
with_timestamp_columns	为数据集定义时间戳列。

download

注意

这是一个实验性的方法，可能会在任何时候更改。 有关详细信息，请参阅 https://aka.ms/azuremlexperimental。

将数据集定义的文件流下载到本地路径。

download(stream_column, target_path=None, overwrite=False, ignore_not_found=True)

参数

名称	说明
stream_column 必需	str 要下载的流列。
target_path 必需	str 要将文件下载到的本地目录。 如果为 None，则数据将下载到临时目录中。
overwrite 必需	bool 指示是否覆盖现有文件。 默认值为 False。 如果覆盖设置为 True，则覆盖现有文件；否则将引发异常。
ignore_not_found 必需	bool 指示当找不到由数据集指向的某些文件时是否使下载失败。 默认值为 True。 如果 ignore_not_found 设置为 False，则任何文件下载因任何原因失败，下载都将失败；否则，将记录未发现错误的警告，并且只要没有遇到其他错误类型，下载都将成功。

返回

类型	说明
ndarray	返回下载的每个文件的文件路径数组。

drop_columns

从数据集中删除指定列。

如果删除了时序列，也会删除返回的数据集的相应功能。

drop_columns(columns)

参数

名称	说明
columns 必需	Union[str, list[str]] 要删除的列的名称或名称列表。

返回

类型	说明
TabularDataset	返回已删除指定列的新 TabularDataset 对象。

filter

注意

这是一个实验性的方法，可能会在任何时候更改。 有关详细信息，请参阅 https://aka.ms/azuremlexperimental。

筛选数据，仅保留与指定表达式匹配的记录。

filter(expression)

参数

名称	说明
expression 必需	any 要计算的表达式。

返回

类型	说明
TabularDataset	已修改的数据集（未注册）。

注解

通过使用列的名称对数据集编制索引来启动表达式。 它们支持各种函数和运算符，可以使用逻辑运算符进行组合。 当数据提取时，将对每个记录进行惰性计算，而不会对其定义。

   dataset['myColumn'] > dataset['columnToCompareAgainst']
   dataset['myColumn'].starts_with('prefix')

get_profile

注意

这是一个实验性的方法，可能会在任何时候更改。 有关详细信息，请参阅 https://aka.ms/azuremlexperimental。

从为工作区中的此数据集或相同数据集提交的最新配置文件运行中获取数据配置文件。

get_profile(workspace=None)

参数

名称	说明
workspace 必需	Workspace 已提交配置文件运行的工作区。 默认为此数据集的工作区。 如果数据集不与工作区关联，则为必需。 有关工作区的详细信息，请参阅 https://docs.microsoft.com/en-us/python/api/azureml-core/azureml.core.workspace.workspace。

返回

类型	说明
DatasetProfile	来自 DatasetProfile 类型的最新配置文件运行的配置文件结果。

get_profile_runs

注意

这是一个实验性的方法，可能会在任何时候更改。 有关详细信息，请参阅 https://aka.ms/azuremlexperimental。

返回与工作区中的此数据集或相同数据集关联的以前的配置文件运行。

get_profile_runs(workspace=None)

参数

名称	说明
workspace 必需	Workspace 已提交配置文件运行的工作区。 默认为此数据集的工作区。 如果数据集不与工作区关联，则为必需。 有关工作区的详细信息，请参阅 https://docs.microsoft.com/en-us/python/api/azureml-core/azureml.core.workspace.workspace。

返回

类型	说明
iter(Run)	azureml.core.Run 类型的迭代器对象。

keep_columns

保留指定列并从数据集中删除所有其他列。

如果删除了时序列，也会删除返回的数据集的相应功能。

keep_columns(columns, validate=False)

参数

名称	说明
columns 必需	Union[str, list[str]] 要保留的列的名称或名称列表。
validate 必需	bool 指示是否验证从返回的数据集加载数据的可行性。 默认值为 False。 验证要求从当前计算访问数据源。

返回

类型	说明
TabularDataset	返回仅保留指定列的新 TabularDataset 对象。

mount

注意

这是一个实验性的方法，可能会在任何时候更改。 有关详细信息，请参阅 https://aka.ms/azuremlexperimental。

创建一个上下文管理器，用于将数据集定义的文件系统流装载为本地文件。

mount(stream_column, mount_point=None)

参数

名称	说明
stream_column 必需	str 要装载的流列。
mount_point 必需	str 要将文件装载到的本地目录。 如果为 None，则数据将装载到临时目录中，可以通过调用 MountContext.mount_point 实例方法找到该目录。

返回

类型	说明
<xref:azureml.dataprep.fuse.daemon.MountContext>	返回用于管理装载生命周期的上下文管理器。

partition_by

将复制分区的数据并输出到指定的目标。

从带分区格式的输出数据路径创建数据集，在提供名称的情况下注册数据集，并为带分区的新数据路径返回数据集

   ds = Dataset.get_by_name('test') # indexed by country, state, partition_date

   # #1: call partition_by locally
   new_ds = ds.partition_by(name="repartitioned_ds", partition_keys=['country'],
               target=DataPath(datastore, "repartition"))
   partition_keys = newds.partition_keys # ['country']

   # new_ds can be passed to PRS as input dataset

partition_by(partition_keys, target, name=None, show_progress=True, partition_as_file_dataset=False)

参数

名称	说明
partition_keys 必需	list[str] 必需，分区键
target 必需	DataPath, Datastore 或 tuple(Datastore, str) object 必需，数据帧 Parquet 数据将上传到的数据存储路径。 将在目标路径下生成 guid 文件夹，以避免冲突。
name 必需	str 可选，注册名称。
show_progress 必需	bool 可选，指示是否在控制台中显示上传进度。 默认值为 True。
partition_as_file_dataset 必需	可选，指示是否返回 filedataset。 默认值为 False。

返回

类型	说明
TabularDataset	保存或注册的数据集。

random_split

按指定百分比随机并大致地将数据集中的记录拆分为两个部分。

第一个数据集包含总记录的约 percentage，第二个数据集包含剩余记录。

random_split(percentage, seed=None)

参数

名称	说明
percentage 必需	float 拆分数据集依据的大致百分比。 这必须是介于 0.0 和 1.0 之间的数字。
seed 必需	int 用于随机生成器的可选种子。

返回

类型	说明
(TabularDataset, TabularDataset)	返回表示拆分后的两个数据集的新 TabularDataset 对象的元组。

skip

按指定的计数从数据集的顶部起跳过记录。

skip(count)

参数

名称	说明
count 必需	int 要跳过的记录数。

返回

类型	说明
TabularDataset	返回表示已跳过记录的数据集的新 TabularDataset 对象。

submit_profile_run

注意

这是一个实验性的方法，可能会在任何时候更改。 有关详细信息，请参阅 https://aka.ms/azuremlexperimental。

提交试验运行以计算数据配置文件。

数据配置文件提供有关数据的有用信息（如列类型、缺少值等），对理解输入数据，识别异常和缺少值非常有用。

submit_profile_run(compute_target, experiment, cache_datastore_name=None)

参数

名称	说明
compute_target 必需	Union[str, ComputeTarget] 要运行配置文件计算试验的计算目标。 指定“local”以使用本地计算。 有关计算目标的详细信息，请参阅 https://docs.microsoft.com/en-us/python/api/azureml-core/azureml.core.computetarget。
experiment 必需	Experiment 试验对象。 有关试验的详细信息，请参阅 https://docs.microsoft.com/en-us/python/api/azureml-core/azureml.core.experiment.experiment。
cache_datastore_name 必需	str 要存储配置文件缓存的数据存储的名称；如果为 None，将使用默认数据存储

返回

类型	说明
DatasetProfileRun	DatasetProfileRun 类类型的对象。

take

按指定的计数从数据集的顶部起获取记录示例。

take(count)

参数

名称	说明
count 必需	int 要获取的记录数。

返回

类型	说明
TabularDataset	返回表示采样数据集的新 TabularDataset 对象。

take_sample

按指定的概率大致获取数据集中记录的随机示例。

take_sample(probability, seed=None)

参数

名称	说明
probability 必需	float 记录包含在示例中的概率。
seed 必需	int 用于随机生成器的可选种子。

返回

类型	说明
TabularDataset	返回表示采样数据集的新 TabularDataset 对象。

time_after

在指定的开始时间之后使用时间戳列筛选 TabularDataset。

time_after(start_time, include_boundary=True, validate=True)

参数

名称	说明
start_time 必需	datetime 用于筛选数据的下限。
include_boundary 必需	bool 指示是否应包括与边界时间 (start_time) 关联的行。
validate 必需	bool 指示是否验证数据集中是否存在指定列。 默认值为 True。 验证要求可从当前计算访问数据源。

返回

类型	说明
TabularDataset	具有新筛选的数据集的 TabularDataset。

time_before

在指定的结束时间之前使用时间戳列筛选 TabularDataset。

time_before(end_time, include_boundary=True, validate=True)

参数

名称	说明
end_time 必需	datetime 用于筛选数据的上限。
include_boundary 必需	bool 指示是否应包括与边界时间 (end_time) 关联的行。
validate 必需	bool 指示是否验证数据集中是否存在指定列。 默认值为 True。 验证要求可从当前计算访问数据源。

返回

类型	说明
TabularDataset	具有新筛选的数据集的 TabularDataset。

time_between

在指定开始时间和结束时间之间筛选 TabularDataset。

time_between(start_time, end_time, include_boundary=True, validate=True)

参数

名称	说明
start_time 必需	datetime 用于筛选数据的下限。
end_time 必需	datetime 用于筛选数据的上限。
include_boundary 必需	bool 指示是否应包括与边界时间 (start_end 和 end_time) 关联的行。
validate 必需	bool 指示是否验证数据集中是否存在指定列。 默认值为 True。 验证要求可从当前计算访问数据源。

返回

类型	说明
TabularDataset	具有新筛选的数据集的 TabularDataset。

time_recent

筛选 TabularDataset，以仅包含指定持续时间（量）的最近数据。

time_recent(time_delta, include_boundary=True, validate=True)

参数

名称	说明
time_delta 必需	timedelta 要检索的最近数据的持续时间（量）。
include_boundary 必需	bool 指示是否应包括与边界时间 (time_delta) 关联的行。
validate 必需	bool 指示是否验证数据集中是否存在指定列。 默认值为 True。 验证要求可从当前计算访问数据源。

返回

类型	说明
TabularDataset	具有新筛选的数据集的 TabularDataset。

to_csv_files

将当前数据集转换为包含 CSV 文件的 FileDataset。

生成的数据集将包含一个或多个 CSV 文件，每个文件对应于当前数据集中的一个数据分区。 在下载或读取这些文件之前，这些文件不会具体化。

to_csv_files(separator=',')

参数

名称	说明
separator 必需	str 用于分隔生成文件中的值的分隔符。

返回

类型	说明
FileDataset	返回新的 FileDataset 对象，其中包含一组包含此数据集中的数据的 CSV 文件。

to_dask_dataframe

注意

这是一个实验性的方法，可能会在任何时候更改。 有关详细信息，请参阅 https://aka.ms/azuremlexperimental。

返回一个可以延迟读取数据集中数据的 Dask 数据帧。

to_dask_dataframe(sample_size=10000, dtypes=None, on_error='null', out_of_range_datetime='null')

参数

名称	说明
sample_size 必需	要读取以确定架构和类型的记录数。
dtypes 必需	一个可选的字典，它指定所需的列及其 dtype。 如果提供，则将忽略 sample_size。
on_error 必需	如何处理数据集中的任何错误值，如分析值时错误所生成的值。 有效值为“null”，即将值替换为 null；而“fail”将导致异常。
out_of_range_datetime 必需	如何处理 Pandas 支持的范围之外的日期/时间值。 有效值为“null”，即将值替换为 null；而“fail”将导致异常。

返回

类型	说明
	dask.dataframe.core.DataFrame

to_pandas_dataframe

将数据集中的所有记录加载到 pandas 数据帧。

to_pandas_dataframe(on_error='null', out_of_range_datetime='null')

参数

名称	说明
on_error 必需	如何处理数据集中的任何错误值，如分析值时错误所生成的值。 有效值为“null”，即将值替换为 null；而“fail”将导致异常。
out_of_range_datetime 必需	如何处理 Pandas 支持的范围之外的日期/时间值。 有效值为“null”，即将值替换为 null；而“fail”将导致异常。

返回

类型	说明
DataFrame	返回 pandas 数据帧。

to_parquet_files

将当前数据集转换为包含 Parquet 文件的 FileDataset。

生成的数据集将包含一个或多个 Parquet 文件，每个文件对应于当前数据集中的一个数据分区。 在下载或读取这些文件之前，这些文件不会具体化。

to_parquet_files()

返回

类型	说明
FileDataset	返回新的 FileDataset 对象，其中包含一组包含此数据集中的数据的 Parquet 文件。

to_spark_dataframe

将数据集中的所有记录加载到 Spark 数据帧。

to_spark_dataframe()

返回

类型	说明
DataFrame	返回 Spark 数据帧。

with_timestamp_columns

为数据集定义时间戳列。

with_timestamp_columns(timestamp=None, partition_timestamp=None, validate=False, **kwargs)

参数

名称	说明
timestamp 必需	str 作为 timestamp（过去称为 fine_grain_timestamp）的列的名称（可选）。 默认值为 None（清除）。
partition_timestamp 必需	str partition_timestamp（过去称为 coarse grain timestamp）列的名称（可选）。 默认值为 None（清除）。
validate 必需	bool 指示是否验证数据集中是否存在指定列。 默认值为 False。 验证要求可从当前计算访问数据源。

返回

类型	说明
TabularDataset	返回已定义时间戳列的新 TabularDataset。

注解

方法定义要用作时间戳的列。 数据集上的时间戳列可以将数据视为时间序列数据，并启用其他功能。 如果数据集指定了 timestamp (used to be referred as fine_grain_timestamp) 和 partition_timestamp (used to be referred as coarse grain timestamp)，则这两个列应表示同一时间线。

属性

timestamp_columns

返回时间戳列。

返回

类型	说明
(str, str)	为数据集定义的 timestamp（过去称为 fine_grain_timestamp）和 partition_timestamp（过去称为 coarse grain timestamp）的列名称。