> For the complete documentation index, see [llms.txt](https://docs.geopard.tech/geopard-tutorials/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.geopard.tech/geopard-tutorials/it/tour-del-prodotto-app-web/equation-based-analytics/catalog-of-custom-functions.md).

# Catalogo di funzioni personalizzate

Queste funzioni incapsulano codice Python complesso, consentendoti di implementare con facilità manipolazioni e calcoli sofisticati sui dati.

GeoPard offre un catalogo completo di funzioni personalizzate progettate per migliorare la leggibilità e le funzionalità delle analisi basate su equazioni. Queste funzioni racchiudono complesse `python` operazioni, consentendo di applicare con facilità manipolazioni dei dati e calcoli sofisticati.

### Inserisci equazione

<figure><img src="https://docs.geopard.tech/~gitbook/image?url=https%3A%2F%2F3272281156-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FYICBELdyAXXebKAzfLOR%252Fuploads%252FdHTdBE1CN2gSJbE7Bfo0%252Fimage.png%3Falt%3Dmedia%26token%3Dd8e3544f-feca-43a6-b6a1-f1305068de88&#x26;width=768&#x26;dpr=4&#x26;quality=100&#x26;sign=508ec9e0&#x26;sv=2" alt=""><figcaption><p>Inserisci un’equazione</p></figcaption></figure>

L’elenco delle funzioni predefinite disponibili in GeoPard per creare equazioni più intuitive e facili da gestire è incluso nel pacchetto `geopard` :

### fill\_gaps\_with\_k\_neighbors

```python
# input_data è un layer attributo del Dataset (ad es. Resa, NDVI)
filled_layer = geopard.fill_gaps_with_k_neighbors(yield_layer, k=5)
```

Questa funzione ripristina i dati mancanti o i valori zero in un dataset utilizzando l’algoritmo K-Neighbors. Specificando la variabile `input_data` (un Dataset con l’attributo selezionato) e il numero di vicini `k`, puoi riempire facilmente i valori mancanti, garantendo continuità e integrità dei dati.

Questa funzione è efficace quando le lacune nei dati sono distribuite nel campo e non concentrate in una particolare porzione del suo perimetro.

### determine\_data\_similarity

```python
similarity = geopard.determine_data_similarity(yield_2023, yield_2024)
```

Usa questa funzione per calcolare la similarità pixel per pixel tra due Dataset. Le variabili `data_layer_1` e `data_layer_2` devono rappresentare la **stessa misurazione** nelle **stesse unità di misura** per garantire un confronto significativo. Fornendo le variabili `data_layer_1` e `data_layer_2` associate ai Dataset, puoi generare una mappa di similarità con valori compresi tra 0 e 1, utile per studi comparativi e il riconoscimento di pattern.

### determine\_data\_similarity\_from\_normalized

```python
layer_1_norm = geopard.normalize_data(layer_1)
layer_2_norm = geopard.normalize_data(layer_2)

similarity = geopard.determine_data_similarity_from_normalized(layer_1_norm, layer_2_norm)
```

Usa questa funzione per calcolare la similarità pixel per pixel tra due dataset normalizzati. La normalizzazione è consigliata quando i layer originali `data_layer_1` e `data_layer_2` hanno scale o unità di misura diverse. Fornendo questi dataset come input, la funzione genera una mappa di similarità con valori compresi tra 0 e 1, adatta a studi comparativi, al riconoscimento di pattern e all’analisi della coerenza spaziale.

### determine\_low\_high\_similarity

```python
zones = geopard.determine_low_high_similarity(soil_ph, yield_layer)
```

Questa funzione valuta la similarità tra valori bassi e alti di due Dataset. Inserendo le variabili `data_layer_1` e `data_layer_2` associate ai Dataset, ottieni una mappa di similarità classificata che indica combinazioni quali basso-basso, basso-alto, alto-basso e alto-alto, utile per classificare i dati in modo dettagliato.

### get\_value\_for\_zone

```python
zone_3_values = geopard.get_value_for_zone(yield_layer, zone_map, zone_id=3)
```

Usa questa funzione per estrarre tutti i valori di un attributo del Dataset all’interno di una singola zona. Specifica `data_layer` (il layer attributo), `zones_layer` (la mappa delle zone) e `zone_id` (il numero della zona) per isolare i valori da analizzare, come resa, dose di applicazione o dose di semina, all’interno della zona.

### drop\_value

```python
clean_layer = geopard.drop_value(elevation_layer, value_to_drop=0)
```

Questa funzione consente di rimuovere valori specifici da un attributo del dataset. Specificando `data_layer` e `value_to_drop`, è possibile ripulire il dataset eliminando tali valori dal risultato, sostituendoli tecnicamente con `NaN`.

### normalize\_data

```python
ndvi_normalized = geopard.normalize_data(ndvi_layer)
```

Normalizza un attributo del dataset con questa funzione. Passando `data_layer`, è possibile scalare i dati a un intervallo standardizzato da 0 a 1, facilitando il confronto e l’integrazione tra dataset diversi.

### calculate\_total\_applied\_fertilizer

```python
applications = [urea_rate, map_rate]
coefficients = [1.0, 1.0]  # use 1.0 to keep units, or adjust for product concentration

total_applied = geopard.calculate_total_applied_fertilizer(applications, coefficients)
```

Calcola la quantità totale di fertilizzante applicata per unità di superficie (ad esempio, in kg/ha, l/ha, gal/ac e così via). Fornendo `application_list` dataset con attributi AppliedRate `active_ingredient_coefficient_list` corrispondenti ai prodotti fertilizzanti, è possibile ottenere la quantità totale effettiva di fertilizzante applicata in unità di massa o volume (ad esempio, in kg, l, gal e così via).

### calculate\_total\_applied\_nitrogen

```python
applications = [urea_rate, uan_rate]
nitrogen_coefficients = [0.46, 0.32]  # N fraction (active ingredient) in each product

N_total_applied = geopard.calculate_total_applied_nitrogen(applications, nitrogen_coefficients)
```

Calcola con questa funzione la quantità totale di azoto applicata in kg/ha. Fornendo `application_list` dataset con attributi AppliedRate `active_ingredient_coefficient_list` corrispondenti ai prodotti azotati, è possibile convertire l’azoto effettivamente applicato in kg/ha e calcolare con precisione la quantità totale di azoto applicata, un dato essenziale per la pianificazione agronomica e le valutazioni di sostenibilità. Il risultato viene utilizzato come `N_total_applied` in[`geopard.calculate_nitrogen_use_efficiency`](#calculate_nitrogen_use_efficiency).

### calculate\_nitrogen\_uptake

```python
N_uptake = geopard.calculate_nitrogen_uptake(
    yield_wet_tha=yield_layer,
    moisture_pct=moisture_layer,
    protein_pct=protein_layer,
    protein_crop_correction_coefficient=6.25
)
```

Determina con questa funzione l’assorbimento di azoto in kg/ha. Specificando `yield_wet_tha`, `moisture_pct`, `protein_pct` dal dataset della resa e `protein_crop_correction_coefficient` che rappresenta il legame tra la proteina e l'assorbimento dell'azoto, è possibile valutare l'efficienza d'uso dell'azoto nella produzione delle colture. Il risultato viene utilizzato come `N_uptake` in[`geopard.calculate_nitrogen_use_efficiency`](#calculate_nitrogen_use_efficiency) .

### calculate\_nitrogen\_use\_efficiency

```python
NUE_pct = geopard.calculate_nitrogen_use_efficiency(N_total_applied, N_uptake)
```

Valuta l'efficienza d'uso dell'azoto in percentuale con questa funzione. Inserendo [`N_total_applied`](#calculate_total_applied_nitrogen) e [`N_uptake`](#calculate_nitrogen_uptake) come variabili (ottenute da funzioni precedenti), è possibile misurare l'efficacia dell'applicazione di azoto e ottimizzare l'uso dei fertilizzanti.

### calculate\_costs

```python
rates = [seed_rate, fertilizer_rate]
prices = [1.2, 0.8]  # price per unit for each rate layer
costs = geopard.calculate_costs(rates, prices)
```

Calcola i costi totali in base alle dosi di applicazione e ai prezzi con questa funzione. Specificando un `application_rate_list` di dataset con gli attributi AppliedRate e il corrispondente `price_per_unit_list`, è possibile sommare le spese relative alle diverse attività agricole, per gestire il budget e pianificare le finanze. Il risultato viene utilizzato come `costs` in[`geopard.calculate_profit`](#calculate_profit).

### calculate\_revenue

```python
revenue = geopard.calculate_revenue(yield_as_mass=yield_layer, yield_price_per_unit=0.25)
```

Calcola i ricavi del dataset di resa con questa funzione. Inserendo `yield_as_mass` associato all'attributo Yield del dataset di resa e il `yield_price_per_unit`, è possibile stimare i ricavi generati dalla produzione delle colture e agevolare le valutazioni economiche. Il risultato viene utilizzato come `costs` in[`geopard.calculate_profit`](#calculate_profit) .

### calculate\_profit

```python
profit = geopard.calculate_profit(revenue, costs)
```

Calcola il profitto sottraendo i costi dai ricavi con questa funzione. Specificando le variabili [`revenue`](#calculate_revenue) e [`costs`](#calculate_costs) (ottenute da funzioni precedenti), è possibile calcolare facilmente il guadagno finanziario delle attività agricole, a supporto dell'analisi della redditività e delle decisioni strategiche.

### fill\_value\_for\_range

```python
# mantieni solo i valori compresi tra 10 e 20, sostituisci gli altri con 0
filtered = geopard.fill_value_for_range(layer, min_value=10, max_value=20, value_to_fill=0)
```

Questa funzione filtra i valori compresi in un intervallo specificato nell'array `input` . Specificando l'array e, facoltativamente, `input` il valore `min_value` e `max_value` soglie, è possibile isolare i valori che rientrano nell’intervallo desiderato. Il parametro `value_to_fill` consente di sostituire i valori fuori intervallo con un valore specificato, migliorando i processi di filtraggio e normalizzazione dei dati.

### calculate\_per\_pixel\_mae

```python
mae_layer = geopard.calculate_per_pixel_mae(predicted_yield, observed_yield)
```

Usa questa funzione per calcolare l’errore assoluto medio (MAE) per pixel tra due dataset. La funzione restituisce una mappa spaziale delle differenze assolute. La «differenza assoluta» indica semplicemente l’entità dello scarto tra i valori dei pixel corrispondenti, indipendentemente da quale sia maggiore.

La funzione consente di individuare le aree con le discrepanze maggiori.

### calculate\_per\_pixel\_relative\_deviation

```python
relative_dev = geopard.calculate_per_pixel_relative_deviation(observed_yield, modeled_yield)
```

Questa funzione calcola la deviazione relativa per ogni pixel tra due dataset, esprimendo la differenza come percentuale del valore in `dataset_1`. In sostanza, mostra di quanto il valore di un pixel si discosta dal valore corrispondente in `dataset_1` in termini proporzionali.

Questo approccio è particolarmente utile per analizzare le variazioni delle proprietà del suolo, delle rese colturali o dei dati di telerilevamento, perché consente di individuare rapidamente le aree con differenze proporzionali significative.

### calculate\_difference

```python
difference = geopard.calculate_difference(yield_2024, yield_2023)
```

Questa funzione sottrae un dataset da un altro per creare una mappa delle differenze. Evidenzia le aree in cui i valori di un dataset sono maggiori o minori rispetto all’altro, facilitando l’individuazione di tendenze e variazioni nel tempo.

Questo strumento è particolarmente utile per visualizzare le variazioni delle proprietà del suolo, delle rese colturali o dei dati di telerilevamento e aiuta a individuare rapidamente le aree che potrebbero richiedere ulteriori analisi o interventi.

### calculate\_relative\_difference

```python
relative_diff = geopard.calculate_relative_difference(yield_2024, yield_2023)
```

Questa funzione calcola la differenza relativa per ogni pixel normalizzando la differenza tra i dataset rispetto ai valori di `dataset_2`. Ciò permette di vedere quanto è significativa la variazione rispetto all’entità di `dataset_2`.

Un confronto proporzionale di questo tipo è particolarmente utile quando si lavora con dataset su scale diverse e aiuta a rilevare variazioni relative nelle proprietà del suolo, nelle rese colturali o nei dati dei sensori. Questo approccio consente di individuare le aree con variazioni rilevanti.

### calculate\_normalized\_difference

```python
normalized_diff = geopard.calculate_normalized_difference(layer_1, layer_2)
```

Questa funzione calcola la differenza normalizzata per ogni pixel, rapportando entrambi i dataset al rispettivo valore massimo globale. In questo modo, i dataset diventano direttamente confrontabili anche se in origine hanno intervalli di valori diversi.

La mappa risultante offre una chiara rappresentazione delle variazioni nelle proprietà del suolo, nelle rese colturali e nei dati di telerilevamento, consentendo di individuare e valutare rapidamente le differenze principali.

### build\_zones\_by\_intervals

```python
# intervalli per la zonizzazione
intervals = [
    (4, 8),
    (8, 12),
    (12, 16)
]

# utilizzo
zones = geopard.build_zones_by_intervals(
    layer, 
    intervals
)
```

Questa funzione crea una mappa delle zone di gestione classificando un layer raster continuo in zone discrete, in base a intervalli di valori definiti dall’utente.

Ogni intervallo definisce una zona e a ogni pixel viene assegnata la zona il cui intervallo comprende il suo valore. I pixel che non rientrano in alcun intervallo vengono contrassegnati con -1.

Questo approccio di zonizzazione viene comunemente usato per trasformare mappe di resa, proprietà del suolo o indici di telerilevamento in zone di gestione operative per applicazioni a rateo variabile.

**Casi d’uso tipici**

* Creazione di zone di gestione a partire da layer di resa, NDVI o suolo
* Preparazione di mappe delle zone per il calcolo dei dosaggi di nutrienti o delle quantità di semina
* Suddivisione dei campi in zone omogenee a supporto delle decisioni

### calculate\_nutrient\_rate\_as\_active\_ingredients\_per\_zone

```python
# opzioni per target_nutrient
target_nutrient_option1 = 50 # numero costante
# OPPURE
target_nutrient_option2 = {1: 20, 2: 40} # dizionario per zona
# OPPURE
target_nutrient_option3 = np.array([[1, 1], [2, 3]], dtype=float) # layer raster continuo

# opzioni per applied_nutrient_operations
applied_operations = [
    5,                                      # operazione1 come numero costante
    {1: 2, 2: 4},                           # operazione2 come dizionario per zona
    np.array([[1, 1], [2, 3]], dtype=float) # operazione3 come layer raster continuo
]

# utilizzo
rates_as_active_ingredients = geopard.calculate_nutrient_rate_as_active_ingredients_per_zone(
    zone_map, 
    target_nutrient, 
    plant_available_soil_nutrient, 
    applied_nutrient_operations = applied_operations # or []
)
```

Questa funzione calcola il tasso di applicazione del nutriente richiesto (principio attivo) per ogni zona di gestione.

Il calcolo si basa su:

* un livello obiettivo del nutriente,
* l'apporto di nutrienti dal suolo disponibili per le piante,
* i nutrienti già apportati con operazioni precedenti (letame, fertilizzanti, digestato ecc.).

Le operazioni di apporto dei nutrienti possono essere indicate come costanti, valori per zona, layer raster o una combinazione di questi. Tutti gli input vengono risolti e aggregati automaticamente per zona.

Per impostazione predefinita, il tasso richiesto viene calcolato come differenza tra il livello obiettivo del nutriente e la somma dell'apporto dal suolo e dei nutrienti già apportati. Il risultato viene restituito come mappa raster in cui ogni zona contiene un tasso uniforme di nutriente.

### convert\_active\_ingredient\_and\_product

```python
# coefficiente di conversione tra principio attivo e prodotto e viceversa
corrected_coefficient = 1.5  # coefficiente costante
# OPPURE
corrected_coefficient = np.array([[np.nan, 5], [np.nan, 1]], dtype=float)  # coefficienti per pixel

# utilizzo
rates_as_products = geopard.convert_active_ingredient_and_product(
    layer, 
    corrected_coefficient
)
```

Questa funzione converte un layer raster tra **tassi di principio attivo e tassi di prodotto** usando un coefficiente di correzione.

Il `corrected_coefficient` può essere un singolo valore **float** (applicato a tutti i pixel) oppure una matrice di coefficienti **matrice** (conversione per pixel). Viene in genere usato per convertire i fabbisogni nutrizionali calcolati (principio attivo) nei tassi effettivi di applicazione del prodotto, o viceversa, in base alla composizione del fertilizzante o alla concentrazione di nutrienti.

La conversione viene applicata pixel per pixel, preservando la struttura spaziale del layer originale.

**Casi d’uso tipici**

* Conversione dei tassi di nutriente nei tassi di prodotto fertilizzante
* Adeguamento delle mappe di distribuzione in base alla concentrazione di nutrienti
* Preparazione delle mappe di prescrizione finali per le macchine agricole

### map\_value\_by\_zone

```python
# assegna un valore a tutte le zone
planned_yield = geopard.map_value_by_zone(
    zone_map,
    3.0
)

# OPPURE: assegna valori diversi per zona
planned_yield = geopard.map_value_by_zone(
    zone_map,
    {1: 2.91, 2: 3.0, 3: 3.06}
)

# OPPURE: aggrega un raster esistente per zona
p_zone_median = geopard.map_value_by_zone(
    zone_map,
    p2o5,
    aggregation_logic="median"
)
```

Questa funzione converte valori scalari, dizionari specifici per zona o layer raster in un raster basato sulle zone.

A ogni pixel valido viene assegnato il valore corrispondente alla relativa zona. Per gli input raster, i valori vengono aggregati all'interno di ogni zona usando `mean`, `median`, `min`, oppure `max`, eliminando di fatto la variabilità all'interno della zona.

Ai valori del dizionario mancanti e ai pixel NoData viene assegnato il valore specificato `default` (NaN per impostazione predefinita).

**Casi d’uso tipici**

* Creazione di obiettivi di resa pianificata a livello di pixel a partire da valori specifici per zona
* Conversione delle raccomandazioni di fertilizzazione specifiche per zona in raster di prescrizione
* Uniformazione della variabilità dei nutrienti nel suolo all'interno delle zone di gestione
* Preparazione dei parametri a livello di zona per i calcoli NumPy pixel per pixel

### calculate\_dose\_by\_nutrient\_balance

```python
# calculate commercial fertilizer dose
ammophos_dose = geopard.calculate_dose_by_nutrient_balance(
    zone_map,
    planned_yield={1: 2.91, 2: 3.0, 3: 3.06},
    soil_nutrient=p2o5,
    removal_per_yield_unit=12.5,
    soil_use_coefficient=0.2,
    fertilizer_use_coefficient=0.4,
    correction_coefficient=1.5,
    product_nutrient_share=0.46,
    min_dose=50,
    max_dose=100
)
```

Questa funzione calcola i tassi di applicazione del fertilizzante per pixel, bilanciando l'asportazione di nutrienti da parte della coltura e l'apporto di nutrienti dal suolo.

Il calcolo tiene conto della resa pianificata, dell'asportazione di nutrienti da parte della coltura, dei nutrienti disponibili nel suolo, dei coefficienti di utilizzo del suolo e del fertilizzante e dei fattori di correzione. Il fabbisogno risultante di principio attivo può essere convertito, facoltativamente, nei tassi di applicazione del fertilizzante commerciale usando `product_nutrient_share`.

Supporta valori di resa pianificata scalari, in forma di dizionario o raster. I valori dei nutrienti nel suolo possono essere utilizzati per pixel oppure aggregati per zona. I tassi finali possono essere vincolati da limiti minimi e massimi di applicazione e arrotondati a numeri interi.

**Casi d’uso tipici**

* Generazione di prescrizioni a dose variabile per fertilizzanti P₂O₅ e K₂O
* Calcolo della reintegrazione dei nutrienti in base alla resa pianificata della coltura
* Considerazione dell'apporto di nutrienti dal suolo e dell'efficienza d'uso del fertilizzante
* Conversione del fabbisogno di principio attivo nei tassi di applicazione del prodotto commerciale
* Generazione di mappe di prescrizione dei fertilizzanti pronte per le macchine agricole

### estimate\_texture\_class\_based\_on\_usda

```python
usda_texture = geopard.estimate_texture_class_based_on_usda(
    sand_pct_layer,
    silt_pct_layer,
    clay_pct_layer
)
```

Questa funzione stima la tessitura del suolo secondo la classificazione USDA per ogni pixel, utilizzando le percentuali di sabbia, limo e argilla.

Fornire tre layer raster in percentuale (0-100) che rappresentino le frazioni granulometriche. L'output è <mark style="background-color:green;">un nome di classe USDA, ad esempio</mark> *<mark style="background-color:green;">sand, loamy\_sand, sandy\_loam, loam, silt\_loam, sandy\_clay\_loam, clay\_loam, silty\_clay\_loam, silty\_clay o undefined</mark>* <mark style="background-color:green;">se i dati di input non sono validi.</mark>

### estimate\_texture\_class\_based\_on\_fao\_wrb

```python
fao_wrb_texture = geopard.estimate_texture_class_based_on_fao_wrb(
    sand_pct_layer,
    silt_pct_layer,
    clay_pct_layer
)
```

Questa funzione stima la classe di tessitura del suolo FAO/WRB (ISO 11277) per ogni pixel, in base alle percentuali di sabbia, limo e argilla.

Fornire tre layer raster in percentuale (0-100) che rappresentino le frazioni granulometriche. L'output è <mark style="background-color:green;">un codice di classe FAO/WRB, ad esempio</mark> *<mark style="background-color:green;">S, LS, SL, L, SiL, Si, SCL, CL, SiCL, SC, SiC, C, HC o undefined</mark>* <mark style="background-color:green;">se i dati di input non sono validi</mark>.

### calculate\_soil\_bulk\_density

```python
bulk_density = geopard.calculate_soil_bulk_density(texture_class_layer, som_pct_layer)
```

Questa funzione calcola <mark style="background-color:green;">la densità apparente del suolo (g/cm³) in base alla classe di tessitura e al contenuto facoltativo di sostanza organica nel suolo (SOM)</mark>.

Il `texture_class_layer` deve contenere nomi o codici delle classi generati dalla [funzione USDA per la classificazione tessiturale](#estimate_texture_class_based_on_usda) o dalla [funzione FAO/WRB per la classificazione tessiturale](#estimate_texture_class_based_on_fao_wrb) menzionate sopra.

Se `som_pct_layer` è fornito come valore percentuale, la funzione adegua la densità apparente in base alla SOM. In caso contrario, restituisce i valori della densità apparente del suolo in g/cm³ associati alle classi tessiturali secondo la tabella di consultazione USDA o FAO/WRB.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.geopard.tech/geopard-tutorials/it/tour-del-prodotto-app-web/equation-based-analytics/catalog-of-custom-functions.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
