Guía de aprendizaje: adición de una función personalizada

Acerca de esta tarea

En esta guía de aprendizaje, está escribiendo una función personalizada, MultiplyByFactor, que multiplica un elemento de entrada por un valor de factor. Como parte del código de la función, defina cómo se representan los controles para los elementos de entrada y salida. Más adelante, especifique el elemento de entrada y el valor de factor.

Utilice el método execute_local_test para probar la función. Utilice este método para probar cualquier función derivada de las clases base en funciones de IoT. El método genera datos de ejemplo para una función localmente. Escribe los resultados en un archivo denominado df_test_entitity_for_function_name en el directorio de trabajo. Si la función funciona, regístrela con.

Por último, cree un tipo de dispositivo de robot de muestra en y aplique la nueva función MultiplyByFactor al tipo de dispositivo.

Esta guía de aprendizaje utiliza Pycharm IDE para crear el paquete de Python para la función personalizada. Si utiliza otro IDE o, asegúrese de utilizar Python 3.9.x con él.

De forma alternativa, aparte de esta guía de aprendizaje, un paquete de inicio de función personalizado está disponible en las funciones de IoT para ayudarle a empezar a crear sus propias funciones personalizadas.

Antes de empezar

Puede clonar un paquete iniciador y utilizarlo como paquete de ejemplo en el entorno local. La clonación de un paquete iniciador le proporciona una forma fácil de instalar los paquetes necesarios, incluidas las funciones de IoT, para la función personalizada. El paquete iniciador proporciona un ejemplo de la estructura de directorio necesaria para el paquete personalizado.

1. Instale Python 3.9.x en el entorno.
2. Instale GIT.
3. Instale el gestor de paquetes de pip3 para Python.
4. Instale un editor, como Xcode, para realizar actualizaciones de código.
5. Clone el paquete de inicio HelloWorld
   1. Abra una ventana de terminal.
   2. Cree una nueva carpeta de proyecto para el paquete iniciador. Por ejemplo, mkdir project.
   3. Vaya al directorio de proyecto. Por ejemplo, cd project.
   4. Clone el paquete iniciador. Escriba: git clone --branch starter_package https://github.com/ibm-watson-iot/functions.git
   5. Verifique que ha clonado el paquete iniciador en el directorio de proyecto.
   6. Cambie al directorio de funciones en el paquete iniciador. Escriba: cd functions
   7. Escriba: git status
   8. Copie la vía de acceso del directorio de trabajo para su uso posterior. Escriba pwd y copie la vía de acceso.
   9. Abra el archivo setup.py. El archivo setup.py define el nombre de paquete y la lista de paquetes necesarios para el proyecto.
   10. Establezca el parámetro name en custom{your_initials}. Sustituya la variable {your_initials} por sus iniciales o por otro valor exclusivo.
   11. En el repositorio ibm-watson-iot/functions , verifique que el paquete iotfunction es la versión correcta. Por ejemplo, para 8.8, el paquete debe pertenecer a la rama 8.8.X GitHub. No sustituya el x de la versión por otro valor. El siguiente texto es un ejemplo de archivo setup.py . El parámetro name se establece en customId y se utiliza la rama 8.7.X .

#!/usr/bin/env python 
from setuptools import setup, find_packages
setup(name='customld', version='0.0.1', packages=find_packages(),
install_requires=['iotfunctions@git+https://github.com/ibm-watson-iot/functions.git@8.7.x'])

1. Instale la edición de comunidad PyCharm.
2. En PyCharm, apunte el entorno al paquete iniciador que ha clonado. Pulse Abrir y localice el directorio que ha clonado.
3. Configure un nuevo entorno virtual Pycharm.
   1. Vaya a PyCharm > Preferencias > Proyecto <su_proyecto> > Intérprete de proyectos.
   2. Si está configurando un nuevo entorno virtual:
   3. Pulse el icono de valores y pulse Añadir.
   4. Especifique la ubicación de la carpeta del proyecto.
   5. Establezca el intérprete base en el directorio Python 3.9.x .
   6. Si tiene un entorno virtual existente, establezca el intérprete de proyecto en Python 3.x.
4. Ejecute el mandato siguiente para instalar el paquete iotfunctions en el entorno Python . Asegúrese de que utiliza el nombre de rama correcto para su versión.

       pip3 install git+https://github.com/ibm-watson-iot/functions.git@8.7.x --upgrade

Asegúrese de que siempre utiliza la versión más reciente de las funciones de IoT. Compruebe la versión de cada módulo Python compatible con. Si no utiliza la versión exacta compatible, la ejecución secuencial podría interrumpirse.

Pasos

Complete estos pasos para aplicar un cálculo a los datos de ejemplo utilizando una función personalizada.

Paso 1: definir el cálculo

Una empresa que desarrolla brazos robóticos está introduciendo un nuevo brazo robótico y está probando que lo realiza así como el robótico existente. En las primeras pruebas, el equipo descubrió que para algunos de los robots, la distancia recorrida durante las pruebas era demasiado alta. Después de la investigación, el equipo descubrió que las herramientas utilizadas para realizar las pruebas estaban añadiendo un retraso a la velocidad y al tiempo de recorrido del robot. El gestor de operaciones quiere ajustar ambos valores por un factor de 2 pero quiere que la flexibilidad cambie ese valor más tarde.

El analista identifica que un cálculo similar puede resultar útil en otros cálculos y generaliza la función escribiendo una clase MultiplyByFactor.

distance * factor

Paso 2: empaquetar la función y almacenarla GitHub.

1. Cree un nuevo repositorio en GitHub para el paquete iniciador que ha clonado.
   1. El repositorio debe tener un URL al que se pueda acceder desde una instalación de pip.
   2. Se recomienda que el repositorio sea privado. Puede acceder al repositorio utilizando una señal de acceso personal.
2. Añada un archivo al repositorio para crear la rama maestra. Por ejemplo, añada un archivo vacío denominado test.md y pulse Commit new file.
3. Abra el proyecto en PyCharm localmente para su edición.
4. Verifique que el proyecto tenga la siguiente estructura de directorios y archivos:

   functions
   |
   |__ setup.py
   |
   |__ scripts
     |
     |_ local_test_of_function.py
   |
   |__ custom
     |
     |_ functions.py
     |_  __init__.py

5. Cambie el nombre del módulo, custom, por un nombre exclusivo, como customyourinitials. Por ejemplo, customld.
6. Cree un módulo de función multiplybyfactor<yourinitials>.py en custom<yourinitials> y pegue el código siguiente. Actualice las variables en <> para que coincidan con el entorno. Por ejemplo, si el código está en GitHub, puede establecer PACKAGE_URL en 'git+https://<XXXXXX>@github.com/github.com/jones/starter@starter_package'.

   En esta función, implementa dos métodos. El cálculo se añade al método execute. Los argumentos de entrada y salida se establecen para la función en el método build_ui. Estos argumentos se configuran mediante la interfaz de usuario de configuración.

   import inspect
   import logging
   import datetime as dt
   import math
   from sqlalchemy.sql.sqltypes import TIMESTAMP,VARCHAR
   import numpy as np
   import pandas as pd
   
   from iotfunctions.base import BaseTransformer
   from iotfunctions import ui
   
   logger = logging.getLogger(__name__)
   
   # Specify the URL to your package here.
   # This URL must be accessible via pip install.
   # Example assumes the repository is private.
   # Replace XXXXXX with your personal access token.
   # After @ you must specify a branch.
   
   PACKAGE_URL = 'git+https://XXXXXX@github.com/<user_id><path_to_repository>@starter_package'
   
   class MultiplyByFactor<YourInitials>(BaseTransformer):
   
       def __init__(self, input_items, factor, output_items):
   
           self.input_items = input_items
           self.output_items = output_items
           self.factor = float(factor)
           super().__init__()
       def execute(self, df):
           df = df.copy()
           for i,input_item in enumerate(self.input_items):
               df[self.output_items[i]] = df[input_item] * self.factor
           return df
   
       @classmethod
       def build_ui(cls):
           #define arguments that behave as function inputs
           inputs = []
           inputs.append(ui.UIMultiItem(
                   name = 'input_items',
                   datatype=float,
                   description = "Data items adjust",
                   output_item = 'output_items',
                   is_output_datatype_derived = True)
                         )        
           inputs.append(ui.UISingle(
                   name = 'factor',
                   datatype=float)
                         )
           outputs = []
           return (inputs,outputs)   

Paso 3: Guardar sus credenciales en un archivo

Establecer credenciales para conectarse a.

1. Descargue el archivo credentials_as.json.
2. Sustituya las variables por los datos y, a continuación, guarde el archivo en la máquina local.

El archivo de credenciales se utiliza para ejecutar o probar la función localmente. No envíe este archivo al repositorio externo en el Paso 4.

Paso 4: Envíe los cambios locales en el repositorio de GitHub

Verifique que ha completado estos pasos:

• Los archivos que ha modificado siguen apuntando al repositorio de GitHub del que ha clonado el código. Cambie el repositorio remoto al repositorio de GitHub.
• Verifique que el archivo de credenciales no esté incluido con el código de función antes de confirmar los cambios en el directorio externo.

Envíe el código de función a su repositorio externo en GitHub.

1. Abra una ventana de terminal en la carpeta del proyecto.
2. Especifique: git remote -v. El repositorio remoto sigue apuntando a https://github.com/ibm-watson-iot/functions
3. Cambie el URL de origen remoto utilizando los mandatos siguientes:

   git remote set-url origin URL_To_YOUR_GITHUB_REPOSITORY

   Confirme que los URL de Recuperar y Enviar apuntan a su repositorio.
4. Añada el remoto en sentido ascendente utilizando el mandato siguiente. Especifique:

   git remote add upstream https://github.com/ibm-watson-iot/functions.git

5. Añada sus archivos a GIT y confírmelos.
   1. En PyCharm, seleccione el directorio custom<your_initials>.
   2. Seleccione Git > Añadir.
   3. Seleccione Git > Confirmar.
   4. En la ventana Confirmar cambios, pulse Confirmar.
   5. Seleccione Git > Repositorio > Enviar.
   6. Pulse Enviar.
6. Verifique que el módulo se haya enviado a una rama starter_package en el repositorio.

Paso 5: Instalar la función personalizada en el entorno local

Instale la función personalizada en el entorno local. Actualice las variables en <> para que coincidan con el entorno.

pip3 install git+https://<XXXXXX>@github.com/<user_id><path_to_repository>@starter_package --upgrade

Por ejemplo:

pip3 install git+https://<XXXXXX>@github.com/jones/starter@starter_package --upgrade

Sustituya < xxxxxx> por su señal de acceso personal. < /xxxxxx>

Paso 6: Pruebe su función personalizada localmente.

1. Cree un script denominado test_my_custom_function.py en la carpeta scripts. En el script, importe las bibliotecas y los paquetes de Python:

   import datetime as dt
   import json
   import pandas as pd
   import numpy as np
   from sqlalchemy import Column, Integer, String, Float, DateTime, Boolean, func
   from iotfunctions.base import BaseTransformer
   from iotfunctions.metadata import EntityType
   from iotfunctions.db import Database
   from iotfunctions import ui

2. Conectar a. En el script test_my_custom_function.py, añada:

   with open('credentials_as.json', encoding='utf-8') as F:
     credentials = json.loads(F.read())
   db_schema = None
   db = Database(credentials=credentials)

3. Importar y crear una instancia de la función. En el script test_my_custom_function.py, añada el código siguiente. Actualice las variables en <> para que coincidan con el entorno.

   from custom<yourinitials>.multiplybyfactor<yourinitials> import MultiplyByFactor<YourInitials>
   fn = MultiplyByFactor<YourInitials>(
       input_items = ['speed', 'travel_time'],
       factor = '2',
       output_items = ['adjusted_speed', 'adjusted_travel_time']
                 )
   df = fn.execute_local_test(db=db, db_schema=db_schema, generate_days=1,to_csv=True)
   print(df)

4. Ejecute el script desde la línea de mandatos. Los resultados del marco de fecha se guardan en un archivo .csv . Busque df_test_entity_for_multiplybyfactor<your_initials>.csv en el directorio de scripts. Especifique:

   python3 test_my_custom_function.py

Paso 7: Registre su función personalizada.

1. Cree un script denominado register_my_custom_function.py en la carpeta scripts. En el script, importe las bibliotecas y los paquetes de Python:

   import datetime as dt
   import json
   import pandas as pd
   import numpy as np
   from sqlalchemy import Column, Integer, String, Float, DateTime, Boolean, func
   from iotfunctions.base import BaseTransformer
   from iotfunctions.metadata import EntityType
   from iotfunctions.db import Database
   from iotfunctions import ui

2. Conectar a. En el script register_my_custom_function.py, añada:

   with open('credentials_as.json', encoding='utf-8') as F:
     credentials = json.loads(F.read())
   db_schema = None
   db = Database(credentials=credentials)
   ``

3. En el script register_my_custom_function.py, para registrar la función, añada el código siguiente. Actualice las variables en <> para que coincidan con el entorno.

   from custom<yourinitials>.multiplybyfactor<yourinitials> import MultiplyByFactor<YourInitials>
   
   db.register_functions([MultiplyByFactor<YourInitials>])

4. Ejecute el script desde la línea de mandatos. Por ejemplo:

   python3 register_my_custom_function.py

Paso 8: Cree un tipo de dispositivo de ejemplo.

1. En la página Configuración, en la pestaña Tipos de dispositivos, haga clic en Añadir tipo de dispositivo + para añadir un nuevo tipo de dispositivo.
2. Seleccione la plantilla de tipo de muestra Robot industrial.
3. Asigne un nombre al tipo de dispositivo en el campo Nombre del tipo de dispositivo.
4. Pulse Crear.
5. Seleccione el tipo de dispositivo de muestra recién creado en Tipos de dispositivos, haga clic en el botón de las elipses (3 puntos dispuestos verticalmente) y seleccione Editar, esto abrirá la pestaña Datos para el tipo de dispositivo de muestra.

Las métricas tardan hasta 5 minutos en generarse.

Paso 9: Aplique la función personalizada al tipo de dispositivo.

1. Si no ha creado una métrica distance, añádala. Siga los pasos de la Guía de aprendizaje: adición de expresiones
2. En la pestaña Datos , pulse Crear métrica.
3. Seleccione la función MultiplyByFactor<YourInitials> en el catálogo.
4. Establezca el ámbito y, a continuación, pulse Siguiente.
5. En el campo de factor, especifique 2.
6. En el campo input_item, seleccione distance.
7. Haga clic en Siguiente.
8. Cambie el nombre de la salida por 'adjusted_distance'.
9. Pulse Crear.
10. En la lista de elementos de datos, seleccione adjusted_distance. Espere hasta 5 minutos para evaluar la función personalizada con los datos de muestra.