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

14.2.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:

• clickando el botón ;

• selecting features con la herramienta ^{Select By Expression…};

• editing attributes con p.ej. la herramienta ^{Field calculator};

• manipular parámetros de simbología, etiqueta o elemento de diseño con la herramienta ^{Data defined override} (ver Configuración de anulación definida por datos);

• construyendo una geometry generator symbol layer;

• haciendo algún geoprocessing.

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.

14.2.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:

Figura 14.65 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:

  • ^{Limpiar el editor de expresión}

  • crear y administrar expresiones de usuario

• 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 esperado de salida cuando está definiendo las propiedades de objeto definido por datos

  • una previsualización de salida actual de la expresión, evaluada en la primera entidad de la Capa de forma predeterminada. Puede examinar y evaluar otras entidades de la capa usando el cuadro combinado Objeto (los valores se toman de la propiedad nombre mostrado de la capa).

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

14.2.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 diálogo define el contexto: si está acostumbrado a SQL, probablemente conozca consultas del tipo seleccionar entidades de la capa donde condición o actualizar el conjunto de capas campo= nuevo_valor donde condición. Una expresión QGIS también necesita toda esta información, pero la herramienta que utiliza para abrir el cuadro de diálogo del generador de expresiones proporciona partes de ella. Por ejemplo, dando una capa(building) con un campo (height):

   • presionando la herramienta ^{Seleccionar 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 ^{Calculadora de campos`y escogiendo «altura» como :guilabel:`Actualizar campo existente}, ya proporcionas el comando «actualizar la altura del conjunto de edificios = ??? donde la altura> 20». Los únicos bits restantes que debe proporcionar en este caso es el nuevo valor, p. Ej. simplemente ingrese 50 para ajustar 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.

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

• In a print layout label, display the name of the «airports» features that are within the layout «Map 1» item:

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

14.2.1.4. Guardando expresiones

Usando el botón ^{Agregar expresión actual a las expresiones de usuario} sobre el marco del editor de expresión, puede guardar expresiones importantes a las que quiera acceder ágilmente. Estas están disponibles en el grupo expresiones de Usuario en el panel central. Ellas son guardadas en el perfil de usuario (archivo <userprofile>/QGIS/QGIS3.ini) y 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:

• ^{Agregar 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.

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

• ^{Eliminar la expresión seleccionada de las expresiones del usuario}

• ^{Importar expresiones de usuario} de un archivo .json en la carpeta del perfil del usuario actual

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

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

Figura 14.66 La pestaña Editor de funciones

Para crear una nueva función:

1. Presiona el botón ^{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 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 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 ^{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

Here’s a short example on how to create your own my_sum function that will operate with two values.

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

When using the args='auto' function argument the number of function arguments required will be calculated by the number of arguments the function has been defined with in Python (minus 2 - feature, and parent). The group='Custom' argument indicates the group in which the function should be listed in the Expression dialog.

It is also possible to add keywords arguments like:

• usesgeometry=True if the expression requires access to the features geometry. By default False.

• handlesnull=True if the expression has custom handling for NULL values. If False (default), the result will always be NULL as soon as any parameter is NULL.

• referenced_columns=[list]: An array of attribute names that are required to the function. Defaults to [QgsFeatureRequest.ALL_ATTRIBUTES].

The previous example function can then be used in expressions:

Figura 14.67 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.