13.1. Expresiones

En base a datos de capa y funciones predefinidas o definidas por el usuario, Expresiones ofrece una manera poderosa de manipular el valor de un atributo, la geometría y las variables con el objetivo de cambiar dinámicamente el estilo de geometría, el contenido o posición de la etiqueta, el valor para el diagrama, la altura de un elemento de diseño, seleccionar algunas funciones, crear campo virtual, …

Nota

Puede encontrar una lista de las funciones y variables predeterminadas para escribir expresiones en Lista de funciones, con información detallada y ejemplos.

13.1.1. El constructor de cadena de Expresión

El diálogo principal para construir expresiones, el :guilabel: Expression string builder está disponible desde muchas partes en QGIS y, en particular, se puede acceder mediante:

El cuadro de diálogo del generador de expresiones ofrece acceso a:

  • Expression tab que, gracias a una lista de funciones predefinidas, ayuda a escribir y verificar la expresión a usar;

  • Function Editor tab lo que ayuda a ampliar la lista de funciones mediante la creación de funciones personalizadas.

13.1.1.1. La Interfaz

La pestaña Expresión proporciona la interfaz principal para escribir expresiones usando funciones, campos de capa y valores. Contiene los siguientes controles:

../../../_images/function_list.png

Figura 13.1 La pestaña Expresión

  • Un área de editor de expresiones para escribir o pegar expresiones. Está disponible el autcompletado para acelerar la escritura de la expresión:

    • Las variables correspondientes, los nombres de las funciones y los nombres de campo para el texto de entrada se muestran a continuación: use las flechas Up y Down para examinar los elementos y presione Tab para insertar en la expresión o simplemente haga clic en el elemento deseado.

    • Los parámetros de la función son mostrados mientras los rellena.

    QGIS también verifica la corrección de la expresión y resalta todos los errores usando:

    • Underline: para funciones desconocidas, argumentos incorrectos o inválidos;

    • Marker: para cualquier otro error (por ejemplo, paréntesis faltante, carácter inesperado) en una sola ubicación.

    Truco

    Documenta tu expresion con comentarios

    Cuando se utiliza una expresión compleja, es una buena práctica agregar texto como un comentario de varias líneas o comentarios entrelíneas para ayudarlo a recordar.

    /*
Labels each region with its highest (in altitude) airport(s)
and altitude, eg 'AMBLER : 264m' for the 'Northwest Artic' region
*/
with_variable(
  'airport_alti', -- stores the highest altitude of the region
  aggregate(
    'airports',
    'max',
    "ELEV", -- the field containing the altitude
    -- and limit the airports to the region they are within
    filter := within( $geometry, geometry( @parent ) )
  ),
    aggregate( -- finds airports at the same altitude in the region
      'airports',
      'concatenate',
      "NAME",
      filter := within( $geometry, geometry( @parent ) )
        and "ELEV" = @airport_alti
    )
    || ' : ' || @airport_alti || 'm'
    -- using || allows regions without airports to be skipped
)

  • Sobre el editor de expresión, un conjunto de herramientas le ayuda:

  • Bajo el editor de expresión, encontrará:

    • Un conjunto de operadores básicos para ayudarle a construir la expresión

    • Una indicación del formato de salida esperado cuando se definen los datos de las propiedades de las características

    • Una Vista previa de salida de la expresión (hasta 60 caracteres), evaluada en la primera característica de la Capa por defecto. Para ver el texto de la vista previa de salida de más de 60 caracteres, puede situar el cursor sobre el texto para que aparezca una ventana emergente con toda la vista previa de salida. Para copiar el texto de la vista previa de salida en el portapapeles, haga clic con el botón derecho en el texto de la vista previa de salida y seleccione |editarCopiar| Copiar valor de expresión.

      Puede examinar y evaluar otras características de la capa utilizando el cuadro combinado Feature (los valores se toman de la propiedad de la capa nombre para mostrar).

      En caso de error, se lo indica y puede acceder a los detalles con el hiperenlace proporcionado.

  • Un selector de funciones muestra la lista de funciones, variables, campos … organizados en grupos. Hay un cuadro de búsqueda disponible para filtrar la lista y encontrar rápidamente una función o campo en particular. Al hacer doble clic en un elemento, se agrega al editor de expresiones.

  • Un panel de ayuda para cada elemento seleccionado en el selector de función.

    Truco

    Press¡iona Ctrl+Click cuando se pasa el nombre de una función en una expresión para mostrar automáticamente su ayuda en el cuadro de diálogo.

    El control de valores de un campo que se muestra cuando se selecciona un campo en el selector de funciones ayuda a obtener atributos de objetos:

    • Buscar un determinado valor de campo

    • Mostrar la lista de valores Todos únicos o 10 Muestras. También dsiponible con click derecho.

      Cuando el campo está mapeado con otra capa o un conjunto de valores, es decir, si el widget de campo es de tipo RelationReference, ValueRelation or ValueMap, es posible enumerar todos los valores del campo mapeado (de la capa, tabla o lista referenciada). Además, puede filtrar esta lista a checkbox Mostrar solo los valores en uso en el campo actual.

    DOble Click en un valor de campo en el control lo agrega al editor de expresión.

    Truco

    El panel derecho, mostrando funciones de ayuda o valores de campo, puede ser colapsado (invisible) en el diálogo. Presione el botón guilabel:Show Values o Show Help para restaurarlo.

13.1.1.2. Escribir una expresión

Las expresiones de QGIS son usadas para seleccionar objetos o establecer valores. Escribir una expresión en QGIS debe cumplir algunas reglas:

  1. El cuadro de diálogo define el contexto: si está acostumbrado a SQL, probablemente conozca consultas del tipo seleccione entidades de la capa donde condición o actualice el campo del conjunto de capas = nuevo_valor donde condición. Una expresión de QGIS también necesita toda esta información, pero la herramienta que usa para abrir el cuadro de diálogo del generador de expresiones proporciona partes de ella. Por ejemplo, dando una capa (edificios) con un campo (altura):

    • presionando la herramienta expressionSelectSeleccionar por expresión quiere decir que quiere «seleccionar objetos de buildings». La condición es la única información que necesita proporcionar en el control de texto de expresión, p.ej. tipo "height" > 20 para seleccionar buildings mas altos que 20.

    • con esta selección hecha, presionando el botón calculateField Field calculator y eligiendo «altura» como Actualizar campo existente, ya proporciona el comando «actualizar edificios establecer altura = ??? donde altura> 20». Los únicos bits restantes que debe proporcionar en este caso son el nuevo valor, por ejemplo, simplemente ingrese 50 en el cuadro de texto del editor de expresiones para establecer la altura de los edificios seleccionados previamente.

  2. Preste atención a las comillas: las comillas simples devuelven un literal, por lo que un texto colocado entre comillas simples ('145') se interpreta como una cadena. Las comillas dobles te darán el valor de ese texto, así que úsalas para los campos ("myfield"). Los campos también se pueden utilizar sin comillas (myfield). Sin comillas para números (3,16).

    Nota

    Las funciones normalmente toman como argumento una cadena para el nombre de campo. Haga:

    attribute( @atlas_feature, 'height' ) -- returns the value stored in the "height" attribute of the current atlas feature

    Y no:

    attribute( @atlas_feature, "height" ) -- fetches the value of the attribute named "height" (e.g. 100), and use that value as a field
                                      -- from which to return the atlas feature value. Probably wrong as a field named "100" may not exist.

Truco

Usar parámetros nombrados para facilitar la lectura de la expresión

Algunas funciones requieren la configuración de muchos parámetros. El motor de expresión admite el uso de parámetros con nombre. Esto significa que en lugar de escribir la expresión críptica clamp(1, 2, 9), puede usar ``clamp(min:=1, value:=2, max:=9) “”. Esto también permite cambiar los argumentos, p. Ej. ``clamp(value:=2, max:=9, min:=1) “”. El uso de parámetros con nombre ayuda a aclarar a qué se refieren los argumentos de una función de expresión, lo cual es útil cuando intentas interpretar una expresión más adelante.

13.1.1.3. Algunos caso de uso de expresiones

  • De la calculadora de Campo, calcular un campo «pop_density» usando los campos existentes «total_pop» y «area_km2»:

    "total_pop" / "area_km2"

  • Etiquetar o categorizar entidades basandose en sus áreas:

    CASE WHEN $area > 10 000 THEN 'Larger' ELSE 'Smaller' END

  • Actualice el campo «density_level» con categorías de acuerdo con los valores «pop_density»

    CASE WHEN "pop_density" < 50 THEN 'Low population density'
     WHEN "pop_density" >= 50 and "pop_density" < 150 THEN 'Medium population density'
     WHEN "pop_density" >= 150 THEN 'High population density'
END

  • Aplique un estilo categorizado a todas las características de acuerdo a si el precio promedio de su casa es menor o mayor a 10000€ por metro cuadrado

    "price_m2" > 10000

  • Usando la herramienta «Select By Expression…», seleccione todas las características que representan áreas de “High population density” and cuyo precio promedio de la vivienda es superior a 10000€ por metro cuadrado:

    "density_level" = 'High population density' and "price_m2" > 10000

    La expresión previa puede además ser usada para definir que entidades etiquetar o mostrar en el mapa.

  • Crear un símbolo diferente (tipo) para la capa, usando el generador de geometría:

    point_on_surface( $geometry )

  • Dando una entidad de punto, generar una línea cerrada (usando make_line) alrededor de su geometría:

    make_line(
  -- using an array of points placed around the original
  array_foreach(
    -- list of angles for placing the projected points (every 90°)
    array:=generate_series( 0, 360, 90 ),
    -- translate the point 20 units in the given direction (angle)
    expression:=project( $geometry, distance:=20, azimuth:=radians( @element ) )
  )
)

  • En una etiqueta de diseño de impresión, muestre el nombre de las entidades de los «aeropuertos» que se encuentran dentro del elemento «Mapa 1» del diseño:

    with_variable( 'extent',
               map_get( item_variables( 'Map 1' ), 'map_extent' ),
               aggregate( 'airports', 'concatenate', "NAME",
                          intersects( $geometry, @extent ), ' ,'
                        )
             )

13.1.1.4. Guardando expresiones

Uso de fileSave Add current expression to user expressions sobre el marco del editor de expresiones, puede guardar expresiones importantes a las que desea tener acceso rápido. Están disponibles en el grupo Expresiones de usuario en el panel central. Se guardan en el user profile (<userprofile>/QGIS/QGIS3.ini file) y están disponibles en todos los diálogos de expresión dentro de todos los proyectos del perfil de usuario actual.

Un conjunto de herramientas sobre el marco del editor de expresión le ayuda a administrar las expresiones de usuario:

  • fileSaveAgregar la expresión actual a las expresiones de usuario: almacenar la expresión en el perfil de usuario. Se puede agregar una etiqueta y un texto de ayuda para una fácil identificación.

  • symbologyEdit Editar expresión seleccionada de expresiones de usuario, así como su ayuda y su etiqueta

  • deleteSelected Eliminar la expresión seleccionada de las expresiones del usuario

  • sharingImport Importar expresiones de usuario de un archivo .json en la carpeta del perfil del usuario actual

  • sharingExport Exportar expresiones de usuario como un archivo``.json``; todas las expresiones de usuario en el archivo del perfil de usuario QGIS3.ini son compartidos

13.1.2. Editor de Funciones

Con la pestaña Function Editor, puedes escribir tus propias funciones en lenguaje Python. Esto proporciona una forma práctica y cómoda de abordar necesidades particulares que no estarían cubiertas por las funciones predefinidas.

../../../_images/function_editor.png

Figura 13.2 La pestaña Editor de funciones

Para crear una nueva función:

  1. Presiona el botón symbologyAdd New File.

  2. Ingrese un nombre para usar en el formulario que aparece y presione OK.

    Se agrega un nuevo elemento del nombre que proporcione en el panel izquierdo de la pestaña Function Editor; este es un archivo Python .py basado en el archivo de plantilla QGIS y almacenado en la carpeta /python/expressions en el directorio activo user profile.

  3. El panel derecho muestra el contenido del archivo: una plantilla de script de Python. Actualice el código y su ayuda según sus necesidades.

  4. Presione el botón start Save and Load Functions. La función que escribió se agrega al árbol de funciones en la pestaña Expression, por defecto bajo el grupo``Custom``.

  5. Disfruta tu nueva función.

  6. Si la función requiere mejoras, habilite la pestaña Function Editor, haga los cambios y presione de nuevo el botón start Save and Load Functions para hacerlos accesibles en el archivo, por lo tanto en cualquier pestaña de expresión.

Las funciones personalizadas de Python se almacenan en el directorio de perfil de usuario, lo que significa que en cada inicio de QGIS, cargará automáticamente todas las funciones definidas con el perfil de usuario actual. Tenga en cuenta que las nuevas funciones solo se guardan en la carpeta /python/expressions y no en el archivo del proyecto. Si comparte un proyecto que utiliza una de sus funciones personalizadas, también deberá compartir la carpeta:file:.py file in the /python/expressions.

Para borrar una función personalizada:

  1. Active la pestaña Editor de Función

  2. Seleccione la función de la lista

  3. Presione symbologyRemove Borrar función Seleccionada. La función se elimina de la lista y el archivo .py correspondiente se elimina de la carpeta del perfil de usuario.

Ejemplo

Aquí hay un breve ejemplo de como crear su propia función my_sum que operará con dos valores.

from qgis.core import *
from qgis.gui import *

@qgsfunction(args='auto', group='Custom')
def my_sum(value1, value2, feature, parent):
    """
    Calculates the sum of the two parameters value1 and value2.
    <h2>Example usage:</h2>
    <ul>
      <li>my_sum(5, 8) -> 13</li>
      <li>my_sum("field1", "field2") -> 42</li>
    </ul>
    """
    return value1 + value2

El decorador @qgsfunction acepta los siguientes argumentos:

  • args: el número de argumentos. Cuando se utiliza el argumento args='auto' el número de argumentos de la función requeridos se calculará por el número de argumentos con los que la función ha sido definida en Python (menos 2 - feature, y parent). Con args = -1, se acepta cualquier número de argumentos.

  • El argumento group indica el grupo en el que debe aparecer la función en el cuadro de diálogo Expresión.

  • usesgeometry=True si la expresión requiere acceso a la geometría de las entidades. Por defecto Falso.

  • handlesnull=True si la expresión tiene un manejo personalizado para valores NULOS. Si False (predeterminado), el resultado siempre será NULO tan pronto como cualquier parámetro sea NULO.

  • referenced_columns=[list]: Una matriz de nombres de atributos que se requieren para la función. El valor predeterminado es [QgsFeatureRequest.ALL_ATTRIBUTES].

La propia función admite los siguientes argumentos:

  • cualquier número y tipo de parámetros que desee pasar a su función, establecidos antes de los siguientes argumentos.

  • feature: el objeto espacial actual

  • parent: el objeto QgsExpression.

  • context: Si se encuentra un argumento llamado context en la última posición, esta variable contendrá un objeto QgsExpressionContext, que da acceso a diversa información adicional como variables de expresión. Por ejemplo context.variable( 'layer_id' )

La función de ejemplo anterior se puede usar en expresiones:

../../../_images/customFunction.png

Figura 13.3 Función personalizada agregada a la pestaña Expresión

Se puede encontrar más información sobre cómo crear código Python en Libro de Recetas para Desarrollador PyQGIS.