Dela via

Definiera anpassade R-moduler för Machine Learning Studio (klassisk)

  • Artikel

GÄLLER FÖR: Gäller för.Machine Learning Studio (klassisk) Gäller inte för.Azure Machine Learning

Viktigt!

Stödet för Machine Learning Studio (klassisk) upphör den 31 augusti 2024. Vi rekommenderar att du byter till Azure Machine Learning innan dess.

Från och med den 1 december 2021 kan du inte längre skapa nya Machine Learning Studio-resurser (klassisk). Du kan fortsätta att använda befintliga Machine Learning Studio-resurser (klassisk) till och med den 31 augusti 2024.

Dokumentationen om ML Studio (klassisk) håller på att dras tillbaka och kanske inte uppdateras i framtiden.

Det här avsnittet beskriver hur du skapar och distribuerar en anpassad R Studio (klassisk). Den förklarar vad anpassade R-moduler är och vilka filer som används för att definiera dem. Den visar hur du skapar de filer som definierar en modul och hur du registrerar modulen för distribution på en Machine Learning-arbetsyta. De element och attribut som används i definitionen av den anpassade modulen beskrivs sedan mer detaljerat. Hur du använder extra funktioner och filer och flera utdata diskuteras också.

En anpassad modul är en användardefinierad modul som kan laddas upp till din arbetsyta och köras som en del av Machine Learning Studio-experimentet (klassiskt). En anpassad R-modul är en anpassad modul som kör en användardefinierad R-funktion. R är ett programmeringsspråk för statistisk databehandling och grafik som ofta används av statistiker och dataforskare för att implementera algoritmer. För närvarande är R det enda språk som stöds i anpassade moduler, men stöd för ytterligare språk har schemalagts för framtida versioner.

Anpassade moduler har förstklassig status i Machine Learning Studio (klassisk) i den meningen att de kan användas precis som andra moduler. De kan köras med andra moduler, som ingår i publicerade experiment eller i visualiseringar. Du har kontroll över algoritmen som implementeras av modulen, indata- och utdataportarna som ska användas, modelleringsparametrarna och andra olika körningsbeteenden. Ett experiment som innehåller anpassade moduler kan också publiceras i Azure AI-galleriet för enkel delning.

Filer i en anpassad R-modul

En anpassad R-modul definieras av en .zip fil som innehåller minst två filer:

  • En källfil som implementerar R-funktionen som exponeras av modulen
  • En XML-definitionsfil som beskriver det anpassade modulgränssnittet

Ytterligare extra filer kan också ingå i .zip-filen som tillhandahåller funktioner som kan nås från den anpassade modulen. Det här alternativet beskrivs i avsnittet Argument i referensavsnittet Element i XML-definitionsfilen efter snabbstartsexemplet.

Snabbstartsexempel: definiera, paketera och registrera en anpassad R-modul

Det här exemplet illustrerar hur du konstruerar de filer som krävs av en anpassad R-modul, paketera dem i en zip-fil och sedan registrera modulen på din Machine Learning-arbetsyta. Zip-exempelpaketet och exempelfilerna kan laddas ned från Ladda ned CustomAddRows.zip fil.

Källfilen

Tänk på exemplet med modulen Lägg till rader som ändrar standardimplementeringen av modulen Lägg till rader som används för att sammanfoga rader (observationer) från två datauppsättningar (dataramar). Standardmodulen Lägg till rader lägger till raderna i den andra indatauppsättningen i slutet av den första indatauppsättningen med hjälp av algoritmen rbind . Den anpassade CustomAddRows funktionen accepterar på liknande sätt två datauppsättningar, men accepterar även en boolesk växlingsparameter som ytterligare indata. Om växlingsparametern är inställd på FALSE returnerar den samma datauppsättning som standardimplementeringen. Men om växlingsparametern är TRUE lägger funktionen till rader med den första indatauppsättningen i slutet av den andra datamängden i stället. Filen CustomAddRows.R som innehåller implementeringen av R-funktionen CustomAddRows som exponeras av modulen Anpassad lägg till rader har följande R-kod.

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

XML-definitionsfilen

Om du vill exponera den här CustomAddRows funktionen som modulen Machine Learning Studio (klassisk) måste du skapa en XML-definitionsfil för att ange hur modulen Lägg till rader ska se ut och fungera.

<!-- 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>

Det är viktigt att observera att värdet för ID-attributen för indata- och Arg-elementen i XML-filen måste matcha funktionsparameternamnen för R-koden i Filen CustomAddRows.R EXAKT: (datauppsättning1, datauppsättning2 och växling i exemplet). På samma sätt måste värdet för attributet entryPoint för language-elementet matcha namnet på funktionen i R-skriptet EXAKT: (CustomAddRows i exemplet).

Id-attributet för utdataelementet motsvarar däremot inte några variabler i R-skriptet. När mer än ett utdata krävs returnerar du bara en lista från R-funktionen med resultat i samma ordning som utdataelement deklareras i XML-filen.

Paketera och registrera modulen

Spara dessa två filer som CustomAddRows.R och CustomAddRows.xml och zippa sedan ihop de två filerna till en CustomAddRows.zip fil.

Om du vill registrera dem på din Machine Learning-arbetsyta går du till din arbetsyta i Machine Learning Studio (klassisk), klickar på knappen +NYTT längst ned och väljer MODUL –> FRÅN ZIP PACKAGE för att ladda upp den nya modulen Lägg till rader.

Ladda upp Zip

Modulen Lägg till rader är nu redo att nås av dina Machine Learning-experiment.

Element i XML-definitionsfilen

Modulelement

Modulelementet används för att definiera en anpassad modul i XML-filen. Flera moduler kan definieras i en XML-fil med flera modulelement . Varje modul på arbetsytan måste ha ett unikt namn. Registrera en anpassad modul med samma namn som en befintlig anpassad modul och ersätt den befintliga modulen med den nya. Anpassade moduler kan dock registreras med samma namn som en befintlig Machine Learning Studio-modul (klassisk). I så fall visas de i kategorin Anpassad för modulpaletten.

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

I modulelementet kan du ange ytterligare två valfria element:

  • ett ägarelement som är inbäddat i modulen
  • ett Beskrivning-element som innehåller text som visas i snabb hjälp för modulen och när du hovrar över modulen i Machine Learning-användargränssnittet.

Regler för teckenbegränsningar i modulelementen:

  • Värdet för namnattributet i modulelementet får inte överstiga 64 tecken.
  • Innehållet i elementet Beskrivning får inte vara längre än 128 tecken.
  • Innehållet i elementet Ägare får inte vara längre än 32 tecken.

En moduls resultat kan vara deterministiska eller icke-deterministiska.** Som standard anses alla moduler vara deterministiska. Med tanke på en oföränderlig uppsättning indataparametrar och data ska modulen returnera samma resultat eacRAND eller en funktionstid som körs. Med tanke på det här beteendet kör Machine Learning Studio (klassisk) endast moduler som markerats som deterministiska om en parameter eller indata har ändrats. Att returnera cachelagrade resultat ger också mycket snabbare körning av experiment.

Det finns funktioner som är icke-terministiska, till exempel RAND eller en funktion som returnerar aktuellt datum eller tid. Om modulen använder en icke-deterministisk funktion kan du ange att modulen är icke-deterministisk genom att ange det valfria isDeterministiska attributet till FALSE. Detta försäkrar att modulen körs igen när experimentet körs, även om modulens indata och parametrar inte har ändrats.

Språkdefinition

Språkelementet i XML-definitionsfilen används för att ange det anpassade modulspråket. R är för närvarande det enda språk som stöds. Värdet för attributet sourceFile måste vara namnet på R-filen som innehåller funktionen som ska anropas när modulen körs. Den här filen måste vara en del av zip-paketet. Värdet för attributet entryPoint är namnet på den funktion som anropas och måste matcha en giltig funktion som definierats med i källfilen.

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

Hamnar

Portarna för in- och utdata för en anpassad modul anges i underordnade element i avsnittet Portar i XML-definitionsfilen. Ordningen på dessa element avgör vilken layout användarna upplever (UX). Den första underordnade in- eller utdata som anges i xml-filens portelement blir den port som är mest indata i Machine Learning UX. Varje indata- och utdataport kan ha ett valfritt underordnat Beskrivning-element som anger den text som visas när du hovrar musmarkören över porten i Machine Learning-användargränssnittet.

Portregler:

  • Maximalt antal in- och utdataportar är 8 för varje port.

Indataelement

Med indataportar kan du skicka data till din R-funktion och arbetsyta. De datatyper som stöds för indataportar är följande:

DataTable: Den här typen skickas till din R-funktion som en data.frame. I själva verket konverteras alla typer (till exempel CSV-filer eller ARFF-filer) som stöds av Machine Learning och som är kompatibla med DataTable automatiskt till en data.frame.

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

ID-attributet som är associerat med varje DataTable-indataport måste ha ett unikt värde och det här värdet måste matcha motsvarande namngivna parameter i R-funktionen. Valfria DataTable-portar som inte skickas som indata i ett experiment har värdet NULL som skickas till R-funktionen och valfria zip-portar ignoreras om indata inte är anslutna. attributet isOptional är valfritt för både DataTable - och Zip-typerna och är falskt som standard.

Zip: Anpassade moduler kan acceptera en zip-fil som indata. Dessa indata packas upp i R-arbetskatalogen för din funktion

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

För anpassade R-moduler behöver ID:t för en Zip-port inte matcha några parametrar för R-funktionen. Det beror på att zip-filen extraheras automatiskt till R-arbetskatalogen.

Indataregler:

  • Värdet för ID-attributet för indataelementet måste vara ett giltigt R-variabelnamn.
  • Värdet för ID-attributet för indataelementet får inte vara längre än 64 tecken.
  • Värdet för namnattributet för indataelementet får inte vara längre än 64 tecken.
  • Innehållet i beskrivningselementet får inte vara längre än 128 tecken
  • Värdet för typattributet för indataelementet måste vara Zip eller DataTable.
  • Värdet för attributet isOptional för indataelementet krävs inte (och är falskt som standard när det inte anges), men om det anges måste det vara sant eller falskt.

Utdataelement

Standardutdataportar: Utdataportar mappas till returvärdena från R-funktionen, som sedan kan användas av efterföljande moduler. DataTable är den enda standardporttypen som stöds för närvarande. (Stöd för Elever och transformeringar kommer.) Ett DataTable-utdata definieras som:

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

För utdata i anpassade R-moduler behöver värdet för ID-attributet inte motsvara något i R-skriptet, men det måste vara unikt. För en enskild modulutdata måste returvärdet från R-funktionen vara en data.frame. För att kunna mata ut fler än ett objekt av en datatyp som stöds måste lämpliga utdataportar anges i XML-definitionsfilen och objekten måste returneras som en lista. Utdataobjekten tilldelas till utdataportar från vänster till höger, vilket återspeglar i vilken ordning objekten placeras i den returnerade listan.

Om du till exempel vill ändra modulen Lägg till rader för att mata ut de ursprungliga två datauppsättningarna, datauppsättning1 och datauppsättning2, utöver den nya kopplade datauppsättningen, datauppsättningen (i en ordning från vänster till höger, som: datauppsättning, datauppsättning1, datauppsättning2), definierar du sedan utdataportarna i CustomAddRows.xml-filen på följande sätt:

<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>

Och returnera listan över objekt i en lista i rätt ordning i CustomAddRows.R:

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

Visualiseringsutdata: Du kan också ange en utdataport av typen Visualisering, som visar utdata från R-grafikenheten och konsolutdata. Den här porten är inte en del av R-funktionens utdata och stör inte ordningen på de andra utdataporttyperna. Om du vill lägga till en visualiseringsport i de anpassade modulerna lägger du till ett utdataelement med värdet Visualisering för dess typattribut :

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

Utdataregler:

  • Värdet för ID-attributet för utdataelementet måste vara ett giltigt R-variabelnamn.
  • Värdet för ID-attributet för utdataelementet får inte vara längre än 32 tecken.
  • Värdet för namnattributet för utdataelementet får inte vara längre än 64 tecken.
  • Värdet för typattributet för utdataelementet måste vara Visualisering.

Argument

Ytterligare data kan skickas till R-funktionen via modulparametrar som definieras i elementet Argument . De här parametrarna visas i fönstret egenskaper längst till höger i Machine Learning-användargränssnittet när modulen väljs. Argument kan vara någon av de typer som stöds eller så kan du skapa en anpassad uppräkning när det behövs. Precis som portelementen kan argumentelement ha ett valfritt Beskrivning-element som anger den text som visas när du hovrar musen över parameternamnet. Valfria egenskaper för en modul, till exempel defaultValue, minValue och maxValue, kan läggas till i valfritt argument som attribut till ett egenskapselement . Giltiga egenskaper för elementet Egenskaper beror på argumenttypen och beskrivs med argumenttyperna som stöds i nästa avsnitt. Argument med egenskapen isOptional inställt på "true" kräver inte att användaren anger ett värde. Om ett värde inte anges i argumentet skickas inte argumentet till startpunktsfunktionen. Argument för den startpunktsfunktion som är valfri måste hanteras explicit av funktionen, t.ex. tilldelat ett standardvärde för NULL i funktionsdefinitionen för startpunkt. Ett valfritt argument tillämpar endast de andra argumentbegränsningarna, dvs. min eller max, om ett värde tillhandahålls av användaren. Precis som med indata och utdata är det viktigt att var och en av parametrarna har unika ID-värden associerade med dem. I vårt snabbstartsexempel växlades det associerade ID/parametern.

Arg-element

En modulparameter definieras med hjälp av det underordnade elementet Arg i avsnittet Argument i XML-definitionsfilen. Precis som med de underordnade elementen i avsnittet Portar definierar ordningen på parametrarna i avsnittet Argument den layout som påträffas i UX. Parametrarna visas uppifrån och ned i användargränssnittet i samma ordning som de definieras i XML-filen. De typer som stöds av Machine Learning för parametrar visas här.

int – en parameter av typen Heltal (32 bitar).

<Arg id="intValue1" name="Int Param" type="int">
    <Properties min="0" max="100" default="0" />
    <Description>Integer Parameter</Description>
</Arg>
  • Valfria egenskaper: min, max, standard och isOptional

double – en parameter av dubbel typ.

<Arg id="doubleValue1" name="Double Param" type="double">
    <Properties min="0.000" max="0.999" default="0.3" />
    <Description>Double Parameter</Description>
</Arg>
  • Valfria egenskaper: min, max, standard och isOptional

bool – en boolesk parameter som representeras av en kryssruta i UX.

<Arg id="boolValue1" name="Boolean Param" type="bool">
    <Properties default="true" />
    <Description>Boolean Parameter</Description>
</Arg>
  • Valfria egenskaper: standard – falskt om det inte har angetts

sträng: en standardsträng

<Arg id="stringValue1" name="My string Param" type="string">
    <Properties isOptional="true" />
    <Description>String Parameter 1</Description>
</Arg>
  • Valfria egenskaper: standard och isOptional

ColumnPicker: en kolumnvalsparameter. Den här typen renderas i UX som kolumnväljare. Egenskapselementet används här för att ange ID för den port som kolumnerna väljs från, där målporttypen måste vara DataTable. Resultatet av kolumnmarkeringen skickas till R-funktionen som en lista över strängar som innehåller de valda kolumnnamnen.

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

  • Nödvändiga egenskaper: portId – matchar ID:t för ett indataelement med typen DataTable.

  • Valfria egenskaper:

    • allowedTypes – Filtrerar de kolumntyper som du kan välja mellan. Giltiga värden:

      • Numerisk
      • Booleskt
      • Kategoriska
      • String
      • Etikett
      • Funktion
      • Poäng
      • Alla

    • default – Giltiga standardval för kolumnväljaren är:

      • Ingen
      • Numeriska funktioner
      • Numerisk etikett
      • Numerisk kärna
      • NumerisktAlla
      • Booleskfeatur
      • BooleanLabel
      • Boolesk kärna
      • Boolesktalla
      • Kategoriskfeatur
      • KategoriskLabel
      • Kategorisk kärnor
      • KategoriskAlla
      • StringFeature
      • StringLabel
      • StringScore
      • StringAll
      • AllLabel
      • AllFeature
      • AllScore
      • Alla

Listruta: en användardefinerad uppräkningslista (listruta). Listruteobjekten anges i elementet Egenskaper med hjälp av ett objektelement . ID :t för varje objekt måste vara unikt och en giltig R-variabel. Värdet för namnet på ett objekt fungerar som både den text som du ser och värdet som skickas till R-funktionen.

<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>
  • Valfria egenskaper:
    • default – Värdet för standardegenskapen måste motsvara ett ID-värde från ett av elementen Item .

Extra filer

Alla filer som placeras i zip-filen för den anpassade modulen kommer att vara tillgängliga för användning under körningstiden. Alla katalogstrukturer som finns bevaras. Det innebär att filkällor fungerar på samma sätt lokalt och i Machine Learning Studio-körningen (klassisk).

Kommentar

Observera att alla filer extraheras till "src"-katalogen så att alla sökvägar ska ha prefixet "src/".

Anta till exempel att du vill ta bort alla rader med NA:er från datauppsättningen och även ta bort eventuella dubbletter av rader innan du matar ut dem till CustomAddRows, och du har redan skrivit en R-funktion som gör det i en fil RemoveDupNARows.R:

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

Du kan hämta extrafilen RemoveDupNARows.R i funktionen 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)
}

Ladda sedan upp en zip-fil som innehåller "CustomAddRows.R", "CustomAddRows.xml" och "RemoveDupNARows.R" som en anpassad R-modul.

Körningsmiljö

Körningsmiljön för R-skriptet använder samma version av R som modulen Kör R-skript och kan använda samma standardpaket. Du kan också lägga till ytterligare R-paket i din anpassade modul genom att inkludera dem i zip-paketet för anpassade moduler. Läs bara in dem i ditt R-skript som du skulle göra i din egen R-miljö.

Begränsningar i körningsmiljön är:

  • Icke-beständigt filsystem: Filer som skrivs när den anpassade modulen körs sparas inte över flera körningar av samma modul.
  • Ingen nätverksåtkomst