Tentukan modul R kustom untuk Machine Learning Studio (klasik)

  • Artikel
  • 14 menit untuk membaca

BERLAKU UNTUK:Applies to.Machine Learning Studio (klasik) Does not apply to.Azure Machine Learning

Penting

Dukungan untuk Studio Azure Machine Learning (klasik) akan berakhir pada 31 Agustus 2024. Sebaiknya Anda transisi ke Azure Machine Learning sebelum tanggal tersebut.

Mulai 1 Desember 2021, Anda tidak akan dapat membuat sumber daya Studio Azure Machine Learning (klasik) baru. Hingga 31 Agustus 2024, Anda dapat terus menggunakan sumber daya Pembelajaran Mesin Studio (klasik) yang ada.

ML Dokumentasi Studio (klasik) sedang berhenti dan mungkin tidak diperbarui di masa mendatang.

Topik ini menjelaskan cara menulis dan menggunakan R Studio kustom (klasik). Topik ini menjelaskan apa modul R kustom dan file apa yang digunakan untuk mendefinisikannya. Topik ini menggambarkan cara membuat file yang menentukan modul dan cara mendaftarkan modul untuk penyebaran di ruang kerja Machine Learning. Elemen dan atribut yang digunakan dalam definisi modul kustom akan dijelaskan secara lebih detail. Cara menggunakan fungsionalitas tambahan dan file dan beberapa output juga dibahas.

Modul kustom adalah modul yang ditentukan pengguna, yang dapat diunggah ke ruang kerja Anda dan dieksekusi sebagai bagian dari eksperimen Azure Machine Learning Studio (klasik). Modul R kustom adalah modul kustom yang menjalankan fungsi R yang ditentukan pengguna. R adalah bahasa pemrograman untuk komputasi statistik dan grafik yang banyak digunakan oleh ahli statistik dan ilmuwan data untuk menerapkan algoritma. Saat ini, R adalah satu-satunya bahasa yang didukung dalam modul kustom, tetapi dukungan untuk bahasa tambahan dijadwalkan untuk rilis mendatang.

Modul kustom memiliki status kelas satu di Azure Machine Learning Studio (klasik) dalam arti bahwa dapat digunakan seperti modul lainnya. Mereka dapat dieksekusi dengan modul lain, termasuk dalam eksperimen yang dipublikasikan atau dalam visualisasi. Anda memiliki kontrol atas algoritma yang diimplementasikan oleh modul, port input dan output yang akan digunakan, parameter pemodelan, dan berbagai perilaku runtime lainnya. Eksperimen yang berisi modul kustom juga dapat dipublikasikan ke Galeri AI Azure agar mudah dibagikan.

File dalam modul R kustom

Modul R kustom didefinisikan oleh file .zip yang berisi, minimal, dua file:

  • File sumber yang mengimplementasikan fungsi R yang diekspos oleh modul
  • File definisi XML yang menjelaskan antarmuka modul kustom

File tambahan juga dapat disertakan dalam file .zip yang menyediakan fungsionalitas yang dapat diakses dari modul kustom. Opsi ini dibahas di bagian Argumen dari bagian referensi Elemen dalam file definisi XML dengan mengikuti contoh mulai cepat.

Contoh mulai cepat: tentukan, paket, dan daftarkan modul R kustom

Contoh ini menggambarkan cara membuat file yang diperlukan oleh modul R kustom, mengemasnya ke dalam file zip, lalu mendaftarkan modul di ruang kerja Machine Learning Anda. Contoh paket zip dan file sampel dapat diunduh dari Unduh file CustomAddRows.zip.

File sumber

Pertimbangkan contoh modul Tambahkan Baris Kustom yang memodifikasi implementasi standar modul Tambahkan Baris yang digunakan untuk menggabungkan baris (pengamatan) dari dua himpunan data (bingkai data). Modul Tambahkan Baris standar menambahkan baris himpunan data input kedua ke akhir himpunan data input pertama menggunakan rbind algoritma. Fungsi CustomAddRows yang dikustomisasi juga menerima dua himpunan data, tetapi juga menerima parameter swap Boolean sebagai input tambahan. Jika parameter swap diatur ke FALSE, parameter akan mengembalikan himpunan data yang sama dengan implementasi standar. Tetapi jika parameter swap TRUE, fungsi menambahkan baris himpunan data input pertama ke akhir himpunan data kedua sebagai gantinya. File CustomAddRows.R yang berisi implementasi fungsi R CustomAddRows yang diekspos oleh modul Baris Tambahkan Kustom memiliki kode R berikut.

CustomAddRows <- function(dataset1, dataset2, swap=FALSE) 
{
    if (swap)
    {
        return (rbind(dataset2, dataset1));
    }
    else
    {
        return (rbind(dataset1, dataset2));
    } 
}

File definisi XML

Untuk mengekspos fungsi CustomAddRows ini sebagai modul Azure Machine Learning Studio (klasik), file definisi XML harus dibuat untuk menentukan cara modul Tambahkan Baris Kustom harus terlihat dan berperilaku.

<!-- Defined a module using an R Script -->
<Module name="Custom Add Rows">
    <Owner>Microsoft Corporation</Owner>
    <Description>Appends one dataset to another. Dataset 2 is concatenated to Dataset 1 when Swap is FALSE, and vice versa when Swap is TRUE.</Description>

<!-- Specify the base language, script file and R function to use for this module. -->        
    <Language name="R" 
        sourceFile="CustomAddRows.R" 
        entryPoint="CustomAddRows" />  

<!-- Define module input and output ports -->
<!-- Note: The values of the id attributes in the Input and Arg elements must match the parameter names in the R Function CustomAddRows defined in CustomAddRows.R. -->
    <Ports>
        <Input id="dataset1" name="Dataset 1" type="DataTable">
            <Description>First input dataset</Description>
        </Input>
        <Input id="dataset2" name="Dataset 2" type="DataTable">
            <Description>Second input dataset</Description>
        </Input>
        <Output id="dataset" name="Dataset" type="DataTable">
            <Description>The combined dataset</Description>
        </Output>
    </Ports>

<!-- Define module parameters -->
    <Arguments>
        <Arg id="swap" name="Swap" type="bool" >
            <Description>Swap input datasets.</Description>
        </Arg>
    </Arguments>
</Module>

Penting untuk dicatat bahwa nilai atribut id dari elemen Input dan Arg dalam file XML harus cocok dengan nama parameter fungsi dari kode R dalam file CustomAddRows.R PERSIS: (dataset1, dataset2, dan swap dalam contoh). Demikian pula, nilai atribut entryPoint elemen Language harus cocok dengan nama fungsi dalam skrip R PERSIS: (CustomAddRows dalam contoh).

Sebaliknya, atribut id untuk elemen Output tidak sesuai dengan variabel apa pun dalam skrip R. Bila diperlukan lebih dari satu output, cukup kembalikan daftar dari fungsi R dengan hasil ditempatkan dalam urutan yang sama seperti elemen Output dideklarasikan dalam file XML.

Paket dan daftarkan modul

Simpan dua file ini sebagai CustomAddRows.R dan CustomAddRows.xml, lalu zip kedua file menjadi file CustomAddRows.zip.

Untuk mendaftarkannya di ruang kerja Azure Machine Learning Anda, buka ruang kerja di Azure Machine Learning Studio (klasik), klik tombol +NEW di bagian bawah dan pilih MODULE -> FROM ZIP PACKAGE untuk mengunggah modul Tambahkan Baris Kustom yang baru.

Upload Zip

Modul Tambahkan Baris Kustom sekarang siap diakses oleh eksperimen Pembelajaran Mesin Anda.

Elemen dalam file definisi XML

Elemen modul

Elemen Module digunakan untuk mendefinisikan modul khusus dalam file XML. Beberapa modul dapat ditentukan dalam satu file XML menggunakan beberapa elemen module. Setiap modul di ruang kerja Anda harus memiliki nama yang unik. Daftarkan modul kustom dengan nama yang sama dengan modul kustom yang ada dan menggantikan modul yang ada dengan yang baru. Modul kustom dapat didaftarkan dengan nama yang sama dengan modul Azure Machine Learning Studio (klasik) yang ada. Jika demikian, mereka muncul dalam kategori Kustom dari palet modul.

<Module name="Custom Add Rows" isDeterministic="false"> 
    <Owner>Microsoft Corporation</Owner>
    <Description>Appends one dataset to another...</Description>/>

Dalam elemen Module, Anda dapat menentukan dua elemen opsional tambahan:

  • Elemen Owner yang disematkan ke dalam modul
  • Elemen Description yang berisi teks yang ditampilkan dalam bantuan cepat untuk modul dan saat Anda mengarahkan mouse ke atas modul di UI Pembelajaran Mesin.

Aturan untuk batas karakter dalam elemen Modul:

  • Nilai atribut name di elemen Module tidak boleh melebihi panjang 64 karakter.
  • Isi elemen Description tidak boleh melebihi 128 karakter.
  • Isi dari elemen Owner tidak boleh melebihi panjang 32 karakter.

Hasil modul dapat menjadi deterministik atau nondeterministik.** Secara default, semua modul dianggap deterministik. Artinya, mengingat serangkaian parameter input dan data yang tidak berubah, modul harus mengembalikan hasil yang sama eacRAND atau waktu fungsi yang dijalankan. Mengingat perilaku ini, Azure Machine Learning Studio (klasik) hanya menjalankan ulang modul yang ditandai sebagai deterministik jika parameter atau data input telah berubah. Mengembalikan hasil cache juga memberikan eksekusi eksperimen yang jauh lebih cepat.

Ada fungsi yang tidak menentukan, seperti RAND atau fungsi yang mengembalikan tanggal atau waktu saat ini. Jika modul Anda menggunakan fungsi nondeterministik, Anda dapat menentukan bahwa modul tersebut nondeterministik dengan menyetel atribut opsional isDeterministic ke FALSE. Hal ini memastikan bahwa modul diulang setiap kali percobaan dijalankan, bahkan jika input modul dan parameter tidak berubah.

Definisi Bahasa

Elemen Language dalam file definisi XML Anda digunakan untuk menentukan bahasa modul kustom. Saat ini, R adalah satu-satunya bahasa yang didukung. Nilai atribut sourceFile haruslah nama file R yang berisi fungsi yang akan dipanggil ketika modul dijalankan. File ini harus menjadi bagian dari paket zip. Nilai atribut entryPoint adalah nama fungsi yang dipanggil dan harus cocok dengan fungsi yang valid yang ditentukan dalam file sumber.

<Language name="R" sourceFile="CustomAddRows.R" entryPoint="CustomAddRows" />

Port

Port input dan output untuk modul kustom ditentukan dalam elemen turunan dari bagian Port dari file definisi XML. Urutan elemen-elemen ini menentukan tata letak yang dialami (UX) oleh pengguna. Input atau output turunan pertama yang tercantum dalam elemen Port dari file XML menjadi port input paling kiri di UX Pembelajaran Mesin. Setiap port input dan output mungkin memiliki elemen turunan Description opsional yang menentukan teks yang ditampilkan saat Anda mengarahkan kursor mouse ke port di UI Pembelajaran Mesin.

Aturan Port:

  • Jumlah maksimum port input dan output adalah 8 untuk masing-masing.

Elemen input

Port input memungkinkan Anda meneruskan data ke fungsi R dan ruang kerja Anda. Tipe data yang didukung untuk port input adalah sebagai berikut:

DataTable: Tipe ini diteruskan ke fungsi R Anda sebagai data.frame. Bahkan, semua tipe (misalnya, file CSV atau file ARFF) yang didukung oleh Pembelajaran Mesin dan yang kompatibel dengan DataTable dikonversi ke data.frame secara otomatis.

<Input id="dataset1" name="Input 1" type="DataTable" isOptional="false">
    <Description>Input Dataset 1</Description>
</Input>

Atribut id yang terkait dengan setiap port input DataTable harus memiliki nilai unik dan nilai ini harus cocok dengan parameter bernama yang sesuai di fungsi R Anda. Port DataTable opsional yang tidak diteruskan sebagai input dalam eksperimen memiliki nilai NULL yang diteruskan ke fungsi R dan port zip opsional diabaikan jika input tidak tersambung. Atribut isOptional bersifat opsional untuk jenis DataTable dan Zip dan false secara default.

Zip: Modul kustom dapat menerima file zip sebagai input. Input ini dibongkar ke dalam direktori kerja R fungsi Anda

<Input id="zippedData" name="Zip Input" type="Zip" IsOptional="false">
    <Description>Zip files to be extracted to the R working directory.</Description>
</Input>

Untuk modul R kustom, ID untuk port Zip tidak harus cocok dengan parameter fungsi R. Ini karena berkas zip secara otomatis diekstrak ke direktori kerja R.

Aturan Input:

  • Nilai atribut id dari elemen Input harus berupa nama variabel R yang valid.
  • Nilai atribut id dari elemen Input tidak boleh lebih dari 64 karakter.
  • Nilai atribut name dari elemen Input tidak boleh lebih panjang dari 64 karakter.
  • Konten elemen Description tidak boleh lebih panjang dari 128 karakter
  • Nilai atribut type dari elemen Input harus Zip atau DataTable.
  • Nilai atribut isOptional dari elemen Input tidak diperlukan (dan secara default false jika tidak ditentukan); tetapi jika ditentukan, itu harus benar atau salah.

Elemen output

Port output standar: Port output dipetakan ke nilai yang dikembalikan dari fungsi R Anda, yang kemudian dapat digunakan oleh modul berikutnya. DataTable adalah satu-satunya tipe port output standar yang didukung saat ini. (Dukungan untuk Pelajar dan Transformasi akan datang.) Output DataTable didefinisikan sebagai:

<Output id="dataset" name="Dataset" type="DataTable">
    <Description>Combined dataset</Description>
</Output>

Untuk output dalam modul R kustom, nilai atribut id tidak harus sesuai dengan apa pun dalam skrip R, tetapi harus unik. Untuk output modul tunggal, nilai yang dikembalikan dari fungsi R harus sebuah data.frame. Untuk menghasilkan lebih dari satu objek dari tipe data yang didukung, port output yang sesuai perlu ditentukan dalam file definisi XML dan objek perlu dikembalikan sebagai daftar. Objek output ditetapkan ke port output dari kiri ke kanan, mencerminkan urutan objek ditempatkan dalam daftar yang dikembalikan.

Misalnya, jika Anda ingin memodifikasi modul Custom Add Rows untuk menghasilkan dua himpunan data asli, dataset1 dan dataset2, selain himpunan data baru yang digabungkan, dataset, (dalam urutan, dari kiri ke kanan, seperti: dataset, dataset1, dataset2), lalu tentukan port output dalam file CustomAddRows.xml sebagai berikut:

<Ports> 
    <Output id="dataset" name="Dataset Out" type="DataTable"> 
        <Description>New Dataset</Description> 
    </Output> 
    <Output id="dataset1_out" name="Dataset 1 Out" type="DataTable"> 
        <Description>First Dataset</Description> 
    </Output> 
    <Output id="dataset2_out" name="Dataset 2 Out" type="DataTable"> 
        <Description>Second Dataset</Description> 
    </Output> 
    <Input id="dataset1" name="Dataset 1" type="DataTable"> 
        <Description>First Input Table</Description>
    </Input> 
    <Input id="dataset2" name="Dataset 2" type="DataTable"> 
        <Description>Second Input Table</Description> 
    </Input> 
</Ports>

Kemudian, kembalikan daftar objek dalam daftar dalam urutan yang benar di 'CustomAddRows.R':

CustomAddRows <- function(dataset1, dataset2, swap=FALSE) { 
    if (swap) { dataset <- rbind(dataset2, dataset1)) } 
    else { dataset <- rbind(dataset1, dataset2)) 
    } 
    return (list(dataset, dataset1, dataset2)) 
}

Output visualisasi: Anda juga dapat menentukan port output dari jenis Visualisasi yang menampilkan output dari perangkat grafis R dan output konsol. Port ini bukan bagian dari output fungsi R dan tidak mengganggu urutan tipe port output lainnya. Untuk menambahkan port visualisasi ke modul khusus, tambahkan elemen Output dengan nilai Visualisasi untuk atribut type-nya:

<Output id="deviceOutput" name="View Port" type="Visualization">
    <Description>View the R console graphics device output.</Description>
</Output>

Aturan Output:

  • Nilai atribut id dari elemen Output harus berupa nama variabel R yang valid.
  • Nilai atribut id dari elemen Output tidak boleh lebih dari 32 karakter.
  • Nilai atribut name dari elemen Output tidak boleh lebih dari 64 karakter.
  • Nilai atribut type dari elemen Output harus Visualization.

Argumen

Data tambahan dapat diteruskan ke fungsi R melalui parameter modul yang ditentukan dalam elemen Argument. Parameter ini muncul di panel properti paling kanan dari UI Pembelajaran Mesin saat modul dipilih. Argumen dapat berupa salah satu jenis yang didukung atau Anda dapat membuat enumerasi khusus bila diperlukan. Serupa dengan elemen Port, elemen Argument dapat memiliki elemen Description opsional yang menentukan teks yang muncul saat Anda mengarahkan mouse ke nama parameter. Properti opsional untuk modul, seperti defaultValue, minValue, dan maxValue dapat ditambahkan ke argumen apa pun sebagai atribut ke elemen Property. Properti yang valid untuk elemen Property bergantung pada tipe argumen dan dijelaskan dengan tipe argumen yang didukung di bagian berikutnya. Argumen dengan properti isOptional yang diatur ke "true" tidak mengharuskan pengguna untuk memasukkan nilai. Jika nilai tidak diberikan ke argumen, maka argumen tidak diteruskan ke fungsi titik masuk. Argumen fungsi titik masuk yang opsional perlu ditangani secara eksplisit oleh fungsi, misalnya menetapkan nilai default NULL dalam definisi fungsi titik masuk. Argumen opsional hanya akan memberlakukan batasan argumen lainnya, yaitu min atau maks, jika nilai disediakan oleh pengguna. Seperti halnya input dan output, sangat penting bahwa setiap parameter memiliki nilai ID unik yang terkait dengannya. Dalam contoh mulai cepat kami, id/parameter terkait adalah swap.

Elemen Arg

Parameter modul ditentukan menggunakan elemen turunan Arg dari bagian Argumen file definisi XML. Seperti elemen turunan di bagian Port, pengurutan parameter di bagian Argumen menentukan tata letak yang ditemukan di UX. Parameter muncul dari atas ke bawah di UI dalam urutan yang sama di mana parameter ditentukan dalam file XML. Jenis yang didukung oleh Pembelajaran Mesin untuk parameter tercantum di sini.

int – parameter tipe Bilangan Bulat (32-bit).

<Arg id="intValue1" name="Int Param" type="int">
    <Properties min="0" max="100" default="0" />
    <Description>Integer Parameter</Description>
</Arg>
  • Properti Opsional: min, maks, default dan isOptional

double – parameter tipe ganda.

<Arg id="doubleValue1" name="Double Param" type="double">
    <Properties min="0.000" max="0.999" default="0.3" />
    <Description>Double Parameter</Description>
</Arg>
  • Properti Opsional: min, maks, default dan isOptional

bool – parameter Boolean yang diwakili oleh kotak centang di UX.

<Arg id="boolValue1" name="Boolean Param" type="bool">
    <Properties default="true" />
    <Description>Boolean Parameter</Description>
</Arg>
  • Properti Opsional: default - false jika tidak diatur

string: string standar

<Arg id="stringValue1" name="My string Param" type="string">
    <Properties isOptional="true" />
    <Description>String Parameter 1</Description>
</Arg>
  • Properti Opsional: default dan isOptional

ColumnPicker: parameter pemilihan kolom. Tipe ini dirender di UX sebagai pemilih kolom. Elemen Property digunakan di sini untuk menentukan ID port tempat kolom dipilih, dengan jenis port target harus DataTable. Hasil pemilihan kolom diteruskan ke fungsi R sebagai daftar string yang berisi nama kolom yang dipilih.

<Arg id="colset" name="Column set" type="ColumnPicker">      
    <Properties portId="datasetIn1" allowedTypes="Numeric" default="NumericAll"/>
    <Description>Column set</Description>
</Arg>

  • Properti yang Diperlukan: portId - cocok dengan ID elemen Input dengan tipe DataTable.

  • Properti Opsional:

    • allowedTypes - Memfilter tipe kolom tempat Anda dapat memilih. Nilai yang valid meliputi:

      • Numerik
      • Boolean
      • Kategoris
      • String
      • Label
      • Fitur
      • Skor
      • Semua

    • default - Pilihan default yang valid untuk pemilih kolom meliputi:

      • Tidak ada
      • NumericFeature
      • NumericLabel
      • NumericScore
      • NumericAll
      • BooleanFeature
      • BooleanLabel
      • BooleanScore
      • BooleanAll
      • CategoricalFeature
      • CategoricalLabel
      • CategoricalScore
      • CategoricalAll
      • StringFeature
      • StringLabel
      • StringScore
      • StringAll
      • AllLabel
      • AllFeature
      • AllScore
      • Semua

DropDown: daftar enumerasi (menu drop-down) yang ditentukan pengguna. Item menu drop-down ditentukan dalam elemen Property menggunakan elemen Item. id untuk setiap Item harus unik dan variabel R yang valid. Nilai name dari Item berfungsi sebagai teks yang Anda lihat dan nilai yang diteruskan ke fungsi R.

<Arg id="color" name="Color" type="DropDown">
    <Properties default="red">
        <Item id="red" name="Red Value"/>
        <Item id="green" name="Green Value"/>
        <Item id="blue" name="Blue Value"/>
    </Properties>
    <Description>Select a color.</Description>
</Arg>
  • Properti Opsional:
    • default - Nilai untuk properti default harus sesuai dengan nilai ID dari salah satu elemen Item.

File Tambahan

File apa pun yang ditempatkan dalam file ZIP modul kustom Anda akan tersedia untuk digunakan selama waktu eksekusi. Setiap struktur direktori yang ada dipertahankan. Ini berarti bahwa sumber file berfungsi sama secara lokal dan dalam eksekusi Azure Machine Learning Studio (klasik).

Catatan

Perhatikan bahwa semua file diekstrak ke direktori 'src' sehingga semua jalur harus memiliki awalan 'src/'.

Misalnya, Anda ingin menghapus baris apa pun dengan NA dari kumpulan data, dan juga menghapus baris duplikat, sebelum mengeluarkannya ke CustomAddRows, dan Anda telah menulis fungsi R yang melakukan itu dalam file RemoveDupNARows.R:

RemoveDupNARows <- function(dataFrame) {
    #Remove Duplicate Rows:
    dataFrame <- unique(dataFrame)
    #Remove Rows with NAs:
    finalDataFrame <- dataFrame[complete.cases(dataFrame),]
    return(finalDataFrame)
}

Anda dapat sumber file tambahan RemoveDupNARows.R dalam fungsi CustomAddRows:

CustomAddRows <- function(dataset1, dataset2, swap=FALSE) {
    source("src/RemoveDupNARows.R")
        if (swap) { 
            dataset <- rbind(dataset2, dataset1))
        } else { 
            dataset <- rbind(dataset1, dataset2)) 
        } 
    dataset <- removeDupNARows(dataset)
    return (dataset)
}

Selanjutnya, unggah file zip yang berisi 'CustomAddRows.R', 'CustomAddRows.xml', dan 'RemoveDupNARows.R' sebagai modul R kustom.

Lingkungan eksekusi

Lingkungan eksekusi untuk skrip R menggunakan versi R yang sama dengan modul Execute R Script dan dapat menggunakan paket default yang sama. Anda juga dapat menambahkan paket R tambahan ke modul kustom Anda dengan menyertakannya dalam paket zip modul kustom. Cukup muat di skrip R Anda seperti yang Anda lakukan di lingkungan R Anda sendiri.

Keterbatasan lingkungan eksekusi meliputi:

  • Sistem file nonpersisten: File yang ditulis saat modul khusus dijalankan tidak bertahan di beberapa kali proses dari modul yang sama.
  • Tidak ada akses jaringan