Definir módulos R personalizados para o Machine Learning Studio (clássico)

APLICA-SE A: Machine Learning Studio (clássico) Azure Machine Learning

Importante

O suporte para o Estúdio de ML (clássico) terminará a 31 de agosto de 2024. Recomendamos a transição para o Azure Machine Learning até essa data.

A partir de 1 de dezembro de 2021, não poderá criar novos recursos do Estúdio de ML (clássico). Até 31 de agosto de 2024, pode continuar a utilizar os recursos existentes do Estúdio de ML (clássico).

• Consulte informações sobre como mover projetos de aprendizado de máquina do ML Studio (clássico) para o Azure Machine Learning.
• Saiba mais sobre o Azure Machine Learning

A documentação do Estúdio de ML (clássico) está a ser descontinuada e poderá não ser atualizada no futuro.

Este tópico descreve como criar e implantar um R Studio personalizado (clássico). Ele explica o que são módulos R personalizados e quais arquivos são usados para defini-los. Ele ilustra como construir os arquivos que definem um módulo e como registrar o módulo para implantação em um espaço de trabalho de Aprendizado de Máquina. Os elementos e atributos usados na definição do módulo personalizado são descritos com mais detalhes. Como usar a funcionalidade auxiliar e arquivos e várias saídas também é discutido.

Um módulo personalizado é um módulo definido pelo usuário que pode ser carregado em seu espaço de trabalho e executado como parte do experimento (clássico) do Machine Learning Studio. Um módulo R personalizado é um módulo personalizado que executa uma função R definida pelo usuário. R é uma linguagem de programação para computação estatística e gráficos que é amplamente utilizada por estatísticos e cientistas de dados para a implementação de algoritmos. Atualmente, R é o único idioma suportado em módulos personalizados, mas o suporte para idiomas adicionais está programado para versões futuras.

Os módulos personalizados têm status de primeira classe no Machine Learning Studio (clássico), no sentido de que podem ser usados como qualquer outro módulo. Podem ser executados com outros módulos, incluídos em experiências publicadas ou em visualizações. Você tem controle sobre o algoritmo implementado pelo módulo, as portas de entrada e saída a serem usadas, os parâmetros de modelagem e outros vários comportamentos de tempo de execução. Um experimento que contém módulos personalizados também pode ser publicado na Galeria de IA do Azure para facilitar o compartilhamento.

Arquivos em um módulo R personalizado

Um módulo R personalizado é definido por um arquivo .zip que contém, no mínimo, dois arquivos:

• Um arquivo de origem que implementa a função R exposta pelo módulo
• Um arquivo de definição XML que descreve a interface do módulo personalizado

Arquivos auxiliares adicionais também podem ser incluídos no arquivo .zip que fornece funcionalidade que pode ser acessada a partir do módulo personalizado. Esta opção é discutida na parte Argumentos da seção de referência Elementos no arquivo de definição XML seguindo o exemplo de início rápido.

Exemplo de início rápido: definir, empacotar e registrar um módulo R personalizado

Este exemplo ilustra como construir os arquivos exigidos por um módulo R personalizado, empacotá-los em um arquivo zip e, em seguida, registrar o módulo em seu espaço de trabalho de Aprendizado de Máquina. O pacote zip de exemplo e os arquivos de exemplo podem ser baixados do arquivo Download CustomAddRows.zip.

O ficheiro de origem

Considere o exemplo de um módulo Adicionar Linhas Personalizado que modifica a implementação padrão do módulo Adicionar Linhas usado para concatenar linhas (observações) de dois conjuntos de dados (quadros de dados). O módulo padrão Add Rows acrescenta as linhas do segundo conjunto de dados de entrada ao final do primeiro conjunto de dados de entrada usando o rbind algoritmo. A função personalizada CustomAddRows aceita similarmente dois conjuntos de dados, mas também aceita um parâmetro de permuta booleano como uma entrada adicional. Se o parâmetro swap for definido como FALSE, ele retornará o mesmo conjunto de dados que a implementação padrão. Mas se o parâmetro swap for TRUE, a função acrescentará linhas do primeiro conjunto de dados de entrada ao final do segundo conjunto de dados. O arquivo CustomAddRows.R que contém a implementação da função R CustomAddRows exposta pelo módulo Adicionar linhas personalizadas tem o seguinte código R.

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

O arquivo de definição XML

Para expor essa CustomAddRows função como o módulo do Estúdio de Aprendizado de Máquina (clássico), um arquivo de definição XML deve ser criado para especificar como o módulo Adicionar Linhas Personalizadas deve parecer e se comportar.

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

É fundamental observar que o valor dos atributos id dos elementos Input e Arg no arquivo XML deve corresponder aos nomes dos parâmetros de função do código R no arquivo CustomAddRows.R EXATAMENTE: (dataset1, dataset2 e swap no exemplo). Da mesma forma, o valor do atributo entryPoint do elemento Language deve corresponder ao nome da função no script R EXATAMENTE: (CustomAddRows no exemplo).

Por outro lado, o atributo id para o elemento Output não corresponde a nenhuma variável no script R. Quando mais de uma saída for necessária, basta retornar uma lista da função R com os resultados colocados na mesma ordem em que os elementos Outputs são declarados no arquivo XML.

Empacotar e registrar o módulo

Salve esses dois arquivos como CustomAddRows.R e CustomAddRows.xml e, em seguida, compacte os dois arquivos juntos em um arquivo CustomAddRows.zip.

Para registrá-los em seu espaço de trabalho de Aprendizado de Máquina, vá para seu espaço de trabalho no Estúdio de Aprendizado de Máquina (clássico), clique no botão +NOVO na parte inferior e escolha MÓDULO -> DO PACOTE ZIP para carregar o novo módulo Adicionar Linhas Personalizadas .

O módulo Adicionar Linhas Personalizadas agora está pronto para ser acessado por seus experimentos de Machine Learning.

Elementos no arquivo de definição XML

Elementos do módulo

O elemento Module é usado para definir um módulo personalizado no arquivo XML. Vários módulos podem ser definidos em um arquivo XML usando vários elementos de módulo . Cada módulo em seu espaço de trabalho deve ter um nome exclusivo. Registre um módulo personalizado com o mesmo nome de um módulo personalizado existente e ele substitui o módulo existente pelo novo. Os módulos personalizados podem, no entanto, ser registrados com o mesmo nome de um módulo existente do Machine Learning Studio (clássico). Em caso afirmativo, eles aparecem na categoria Personalizado da paleta de módulos.

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

Dentro do elemento Module , você pode especificar dois elementos opcionais adicionais:

• um elemento Owner incorporado no módulo
• um elemento Description que contém texto que é exibido na ajuda rápida para o módulo e quando você passa o mouse sobre o módulo na interface do usuário do Machine Learning.

Regras para limites de caracteres nos elementos Module:

• O valor do atributo name no elemento Module não deve exceder 64 caracteres de comprimento.
• O conteúdo do elemento Description não deve exceder 128 caracteres.
• O conteúdo do elemento Proprietário não deve exceder 32 caracteres.

Os resultados de um módulo podem ser determinísticos ou não determinísticos.** Por padrão, todos os módulos são considerados determinísticos. Ou seja, dado um conjunto inalterável de parâmetros de entrada e dados, o módulo deve retornar os mesmos resultados eacRAND ou uma função de tempo em que é executado. Dado esse comportamento, o Machine Learning Studio (clássico) só reexecuta módulos marcados como determinísticos se um parâmetro ou os dados de entrada tiverem sido alterados. O retorno dos resultados armazenados em cache também proporciona uma execução muito mais rápida dos experimentos.

Há funções que não são determinísticas, como RAND ou uma função que retorna a data ou hora atual. Se o módulo usa uma função não determinística, você pode especificar que o módulo não é determinístico definindo o atributo isDeterministic opcional como FALSE. Isso garante que o módulo seja executado novamente sempre que o experimento for executado, mesmo que a entrada e os parâmetros do módulo não tenham sido alterados.

Definição de linguagem

O elemento Language no arquivo de definição XML é usado para especificar o idioma do módulo personalizado. Atualmente, a única linguagem suportada é R. O valor do atributo sourceFile deve ser o nome do arquivo R que contém a função a ser chamada quando o módulo é executado. Este arquivo deve fazer parte do pacote zip. O valor do atributo entryPoint é o nome da função que está sendo chamada e deve corresponder a uma função válida definida com no arquivo de origem.

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

Portas

As portas de entrada e saída para um módulo personalizado são especificadas em elementos filho da seção Portas do arquivo de definição XML. A ordem desses elementos determina o layout experimentado (UX) pelos usuários. A primeira entrada ou saída filho listada no elemento Ports do arquivo XML torna-se a porta de entrada mais à esquerda na UX do Machine Learning. Cada porta de entrada e saída pode ter um elemento filho Descrição opcional que especifica o texto mostrado quando você passa o cursor do mouse sobre a porta na interface do usuário do Aprendizado de Máquina.

Regras de portas:

• O número máximo de portas de entrada e saída é de 8 para cada uma.

Elementos de entrada

As portas de entrada permitem que você passe dados para sua função R e espaço de trabalho. Os tipos de dados suportados para portas de entrada são os seguintes:

DataTable: Este tipo é passado para sua função R como um data.frame. Na verdade, todos os tipos (por exemplo, arquivos CSV ou ARFF) suportados pelo Machine Learning e compatíveis com DataTable são convertidos em data.frame automaticamente.

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

O atributo id associado a cada porta de entrada DataTable deve ter um valor exclusivo e esse valor deve corresponder ao parâmetro nomeado correspondente na função R. As portas DataTable opcionais que não são passadas como entrada em um experimento têm o valor NULL passado para a função R e as portas zip opcionais são ignoradas se a entrada não estiver conectada. O atributo isOptional é opcional para os tipos DataTable e Zip e é false por padrão.

Zip: Os módulos personalizados podem aceitar um arquivo zip como entrada. Esta entrada é descompactada no diretório de trabalho R da sua função

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

Para módulos R personalizados, o ID de uma porta Zip não precisa corresponder a nenhum parâmetro da função R. Isso ocorre porque o arquivo zip é extraído automaticamente para o diretório de trabalho R.

Regras de entrada:

• O valor do atributo id do elemento Input deve ser um nome de variável R válido.
• O valor do atributo id do elemento Input não deve ter mais de 64 caracteres.
• O valor do atributo name do elemento Input não deve ter mais de 64 caracteres.
• O conteúdo do elemento Description não deve ter mais de 128 caracteres
• O valor do atributo type do elemento Input deve ser Zip ou DataTable.
• O valor do atributo isOptional do elemento Input não é necessário (e é false por padrão quando não especificado), mas se for especificado, deve ser true ou false.

Elementos de saída

Portas de saída padrão: As portas de saída são mapeadas para os valores de retorno da função R, que podem ser usados pelos módulos subsequentes. DataTable é o único tipo de porta de saída padrão suportado atualmente. (Suporte para Learners and Transforms está por vir.) Uma saída DataTable é definida como:

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

Para saídas em módulos R personalizados, o valor do atributo id não precisa corresponder a nada no script R, mas deve ser exclusivo. Para uma saída de módulo único, o valor de retorno da função R deve ser um data.frame. Para gerar mais de um objeto de um tipo de dados suportado, as portas de saída apropriadas precisam ser especificadas no arquivo de definição XML e os objetos precisam ser retornados como uma lista. Os objetos de saída são atribuídos às portas de saída da esquerda para a direita, refletindo a ordem em que os objetos são colocados na lista retornada.

Por exemplo, se você quiser modificar o módulo Adicionar linhas personalizadas para gerar os dois conjuntos de dados originais, dataset1 e dataset2, além do novo conjunto de dados associado, conjunto de dados (em uma ordem, da esquerda para a direita, como: dataset, dataset1, dataset2), defina as portas de saída no arquivo CustomAddRows.xml da seguinte maneira:

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

E retorne a lista de objetos em uma lista na ordem correta em 'CustomAddRows.R':

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

Saída de visualização: você também pode especificar uma porta de saída do tipo Visualização, que exibe a saída do dispositivo gráfico R e da saída do console. Esta porta não faz parte da saída da função R e não interfere com a ordem dos outros tipos de porta de saída. Para adicionar uma porta de visualização aos módulos personalizados, adicione um elemento Output com um valor de Visualization para seu atributo type:

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

Regras de saída:

• O valor do atributo id do elemento Output deve ser um nome de variável R válido.
• O valor do atributo id do elemento Output não deve ter mais de 32 caracteres.
• O valor do atributo name do elemento Output não deve ter mais de 64 caracteres.
• O valor do atributo type do elemento Output deve ser Visualization.

Argumentos

Dados adicionais podem ser passados para a função R através de parâmetros de módulo que são definidos no elemento Argumentos . Esses parâmetros aparecem no painel de propriedades mais à direita da interface do usuário do Aprendizado de Máquina quando o módulo é selecionado. Os argumentos podem ser qualquer um dos tipos suportados ou você pode criar uma enumeração personalizada quando necessário. Semelhante aos elementos Ports, os elementos Arguments podem ter um elemento Description opcional que especifica o texto que aparece quando você passa o mouse sobre o nome do parâmetro. Propriedades opcionais para um módulo, como defaultValue, minValue e maxValue podem ser adicionadas a qualquer argumento como atributos para um elemento Properties . As propriedades válidas para o elemento Properties dependem do tipo de argumento e são descritas com os tipos de argumento suportados na próxima seção. Os argumentos com a propriedade isOptional definida como "true" não exigem que o usuário insira um valor. Se um valor não for fornecido para o argumento, o argumento não será passado para a função de ponto de entrada. Os argumentos da função de ponto de entrada que são opcionais precisam ser explicitamente manipulados pela função, por exemplo, atribuído um valor padrão de NULL na definição da função de ponto de entrada. Um argumento opcional só imporá as outras restrições de argumento, ou seja, min ou max, se um valor for fornecido pelo usuário. Tal como acontece com entradas e saídas, é fundamental que cada um dos parâmetros tenha valores de ID exclusivos associados a eles. Em nosso exemplo de início rápido, o id/parâmetro associado foi swap.

Elemento Arg

Um parâmetro module é definido usando o elemento filho Arg da seção Arguments do arquivo de definição XML. Assim como acontece com os elementos filho na seção Portas , a ordenação dos parâmetros na seção Argumentos define o layout encontrado na UX. Os parâmetros aparecem de cima para baixo na interface do usuário na mesma ordem em que são definidos no arquivo XML. Os tipos suportados pelo Machine Learning para parâmetros estão listados aqui.

int – um parâmetro do tipo Integer (32 bits).

<Arg id="intValue1" name="Int Param" type="int">
    <Properties min="0" max="100" default="0" />
    <Description>Integer Parameter</Description>
</Arg>

• Propriedades opcionais: min, max, default e isOptional

double – um parâmetro de tipo duplo.

<Arg id="doubleValue1" name="Double Param" type="double">
    <Properties min="0.000" max="0.999" default="0.3" />
    <Description>Double Parameter</Description>
</Arg>

• Propriedades opcionais: min, max, default e isOptional

bool – um parâmetro booleano que é representado por uma caixa de seleção em UX.

<Arg id="boolValue1" name="Boolean Param" type="bool">
    <Properties default="true" />
    <Description>Boolean Parameter</Description>
</Arg>

• Propriedades opcionais: padrão - false se não definido

string: uma cadeia de caracteres padrão

<Arg id="stringValue1" name="My string Param" type="string">
    <Properties isOptional="true" />
    <Description>String Parameter 1</Description>
</Arg>    

• Propriedades opcionais: default e isOptional

ColumnPicker: um parâmetro de seleção de coluna. Esse tipo é renderizado na UX como um seletor de coluna. O elemento Property é usado aqui para especificar a ID da porta a partir da qual as colunas são selecionadas, onde o tipo de porta de destino deve ser DataTable. O resultado da seleção da coluna é passado para a função R como uma lista de cadeias de caracteres contendo os nomes das colunas selecionadas.

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

• Propriedades necessárias: portId - corresponde à ID de um elemento Input com o tipo DataTable.

• Propriedades opcionais:

  • allowedTypes - Filtra os tipos de coluna dos quais você pode escolher. Os valores válidos incluem:

    • Numérico
    • Boolean
    • Categórico
    • String
    • Etiqueta
    • Caraterística
    • Resultado
    • Todos

  • default - As seleções padrão válidas para o seletor de colunas incluem:

    • Nenhuma
    • NumericFeature
    • NumericLabel
    • Pontuação numérica
    • NumericAll
    • BooleanFeature
    • BooleanLabel
    • BooleanScore
    • BooleanAll
    • CategoricalFeature
    • CategoricalLabel
    • CategoricalScore
    • CategoricalAll
    • StringFeature
    • StringLabel
    • StringScore
    • StringAll
    • AllLabel
    • Todos os recursos
    • AllScore
    • Todos

DropDown: uma lista enumerada (suspensa) especificada pelo usuário. Os itens suspensos são especificados dentro do elemento Properties usando um elemento Item . O id para cada Item deve ser exclusivo e uma variável R válida. O valor do nome de um Item serve como o texto que você vê e o valor que é passado para a função 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>    

• Propriedades opcionais:
  • default - O valor da propriedade default deve corresponder a um valor de ID de um dos elementos Item .

Arquivos auxiliares

Qualquer arquivo que é colocado em seu módulo personalizado arquivo ZIP estará disponível para uso durante o tempo de execução. Todas as estruturas de diretórios presentes são preservadas. Isso significa que o fornecimento de arquivos funciona da mesma forma localmente e na execução (clássica) do Machine Learning Studio.

Nota

Observe que todos os arquivos são extraídos para o diretório 'src', então todos os caminhos devem ter o prefixo 'src/'.

Por exemplo, digamos que você deseja remover quaisquer linhas com NAs do conjunto de dados e também remover quaisquer linhas duplicadas, antes de enviá-las para CustomAddRows, e você já escreveu uma função R que faz isso em um arquivo RemoveDupNARows.R:

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

Você pode originar o arquivo auxiliar RemoveDupNARows.R na função 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)
}

Em seguida, carregue um arquivo zip contendo 'CustomAddRows.R', 'CustomAddRows.xml' e 'RemoveDupNARows.R' como um módulo R personalizado.

Ambiente de Execução

O ambiente de execução para o script R usa a mesma versão do R que o módulo Execute R Script e pode usar os mesmos pacotes padrão. Você também pode adicionar pacotes R adicionais ao seu módulo personalizado incluindo-os no pacote zip do módulo personalizado. Basta carregá-los em seu script R como faria em seu próprio ambiente R.

As limitações do ambiente de execução incluem:

• Sistema de arquivos não persistente: Os arquivos gravados quando o módulo personalizado é executado não são persistidos em várias execuções do mesmo módulo.
• Sem acesso à rede