Share 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 illustrerar 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 beskrivs 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 (klassisk). 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 är schemalagt 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, de indata- och utdataportar 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 innehå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 skapar 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å samma sätt två datauppsättningar, men accepterar även en boolesk växlingsparameter som ytterligare indata. Om växlingsparametern är inställd på FALSE returneras 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 datauppsättningen 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 elementen Input och Arg i XML-filen måste matcha funktionsparameternamnen för R-koden i CustomAddRows.R-filen 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 elementet Output motsvarar däremot inte några variabler i R-skriptet. När mer än en utdata krävs returnerar du helt enkelt 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 i 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-PAKET för att ladda upp den nya modulen Anpassad 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 hjälp av 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 snabbhjälp för modulen och när du hovrar över modulen i Machine Learning-användargränssnittet.

Regler för teckengränser 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 bör modulen returnera samma resultat eacRAND eller en funktionstid då den 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 nondeterministisk 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 ingå i 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" />

Portar

Portarna för in- och utdata för en anpassad modul anges i underordnade element i avsnittet Portar i XML-definitionsfilen. Ordningen på de här elementen avgör vilken layout användarna upplever (UX). De första underordnade indata eller utdata som anges i elementet Portar i XML-filen blir den port som lämnas längst till vänster i Machine Learning UX. Varje in- 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.

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 elementet Beskrivning 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.) 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 utdata från en enskild modul 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, förutom 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 enligt följande:

<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 med 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 egenskapsfönstret 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 argumenttyper som stöds i nästa avsnitt. Argument med egenskapen isOptional inställd på "true" kräver inte att användaren anger ett värde. Om ett värde inte anges för argumentet skickas inte argumentet till startpunktsfunktionen. Argument för startpunktsfunktionen som är valfria måste hanteras explicit av funktionen, t.ex. tilldelas ett standardvärde för NULL i funktionsdefinitionen för startpunkten. Ett valfritt argument tillämpar bara de andra argumentbegränsningarna, dvs. min eller max, om ett värde anges av användaren. Precis som med indata och utdata är det viktigt att var och en av parametrarna har unika ID-värden kopplade till sig. I vårt snabbstartsexempel växlades associerat ID/parameter.

Arg-element

En modulparameter definieras med hjälp av arg-underordnat element 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äffades 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 kolumner 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>

  • Obligatoriska egenskaper: portId – matchar ID:t för ett indataelement med typen DataTable.

  • Valfria egenskaper:

    • allowedTypes – Filtrerar de kolumntyper som du kan välja från. Giltiga värden är:

      • Numerisk
      • Boolesk
      • Kategoriska
      • Sträng
      • Etikett
      • Funktion
      • Poäng
      • Alla

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

      • Ingen
      • Numeriska funktioner
      • Numerisk etikett
      • Numerisk kärna
      • NumerisktAlla
      • Booleskfeature
      • BooleskLabel
      • BooleanScore
      • BooleanAll
      • Kategorisk funktion
      • Kategorisk etikett
      • 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 Objekt-element . ID:t för varje objekt måste vara unikt och en giltig R-variabel. Värdet för namnet på ett objekt fungerar både som den text som visas 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 Objekt .

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

Anteckning

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 dubblettrader 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 den anpassade modulen. 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 i flera körningar av samma modul.
  • Ingen nätverksåtkomst