12.1. Espressioni

Il Calcolatore di campi
Editor delle Funzioni

Basate sui dati dei layer e sulle funzioni predefinite o definite dall’utente, le Espressioni offrono un modo potente per manipolare il valore degli attributi, la geometria e le variabili al fine di cambiare dinamicamente lo stile della geometria, il contenuto o la posizione dell’etichetta, il valore del diagramma, la quota di un oggetto del layout, selezionare alcuni elementi, creare un campo virtuale, …

Nota

Una lista delle funzioni e delle variabili predefinite per scrivere espressioni può essere trovata in Lista delle funzioni, con informazioni dettagliate ed esempi.

12.1.1. Il Calcolatore di campi 

La finestra di dialogo principale per la creazione di espressioni Calcolatore di campi è disponibile da molte parti in QGIS e, in particolare, puoi accederci:

facendo clic sul pulsante ;
selecting features con lo strumento ^{Seleziona con espressione…};
Modifica attributi per esempio con il ^{Calcolatore di campi} ;
nella manipolazione dei parametri di simbologia, di etichetta o del layout con lo strumento ^{Sovrascrittura definita dai dati} (vedi Impostazione Sovrascrittura definita dai dati);
nel costruire geometry generator un layer di simboli;
nell’attivare alcuni geoprocessing.

Le finestre di dialogo del Costruttore di Espressioni offrono l’accesso a:

Expression tab che, grazie ad un elenco di funzioni predefinite, aiuta a scrivere e controllare l’espressione da utilizzare;
Function Editor tab delle funzioni che consente di ampliare l’elenco delle funzioni creando quelle personalizzate.

12.1.1.1. L’Interfaccia 

La scheda Espressione fornisce l’interfaccia principale per scrivere espressioni utilizzando funzioni, campi del layer e valori. Contiene i seguenti widget:

../../../_images/function_list.png — Fig. 12.1 La scheda Espressioni

Un’area di editing di espressioni per digitare o copiare le espressioni. L’autocompletamento è disponibile per velocizzare la scrittura delle espressioni:
- Le variabili, i nomi delle funzioni e dei campi corrispondenti al testo di input sono mostrati di seguito: usare le frecce Up e Down per sfogliare gli elementi e premere Tab per inserireli nell’espressione o semplicemente cliccare sull’elemento desiderato.
- I parametri delle funzione vengono visualizzati durante la digitazione.
QGIS controlla anche la correttezza dell’espressione ed evidenzia tutti gli errori utilizzando:
- Sottolineatura: per funzioni sconosciute, argomenti errati o non corretti;
- Simbolo: per ogni altro errore (es. parentesi mancante, carattere imprevisto) in una singola posizione.
Suggerimento

Documentare le tue espressioni con i commenti

Quando si usa un’espressione complessa, è buona pratica aggiungere testo sia come commento multilinea che come commento in linea per aiutarti a ricordare.
```
/*
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
)
```
Sopra l’editor di espressioni, una serie di strumenti ti aiutano:
- ^{Cancella l’editor espressione}
- creare e manipolare le user expressions
Sotto l’editor di espressioni, trovi:
- un insieme di operatori di base per aiutarti a costruire l’espressione
- un’indicazione del formato in uscita previsto quando si definiscono i dati delle proprietà degli elementi.
- un risultato in Anteprima dell’espressione, valutata sul primo elemento del Layer predefinito. Puoi sfogliare e valutare altre proprietà del layer usando il menu a tendina Elemento (i valori sono presi dal display name in proprietà del layer).
  
  In caso di errore, lo indica e si può accedere ai dettagli con il link ipertestuale fornito.
Un selettore di funzioni visualizza l’elenco di funzioni, variabili, campi…. organizzati in gruppi. Una casella di ricerca è disponibile per filtrare l’elenco e trovare rapidamente una particolare funzione o campo. Facendo doppio clic su un elemento lo aggiunge all’editor di espressioni.
Un pannello di aiuto visualizza la guida per ogni voce selezionata nel selettore di funzione.

Suggerimento

Premi Ctrl+Click quando passi con il mouse sul nome di una funzione in un’espressione per visualizzare automaticamente il suo aiuto nella finestra di dialogo.

Il widget dei valori di un campo mostrato quando un campo è selezionato nel selettore di funzioni aiuta a cercare gli attributi degli elementi:
- Cercare un particolare valore di campo
- Visualizza l’elenco di Tutti i Valori Univoci o di 10 Campioni. Disponibile anche con il tasto destro del mouse.
  
  Quando il campo è mappato con un altro layer o un insieme di valori, ad esempio se il field widget è di tipo RelationReference, ValueRelation o ValueMap, è possibile elencare tutti i valori del campo mappato (dal layer, tabella o lista di riferimento). Inoltre, puoi filtrare questa lista con Mostra solo i valori in uso nel campo corrente.
Il doppio clic sul valore di un campo nel widget lo aggiunge all’editor di espressioni.

Suggerimento

Il pannello di destra, che mostra le funzioni di aiuto o i valori del campo, può essere chiuso (invisibile) nella finestra di dialogo. Premi il pulsante Mostra Valori o Mostra Guida per recuperarlo.

12.1.1.2. Scrivere una espressione 

Le espressioni di QGIS sono usate per selezionare elementi o impostare valori. Scrivere un’espressione in QGIS segue alcune regole:

La finestra di dialogo definisce il contesto: se siete abituati a SQL, probabilmente conoscete query del tipo select features from layer where condition o update layer set field = new_value where condition. Anche un’espressione QGIS ha bisogno di tutte queste informazioni, ma lo strumento che usi per aprire la finestra di dialogo del costruttore di espressioni ne fornisce alcune parti. Per esempio, avendo un layer (buildings) con un campo (height):
- Usando lo strumento ^{Seleziona per espressione} significa che vuoi «selezionare gli elementi da buildings». La condizione è l’unica informazione che devi fornire nel widget di testo dell’espressione, ad esempio scrivi "height" > 20 per selezionare gli edifici che sono più alti di 20.
- con questa selezione fatta, premendo il pulsante :sup: Calcolatore di campi e scegliendo «altezza» come Aggiornamento campo esistente, si fornisce già il comando «aggiorna edifici set altezza = ??? dove altezza > 20». L’unico elemento rimanente che devi fornire in questo caso è il nuovo valore, ad esempio inserisci semplicemente 50 nella casella di testo dell’editor di espressioni per impostare l’altezza degli edifici precedentemente selezionati.

Fai attenzione alle virgolette: le virgolette singole restituiscono una stringa carattere, quindi un testo posto tra virgolette singole ('145') viene interpretato come una stringa. I doppi apici ti daranno il valore di quel testo, quindi usali per i campi ("myfield"). I campi possono anche essere usati senza virgolette (myfield). Niente virgolette per i numeri (3.16).

Nota

Le funzioni normalmente richiedono come parametro una stringa per il nome del campo. Fai:

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

e non:

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.

Suggerimento

Usare i parametri in modo esplicito per facilitare la lettura delle espressioni

Alcune funzioni richiedono l’impostazione di molti parametri. Il motore delle espressioni supporta l’uso di parametri con nomi espliciti. Questo significa che invece di scrivere la criptica espressione clamp( 1, 2, 9), puoi usare clamp( min:=1, value:=2, max:=9). Questo permette anche di cambiare ordine agli argomenti, ad esempio clamp( value:=2, max:=9, min:=1). L’uso di parametri con nome aiuta a chiarire a cosa si riferiscono gli argomenti di una funzione di espressione, il che è utile quando si cerca di interpretare un’espressione in seguito!

12.1.1.3. Alcuni casi di uso di espressioni 

Dal calcolatore di campi, calcola un campo «pop_density» usando i campi esistenti «total_pop» e «area_km2»:
```
"total_pop" / "area_km2"
```
Etichetta o categorizza gli elementi in base alla loro area:
```
CASE WHEN $area > 10 000 THEN 'Larger' ELSE 'Smaller' END
```

Aggiornare il campo «density_level» con le categorie in base ai valori «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

Applicare uno stile categorizzato a tutte le geometrie in base al fatto che il prezzo medio della casa sia più piccolo o superiore a 10000€ per metro quadrato:
```
"price_m2" > 10000
```
Utilizzando lo strumento «Seleziona per espressione …», selezionare tutte le geometrie che rappresentano aree di «Alta densità di popolazione» e il cui prezzo medio di casa è superiore a 10000€ per metro quadrato:
```
"density_level" = 'High population density' and "price_m2" > 10000
```
L’espressione precedente potrebbe anche essere usata per definire quali elementi etichettare o mostrare sulla mappa.
Creare un simbolo diverso (tipo) per il layer, usando il generatore di geometrie:
```
point_on_surface( $geometry )
```

Dato un elemento puntuale, genera una linea chiusa (usando make_line) intorno alla sua geometria:

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 un’etichetta del layout di stampa, visualizzare il nome degli elementi » airports» che si trovano all’interno dell’elemento » Map 1 » del layout:

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

12.1.1.4. Salvare le Espressioni 

Usando il pulsante ^{Aggiungi l’espressione corrente alle espressioni utente} sopra il riquadro dell’editor di espressioni, puoi salvare le espressioni importanti a cui vuoi avere accesso rapido. Queste sono disponibili nel gruppo Espressioni utente nel pannello centrale. Sono salvate sotto il user profile (<userprofile>/QGIS/QGIS3.ini file) e disponibili in tutte le finestre di dialogo delle espressioni all’interno di tutti i progetti del profilo utente corrente.

Un insieme di strumenti disponibili sopra la cornice dell’editor di espressioni ti aiuta a gestire le espressioni utente:

^{Aggiungi l’espressione corrente alle espressioni dell’utente}: memorizza l’espressione nel profilo dell’utente. Un’etichetta e un testo di aiuto possono essere aggiunti per una facile interpretazione.
^{Modifica l’espressione selezionata dalle espressioni utente}, così come il relativo testo di aiuto e l’etichetta
^{Rimuovi l’espressione selezionata dalle espressioni utente}
^{Importa le espressioni utente} da un file .json nella cartella del profilo utente attivo
^{Esporta Espressioni Utente} come file .json; tutte le espressioni utente sono condivise nel profilo utente QGIS3.ini

12.1.2. Editor delle Funzioni 

Con la scheda Editor delle Funzioni, puoi scrivere le tue funzioni nel linguaggio Python. Ciò fornisce un modo pratico e comodo per affrontare esigenze particolari che non sarebbero coperte dalle funzioni predefinite.

../../../_images/function_editor.png — Fig. 12.2 La scheda Editor delle Funzioni

Per creare una nuova funzione:

Premi il pulsante ^{Nuovo File}.
Inserisci un nome da utilizzare nel modulo che compare e premi OK.

Un nuovo oggetto con il nome da te fornito viene aggiunto nel pannello sinistro della scheda Editor delle Funzioni; si tratta di un file .py basato sul file del modello predefinito di QGIS e memorizzato nella cartella /python/expressions sotto la directory attiva user profile.
Il pannello di destra mostra il contenuto del file: un template di script python. Aggiorna il codice e il suo aiuto in base alle tue esigenze.
Premi il pulsante Salva e Carica Funzioni. La funzione scritta viene aggiunta all’albero delle funzioni nella scheda Espressione, di default nel gruppo Custom.
Goditi la tua nuova funzione.
Se la funzione necessita di miglioramenti, abilita la scheda Editor delle Funzioni, fai le modifiche e premi nuovamente il pulsante Salva e Carica Funzioni per renderle disponibili nel file, quindi in qualsiasi scheda di espressione.

Le funzioni personalizzate Python sono memorizzate nella directory del profilo utente, il che significa che ad ogni avvio di QGIS, caricherà automaticamente tutte le funzioni definite con il profilo utente corrente. Tieni presente che le nuove funzioni vengono salvate solo nella cartella /python/expressions e non nel file di progetto. Se condividi un progetto che utilizza una delle tue funzioni personalizzate, dovrai anche condividere il file .py nella cartella /python/expressions.

Per eliminare una funzione personalizzata:

Abilita la scheda Editor delle Funzioni.
Seleziona la funzione nella lista
Premi il ^{Rimuove il file funzioni selezionato}. La funzione viene rimossa dalla lista e il file .py corrispondente viene eliminato dalla cartella del profilo utente.

Esempio

Ecco un breve esempio su come creare la propria funzione my_sum che opererà con due valori.

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

Quando si usa il parametro args='auto' per la funzione il numero di argomenti della funzione richiesti sarà calcolato dal numero di argomenti con cui la funzione è stata definita in Python (meno 2 - feature e parent). L’argomento group='Custom' indica il gruppo in cui la funzione dovrebbe essere elencata nella finestra di dialogo Espressione.

È anche possibile aggiungere argomenti a parole chiave come:

usesgeometry=True se l’espressione richiede l’accesso alla geometria dell’elemento. Per default False.
handlesnull=True se l’espressione ha una gestione personalizzata per i valori NULL. Se False (default), il risultato sarà sempre NULL ogni volta che qualsiasi parametro è NULL.
referenced_columns=[elenco]: Un array di nomi di attributi che sono richiesti alla funzione. Il valore predefinito è [QgsFeatureRequest.ALL_ATTRIBUTES].

La funzione dell’esempio precedente può quindi essere utilizzata nelle espressioni:

../../../_images/customFunction.png — Fig. 12.3 Funzione personalizzata aggiunta alla scheda Espressione

Ulteriori informazioni sulla creazione di codice Python possono essere trovate nel PyQGIS cookbook.

12.1. Espressioni

12.1.1. Il Calcolatore di campi

12.1.1.1. L’Interfaccia

12.1.1.2. Scrivere una espressione

12.1.1.3. Alcuni casi di uso di espressioni

12.1.1.4. Salvare le Espressioni

12.1.2. Editor delle Funzioni