MLTable 類別

  • 參考

表示 MLTable。

MLTable 會定義一系列的延遲評估、不可變的作業，以從數據源載入數據。 除非要求 MLTable 傳遞數據，否則不會從來源載入數據。

初始化新的MLTable。

此建構函式不應該直接叫用。 MLTable 旨在使用 load來建立。

繼承
builtins.object
MLTable

建構函式

MLTable()

方法

convert_column_types

新增轉換步驟，將指定的數據行轉換成其各自的指定新類型。


   from mltable import DataType
       data_types = {
           'ID': DataType.to_string(),
           'Date': DataType.to_datetime('%d/%m/%Y %I:%M:%S %p'),
           'Count': DataType.to_int(),
           'Latitude': DataType.to_float(),
           'Found': DataType.to_bool(),
           'Stream': DataType.to_stream()
       }
drop_columns

新增轉換步驟，以從數據集卸除指定的數據行。 如果空的清單、Tuple 或 set 未卸除任何專案， 重複的數據行會引發 UserErrorException。

嘗試卸除MLTable.traits.timestamp_column或MLTable.traits.index_columns中的數據行將會引發UserErrorException。
extract_columns_from_partition_format

新增轉換步驟，以使用每個路徑的數據分割資訊，並根據指定的數據分割格式將它們擷取到數據行。

格式元件 '{column_name}' 會建立字串數據行，而 '{column_name：yyyy/MM/dd/HH/mm/ss}' 會建立 datetime 數據行，其中 'yyyy'、'MM'、'dd'、'HH'、'mm' 和 'ss' 用來擷取日期時間類型的年、月、日、小時、分鐘和秒。

格式應該從第一個分割區索引鍵的位置開始，直到檔案路徑的結尾為止。 例如，假設路徑 '/Accounts/2019/01/01/data.csv'，其中分割區是依部門名稱和時間， partition_format='/{Department}/{PartitionDate：yyyy/MM/dd}/data.csv' 會建立字符串數據行 'Department'，其值為 'Accounts' 和日期時間數據行 'PartitionDate'，其值為 '2019-01-01'。
filter

篩選數據，只保留符合指定表達式的記錄。
get_partition_count

傳回與這個 MLTable 相關聯之數據基礎的數據分割數目。
keep_columns

新增轉換步驟來保留指定的數據行，並從數據集卸除所有其他數據行。 如果空的清單、Tuple 或 set 未卸除任何專案， 重複的數據行會引發 UserErrorException。

如果未明確保留MLTable.traits.timestamp_column中的數據行或MLTable.traits.index_columns中的數據行，則UserErrorException是不雅的。
random_split

隨機將此 MLTable 分割成兩個 MLTable，其中一個具有大約原始 MLTable 數據的百分比，另一個則具有其餘部分 (1-“percent”%) 。
save

將此 MLTable 儲存為 MLTable YAML 檔案，& 其指定目錄路徑的路徑。

如果未指定 path ，預設為目前的工作目錄。 如果 路徑 不存在，則會建立路徑。 如果 path 是遠端的，基礎資料存放區必須已經存在。 如果 path 是本機目錄 & 不是絕對目錄，則會成為絕對目錄。

如果 路徑 指向檔案，則會引發UserErrorException。 如果 path 是已儲存一或多個檔案的目錄路徑， (包括 MLTable YAML 檔案) 且 覆寫 設定為 False 或 'fail' - 則會引發 UserErrorException。 如果 path 是遠端的，則任何未指定為共置路徑的本機檔案路徑， (相對於從) 載入 MLTable 的目錄，都會引發 UserErrorException。

共置 控件如何將相關聯的路徑儲存至 路徑。 如果為 True，則會將檔案複製到 MLTable YAML 檔案旁 的路徑 做為相對檔案路徑。 否則不會複製相關聯的檔案，遠端路徑會維持為指定狀態，而本機檔案路徑會視需要與路徑重新導向相對。 請注意，False 可能會導致不建議使用非共置 MLTable YAML 檔案，此外，如果 path 是遠端，這會導致 UserErrorException 產生 UserErrorException，因為遠端 URI 不支持相對路徑重新導向。

請注意，如果 MLTable 是以程式設計方式使用本機相對路徑 from_paths () 或 from_read_delimited_files () 等方法建立，則 MLTable 目錄路徑會假設為目前的工作目錄。

儲存新的 MLTable & 相關聯的數據檔到具有現有 MLTable 檔案的目錄時，請留意 & 目錄在儲存新檔案之前，不會清除該目錄的相關數據檔。 儲存新檔案之後，現有的數據檔可以保存，特別是在現有的數據檔沒有符合任何新數據檔的名稱時。 如果新的 MLTable 在其路徑下包含模式指示項，這可能會不小心將現有的數據檔與新的 MLTable 產生關聯，以改變 MLTable。

如果此 MLTable 中的檔案路徑指向 路徑 中的現有檔案，但具有不同的 URI，如果覆寫為 「失敗」或「略過」，則不會覆寫現有的檔案 (亦即略過) 。
select_partitions

新增轉換步驟以選取數據分割。
show

擷取這個MLTable的第一個 計數 數據列作為 Pandas 數據框架。
skip

新增轉換步驟，以略過這個MLTable的第一個 計數 數據列。
take

新增轉換步驟，以選取此 MLTable 的第一個 計數 數據列。
take_random_sample

新增轉換步驟，以隨機選取此MLTable的每個數據列，並有 機率 。 機率必須介於 [0， 1] 範圍內。 可以選擇性地設定隨機種子。
to_pandas_dataframe

將所有記錄從 MLTable 檔案中指定的路徑載入 Pandas DataFrame。
validate

驗證是否可以載入這個MLTable的數據，需要MLTable的數據源 () 才能從目前的計算存取。

convert_column_types

新增轉換步驟，將指定的數據行轉換成其各自的指定新類型。


   from mltable import DataType
       data_types = {
           'ID': DataType.to_string(),
           'Date': DataType.to_datetime('%d/%m/%Y %I:%M:%S %p'),
           'Count': DataType.to_int(),
           'Latitude': DataType.to_float(),
           'Found': DataType.to_bool(),
           'Stream': DataType.to_stream()
       }

convert_column_types(column_types)

參數

名稱 Description
column_types
必要
dict[Union[Tuple[str], str], DataType]

數據行的字典：輸入使用者想要轉換

傳回

類型 Description
MLTable

具有新增轉換步驟的MLTable

drop_columns

新增轉換步驟，以從數據集卸除指定的數據行。 如果空的清單、Tuple 或 set 未卸除任何專案， 重複的數據行會引發 UserErrorException。

嘗試卸除MLTable.traits.timestamp_column或MLTable.traits.index_columns中的數據行將會引發UserErrorException。

drop_columns(columns: str | List[str] | Tuple[str] | Set[str])

參數

名稱 Description
columns
必要
Union[str, list[str], <xref:builtin.tuple>[str], <xref:builtin.set>[str]]

要從這個 MLTable 卸除的數據行 ()

傳回

類型 Description
MLTable

具有新增轉換步驟的MLTable

extract_columns_from_partition_format

新增轉換步驟，以使用每個路徑的數據分割資訊，並根據指定的數據分割格式將它們擷取到數據行。

格式元件 '{column_name}' 會建立字串數據行，而 '{column_name：yyyy/MM/dd/HH/mm/ss}' 會建立 datetime 數據行，其中 'yyyy'、'MM'、'dd'、'HH'、'mm' 和 'ss' 用來擷取日期時間類型的年、月、日、小時、分鐘和秒。

格式應該從第一個分割區索引鍵的位置開始，直到檔案路徑的結尾為止。 例如，假設路徑 '/Accounts/2019/01/01/data.csv'，其中分割區是依部門名稱和時間， partition_format='/{Department}/{PartitionDate：yyyy/MM/dd}/data.csv' 會建立字符串數據行 'Department'，其值為 'Accounts' 和日期時間數據行 'PartitionDate'，其值為 '2019-01-01'。

extract_columns_from_partition_format(partition_format)

參數

名稱 Description
partition_format
必要
str

用來將數據擷取到數據行的數據分割格式

傳回

類型 Description
MLTable

數據分割格式設定為指定格式的MLTable

filter

篩選數據，只保留符合指定表達式的記錄。

filter(expression)

參數

名稱 Description
expression
必要
string

要評估的運算式。

傳回

類型 Description
MLTable

篩選之後的MLTable

備註

表達式的開頭是使用數據行名稱編製 mltable 的索引。 它們支持各種函式和運算符，而且可以使用邏輯運算符來結合。 當數據提取發生，而不是定義數據時，產生的表達式將會針對每個記錄進行延遲評估。


   filtered_mltable = mltable.filter('feature_1 == "5" and target > "0.5)"')
   filtered_mltable = mltable.filter('col("FBI Code") == "11"')

get_partition_count

傳回與這個 MLTable 相關聯之數據基礎的數據分割數目。

get_partition_count() -> int

傳回

類型 Description
int

此 MLTable 中的數據分割區

keep_columns

新增轉換步驟來保留指定的數據行，並從數據集卸除所有其他數據行。 如果空的清單、Tuple 或 set 未卸除任何專案， 重複的數據行會引發 UserErrorException。

如果未明確保留MLTable.traits.timestamp_column中的數據行或MLTable.traits.index_columns中的數據行，則UserErrorException是不雅的。

keep_columns(columns: str | List[str] | Tuple[str] | Set[str])

參數

名稱 Description
columns
必要
Union[str, list[str], <xref:builtin.tuple>[str], <xref:builtin.set>[str]]

此 MLTable 中的數據行 () 保留

傳回

類型 Description
MLTable

具有新增轉換步驟的MLTable

random_split

隨機將此 MLTable 分割成兩個 MLTable，其中一個具有大約原始 MLTable 數據的百分比，另一個則具有其餘部分 (1-“percent”%) 。

random_split(percent=0.5, seed=None)

參數

名稱 Description
percent
必要
Union[int, float]

要分割的MLTable百分比
seed
必要
Optional[int]

選擇性隨機種子

傳回

類型 Description
Tuple[MLTable, MLTable]

具有此 MLTable 數據的兩個 MLTable 會以「百分比」分割成兩個 MLTable

save

將此 MLTable 儲存為 MLTable YAML 檔案，& 其指定目錄路徑的路徑。

如果未指定 path ，預設為目前的工作目錄。 如果 路徑 不存在，則會建立路徑。 如果 path 是遠端的，基礎資料存放區必須已經存在。 如果 path 是本機目錄 & 不是絕對目錄，則會成為絕對目錄。

如果 路徑 指向檔案，則會引發UserErrorException。 如果 path 是已儲存一或多個檔案的目錄路徑， (包括 MLTable YAML 檔案) 且 覆寫 設定為 False 或 'fail' - 則會引發 UserErrorException。 如果 path 是遠端的，則任何未指定為共置路徑的本機檔案路徑， (相對於從) 載入 MLTable 的目錄，都會引發 UserErrorException。

共置 控件如何將相關聯的路徑儲存至 路徑。 如果為 True，則會將檔案複製到 MLTable YAML 檔案旁 的路徑 做為相對檔案路徑。 否則不會複製相關聯的檔案，遠端路徑會維持為指定狀態，而本機檔案路徑會視需要與路徑重新導向相對。 請注意，False 可能會導致不建議使用非共置 MLTable YAML 檔案，此外，如果 path 是遠端，這會導致 UserErrorException 產生 UserErrorException，因為遠端 URI 不支持相對路徑重新導向。

請注意，如果 MLTable 是以程式設計方式使用本機相對路徑 from_paths () 或 from_read_delimited_files () 等方法建立，則 MLTable 目錄路徑會假設為目前的工作目錄。

儲存新的 MLTable & 相關聯的數據檔到具有現有 MLTable 檔案的目錄時，請留意 & 目錄在儲存新檔案之前，不會清除該目錄的相關數據檔。 儲存新檔案之後，現有的數據檔可以保存，特別是在現有的數據檔沒有符合任何新數據檔的名稱時。 如果新的 MLTable 在其路徑下包含模式指示項，這可能會不小心將現有的數據檔與新的 MLTable 產生關聯，以改變 MLTable。

如果此 MLTable 中的檔案路徑指向 路徑 中的現有檔案，但具有不同的 URI，如果覆寫為 「失敗」或「略過」，則不會覆寫現有的檔案 (亦即略過) 。

save(path=None, overwrite=True, colocated=False, show_progress=False, if_err_remove_files=True)

參數

名稱 Description
path
必要
str

要儲存的目錄路徑，預設為目前的工作目錄
colocated
必要
bool

如果為 True，請將此 MLTable 中本機 & 遠端檔案路徑的複本 儲存為相對 路徑。 否則不會複製檔案，而且遠端檔案路徑會儲存為已儲存的MLTable YAML檔案和本機檔案路徑，作為路徑重新導向的相對檔案路徑。 如果 path 是遠端 & 此 MLTable 包含本機檔案路徑，則會引發 UserErrorException。
overwrite
必要
Union[bool, str, <xref:mltable.MLTableSaveOverwriteOptions>]

如何處理 路徑下可能 已經存在的 MLTable YAML 檔案和相關聯的檔案。 選項為 「覆寫」 (或 True) 取代任何現有的檔案、「失敗」 (或 False) ，以在檔案已經存在時引發錯誤，或「略過」讓現有檔案保持原樣。 也可以使用 設定 <xref:mltable.MLTableSaveOverwriteOptions>。
show_progress
必要
bool

顯示複製進度至 stdout
if_err_remove_files
必要
bool

如果在儲存期間發生任何錯誤，請移除任何成功儲存的檔案，讓作業不可部分完成

傳回

類型 Description
MLTable

這個 MLTable 實例

select_partitions

新增轉換步驟以選取數據分割。

select_partitions(partition_index_list)

參數

名稱 Description
partition_index_list
必要
list of int

數據分割索引的清單

傳回

類型 Description
MLTable

已更新數據分割大小的MLTable

備註

下列代碼段示範如何使用select_partitions API，從提供的 MLTable 選取的數據分割。


   partition_index_list = [1, 2]
   mltable = mltable.select_partitions(partition_index_list)

show

擷取這個MLTable的第一個 計數 數據列作為 Pandas 數據框架。

show(count=20)

參數

名稱 Description
count
必要
int

要選取之數據表頂端的數據列數目

傳回

類型 Description
<xref:Pandas> <xref:Dataframe>

MLTable 的第一 個計數 數據列

skip

新增轉換步驟，以略過這個MLTable的第一個 計數 數據列。

skip(count)

參數

名稱 Description
count
必要
int

要略過的數據列數目

傳回

類型 Description

具有新增轉換步驟的MLTable

take

新增轉換步驟，以選取此 MLTable 的第一個 計數 數據列。

take(count=20)

參數

名稱 Description
count
必要
int

要選取之數據表頂端的數據列數目

傳回

類型 Description
MLTable

已新增「採取」轉換步驟的MLTable

take_random_sample

新增轉換步驟，以隨機選取此MLTable的每個數據列，並有 機率 。 機率必須介於 [0， 1] 範圍內。 可以選擇性地設定隨機種子。

take_random_sample(probability, seed=None)

參數

名稱 Description
probability
必要

選取每個數據列的機會
seed
必要
Optional[int]

選擇性隨機種子

傳回

類型 Description
MLTable

具有新增轉換步驟的MLTable

to_pandas_dataframe

將所有記錄從 MLTable 檔案中指定的路徑載入 Pandas DataFrame。

to_pandas_dataframe()

傳回

類型 Description
DataFrame

Pandas Dataframe 包含此 MLTable 中路徑的記錄

備註

下列代碼段示範如何使用 to_pandas_dataframe api 來取得對應至所提供MLTable的 pandas 資料框架。


   from mltable import load
   tbl = load('.\samples\mltable_sample')
   pdf = tbl.to_pandas_dataframe()
   print(pdf.shape)

validate

驗證是否可以載入這個MLTable的數據，需要MLTable的數據源 () 才能從目前的計算存取。

validate()

傳回

類型 Description
None

無

屬性

partition_keys

傳回分割區索引鍵。

傳回

類型 Description
list[str]

分割區索引鍵

paths

傳回字典清單，其中包含提供給這個MLTable的原始路徑。 相對本機檔案路徑假設相對於載入這個MLTable實例之MLTable YAML 檔案的目錄。

傳回

類型 Description
list[dict[str, str]]

包含 MLTable 中所指定路徑的聽寫清單