Comando RCOMMAND
Informações do conceito
Passa uma tabela do Analytics para um script do R externo como um dataframe e cria uma nova tabela no projeto do Analytics usando a saída retornada do script R.
Sintaxe
RCOMMAND FIELDS campo <...n> RSCRIPT caminho_para_script TO nome_tabela <IF teste> <WHILE teste> <FIRST intervalo|NEXT intervalo> <KEEPTITLE> <SEPARATOR caractere> <QUALIFIER caractere> <OPEN>
Parâmetros
| Nome | Descrição |
|---|---|
| FIELDS nome_campo <...n> |
Os campos da tabela do Analytics de origem ou as expressões a serem incluídas no quadro de dados enviado para o script do R. Dependendo da edição do Analytics que estiver usando, você poderá encontrar erros ao enviar dados contendo alguns caracteres especiais do R:
Nota Dados de idiomas misturados também não são compatíveis, por exemplo, uma tabela contendo caracteres japoneses e chineses. |
| RSCRIPT caminho_para_script |
O caminho completo ou relativo para o script do R no sistema de arquivos. Coloque caminho_para_script entre aspas. |
| TO nome_tabela |
A localização para onde enviar os resultados do comando:
A tabela de saída é criada a partir do quadro de dados ou matriz que o script do R retorna. |
| IF teste opcional |
Uma condição que precisa ser atendida para processar o registro atual. O quadro de dados passado para o script do R contém apenas os registros que atendem à condição. |
| WHILE teste opcional |
Uma expressão condicional que deve ser verdadeira para processar cada registro. O comando é executado até que a condição seja avaliada como falsa ou o fim da tabela seja alcançado. Nota Se você usar WHILE juntamente com FIRST ou NEXT, o processamento de registros será interrompido assim que um limite for alcançado. |
| FIRST intervalo | NEXT intervalo opcional |
O número de registros a ser processado:
Use intervalo para especificar o número de registros a serem processados. Se você omitir FIRST e NEXT, todos os registros serão processados por padrão. Cuidado Há um problema conhecido na versão com NEXT na execução de RCOMMAND. Evite usar essa opção, pois a referência do registro poderá ser redefinida para o primeiro registro, independentemente do registro selecionado. |
| KEEPTITLE opcional |
Trate a primeira linha de dados como nomes de campos em vez de dados. Se omitida, serão usados nomes de campo genéricos. Esta opção é obrigatória se quiser recuperar dados usando nomes de coluna no script do R. |
| SEPARATOR caractere opcional |
O caractere a ser usado como separador entre campos. É preciso especificar o caractere como uma cadeia entre aspas. O caractere padrão é uma vírgula. Nota Evite usar quaisquer caracteres que aparecem nos campos de entrada. Se o caractere SEPARATOR aparecer nos dados de entrada, os resultados poderão ser afetados. |
| QUALIFIER caractere opcional |
O caractere qualificador de texto. Os valores dos campos são colocados entre caracteres qualificadores para identificação. É preciso especificar o caractere como uma cadeia entre aspas. O caractere padrão é uma aspa. Nota Evite usar quaisquer caracteres que aparecem nos campos de entrada. Se o caractere QUALIFIER aparecer nos dados de entrada, os resultados poderão ser afetados. |
|
OPEN opcional |
Abre a tabela criada pelo comando após a execução do comando. Válido apenas se o comando criar uma tabela de saída. |
Exemplos
Colocar o R em operação (Hello world)
Crie um script "hello world" para testar a conexão entre o Analytics e o R:
Comando do Analytics
RCOMMAND FIELDS "Olá"; ", mundo!" TO "resultado_r" RSCRIPT "C:\scripts\r_scripts\análise.r"
Script do R (análise.r)
srcTable<-acl.readData()
# criar tabela para enviar de volta ao ACL
output<-data.frame(
c(srcTable[1,1]),
c(srcTable[1,2])
)
# adicionar nomes de colunas e enviar tabela de volta ao ACL
colnames(output) <- c("Cumprimento","Assunto")
acl.output<-output
Acesso de dados de arquivo usando coordenadas de linha e coluna
Envie vários campos de fatura para um script do R para fins de análise fora do Analytics:
Comando do Analytics
RCOMMAND FIELDS Código_Departamento Total_Fatura Data_Fatura Número_Fatura Número_Fornecedor TO "resultado_r" RSCRIPT "C:\scripts\r_scripts\análise.r"
Script do R (análise.r)
# Recupera número da fatura da segunda linha do quadro de dados no script do R
srcTable<-acl.readData()
srcTable[2,4]
Acesso de dados de campos usando nomes de coluna
Envie vários campos de fatura para um script do R para fins de análise fora do Analytics. Use a opção KEEPTITLE para que as colunas possam ser referenciadas por nome no R:
Comando do Analytics
RCOMMAND FIELDS Código_Departamento Total_Fatura Número_Fatura TO "resultado_r" RSCRIPT "C:\scripts\r_scripts\análise.r" KEEPTITLE
Script do R (análise.r)
# Recupera número da fatura da segunda linha do quadro de dados no script do R
srcTable<-acl.readData()
srcTable["2","Número_Fatura"]
Envio de registros de fatura que excedem o valor de 1000,00 para o script do R
Envie vários campos de fatura para um script do R para fins de análise fora do Analytics. Use IF para limitar os registros enviados ao R. Somente os registros com um total de fatura acima de 1000,00 são enviados:
Comando do Analytics
RCOMMAND FIELDS Código_Departamento Total_Fatura Número_Fatura TO "resultado_r" IF Total_Fatura > 1000,00 RSCRIPT "C:\scripts\r_scripts\análise.r" KEEPTITLE
Script do R (análise.r)
# Recupera número da fatura da segunda linha do quadro de dados no script do R
srcTable<-acl.readData()
srcTable["2","Número_Fatura"]
Envio de registros de fatura e retorno de valores de fatura multiplicados
Envie vários campos de fatura para um script do R para fins de análise fora do Analytics. O script do R executa uma única ação em cada célula na coluna nomeada:
Comando do Analytics
RCOMMAND FIELDS Código_Departamento Total_Fatura Número_Fatura TO "resultado_r" RSCRIPT "C:\scripts\r_scripts\análise.r" KEEPTITLE
Script do R (análise.r)
# Retorna fatia da tabela do ACL com valor dobrado
srcTable<-acl.readData()
acl.output<-srcTable["Valor_Fatura"] * 2
Observações
Para obter mais informações sobre o funcionamento desse comando, consulte Executar scripts do R.
Referência aos dados do Analytics no script do R
A tabela do Analytics é passada ao script como um quadro de dados do R. Os quadros de dados são objetos de dados tabulares que podem conter colunas com modos ou tipos diferentes de dados.
Para trabalhar com o quadro de dados criado pelo Analytics em um script do R, chame a função acl.readData() e armazene o quadro de dados retornado em uma variável:
# armazena a tabela do Analytics em um quadro de dados denominado minhaTabela que pode ser referenciado em todo o script
minhaTabela<-acl.readData()
Para recuperar dados de uma célula na estrutura de dados, você pode usar uma das seguintes abordagens:
-
Uso de coordenadas de linha e coluna:
# Recupera o valor da primeira linha e segunda coluna do quadro de dados
minhaTabela[1,2]Nota
As coordenadas são baseadas na ordem de campos especificada no comando e não no layout da tabela ou na exibição aberta no momento.
-
Uso de nomes de linha e coluna:
# Recupera o valor da primeira linha e da coluna "títuloMinhaColuna" do quadro de dados
minhaTabela["1","títuloMinhaColuna"]É necessário especificar a opção KEEPTITLE do comando para usar nomes de colunas.
As linhas são chamadas de "1", "2", "3" e são incrementadas de acordo. Você também pode usar uma combinação de nomes e coordenadas.
Transferência de dados de volta para o Analytics
Para retornar um quadro de dados ou matriz ao Analytics e criar uma nova tabela, use a sintaxe a seguir:
# Passa o dataframe minhaNovaTabela para o Analytics para criar uma nova tabela
acl.output<-minhaNovaTabela
Nota
É necessário retornar um quadro de dados ou uma matriz ao Analytics quando o script do R termina. Verifique se as colunas do quadro de dados ou matriz contêm apenas valores atômicos e não listas, matrizes ou objetos não atômicos. Se não for possível converter os valores em tipos de dados do Analytics, o comando falhará.
Mapeamentos de tipo de dados
Os tipos de dados do Analytics são convertidos em tipos de dados do R usando um processo de tradução entre o projeto do Analytics e o script do R:
| Tipo de dados do Analytics | Tipo(s) de dados R |
|---|---|
| Lógico | Lógico |
| Numérico | Numérico |
| Caractere | Caractere |
| Datahora | Data, POSIXct, POSIXlt |
Desempenho e limites de tamanho de arquivo
O tempo que leva para executar seu script do R e processar os dados retornados aumenta para dados de entrada que ultrapassem 1 GB. O R não é compatível com arquivos de entrada de 2 GB ou mais.
O número de registros enviado para o R também afeta o desempenho. Para duas tabelas com o mesmo tamanho de arquivo, mas com contagem de registros diferente, o processamento da tabela com menos registros é mais rápido.
Processamento de dados de caracteres multibyte
Se você estiver enviando dados para o R em um conjunto de caracteres multibyte, como chinês, é preciso definir a localidade do sistema em seu script do R. Para enviar com sucesso uma tabela de dados multibyte para o R, a primeira linha do script do R deve conter esta função:
# Exemplo que define a localidade para chinesa
Sys.setlocale("LC_ALL","Chinese")
Para obter mais informações sobre Sys.setlocale( ), consulte a documentação do R.
Arquivo de log R
O Analytics registra em log as mensagens da linguagem R no arquivo aclrlan.log na pasta do projeto. Use esse arquivo de log para depurar erros do R.
