> 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/documentazione-api/geopard-api-requests-overview/84.-mutation-calibrate-and-clean-yielddataset.md).

# 84. Mutazione: Calibra e pulisci YieldDataset

Chiamate API per pulire e calibrare i dataset di resa

La calibrazione di "YieldDataset" è una funzionalità che corregge la distribuzione dei valori in base a principi matematici, migliorando l’integrità complessiva dei dati. Aumenta la qualità delle decisioni e rende il dataset utile per analisi approfondite.

I casi d’uso più comuni di questa funzionalità includono:

* Sincronizzare i dati quando più mietitrebbie hanno lavorato contemporaneamente o nell’arco di diversi giorni, garantendo coerenza.
* Rendere il dataset più omogeneo e accurato attenuando le variazioni.
* Rimuovere il rumore e le informazioni superflue che possono offuscare i risultati dell’analisi.
* Eliminare le manovre di inversione o le geometrie anomale, che possono alterare i modelli e le tendenze effettivi in campo.
* Adeguare i dati di resa alle medie o ai totali stabiliti per ciascun attributo.

Per un approfondimento e alcuni esempi, consulta il nostro [caso d’uso sulla calibrazione e pulizia della resa](https://docs.geopard.tech/geopard-tutorials/it/agronomia/yield-and-trials/yield-calibration-and-cleaning.md) .

### YieldDataset originale con attributo WetMass

Cinque mietitrebbie hanno lavorato in parallelo nel campo di 30 ha mostrato qui sotto. La calibrazione di una delle mietitrebbie non era sincronizzata con quella delle altre, con il risultato di <mark style="color:arancione;">macchie arancioni</mark> , che indicano la necessità di un’ulteriore `CALIBRATION` . Inoltre, sono presenti numerose manovre di inversione <mark style="color:rosse;">rosse</mark> vicino ai bordi del "Field", che devono essere eliminate.

<figure><img src="https://1371939954-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYICBELdyAXXebKAzfLOR%2Fuploads%2Fj40y3lH0F0ZfJNH2WhTf%2Fimage.png?alt=media&amp;token=6bf7baaa-3cda-4863-98e1-e0a92ff2b765" alt=""><figcaption><p>YieldDataset originale con attributo WetMass</p></figcaption></figure>

### YieldDataset calibrato e ripulito con attributo WetMass

Il risultato qui sotto mostra il dataset dopo l’applicazione automatica delle operazioni `CALIBRATE` e `CLEAN` con i parametri predefiniti. Il "YieldDataset" risultante è omogeneo, senza valori anomali né cambiamenti bruschi tra geometrie adiacenti.

<figure><img src="https://1371939954-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYICBELdyAXXebKAzfLOR%2Fuploads%2Fu3zjlXg03WoWrjOOT9v7%2Fimage.png?alt=media&amp;token=d298f632-b0fe-462f-a395-64a64c02ea55" alt=""><figcaption><p>YieldDataset calibrato e ripulito con attributo WetMass</p></figcaption></figure>

### Opzioni Pathwise, Average/Total e Conditional

**Calibrazione Pathwise** corrisponde alle traiettorie della macchina. Ai fini della calibrazione, ogni traiettoria viene elaborata come una regione indipendente. Il team GeoPard consiglia di usare questo metodo come approccio standard.

**Calibrazione Average/Total** si concentra sulla ridistribuzione dei valori degli attributi. È utile quando i modelli geospaziali sono accurati, ma i valori assoluti si discostano da quelli effettivi. Per ottenere risultati ottimali, GeoPard consiglia di combinarla con la calibrazione Pathwise: applicare prima Pathwise, quindi adeguare i valori alle medie o ai totali noti.

**Calibrazione Conditional** adegua i valori degli attributi in base alle soglie minime e massime specificate. Questo metodo è particolarmente utile quando i modelli geospaziali sono precisi, ma la distribuzione dei valori deve essere adeguata, soprattutto se si conoscono i valori minimi e massimi. Per ottenere i risultati migliori, GeoPard consiglia di abbinarla alla calibrazione Pathwise: applicare prima Pathwise, quindi adeguare i valori ai limiti minimi e massimi noti.

### Suggerimenti

{% hint style="warning" %}
**Suggerimento per le anomalie nei dati**

Se si riscontrano anomalie nei dati, come valori pari o vicini a zero oppure valori insolitamente elevati (ad esempio, una media di 10 e un massimo di 8000), si consiglia il flusso di lavoro **Clean & Calibration** . Si configura con i parametri `actions: [CLEAN, CALIBRATE]`.

Dare priorità alla pulizia dei dati prima della calibrazione permette di rimuovere errori, valori mancanti o incongruenze, migliorando così la qualità e l’accuratezza dei dati.
{% endhint %}

{% hint style="warning" %}
**Suggerimento per i dati senza errori iniziali**

Se i dataset non presentano inizialmente errori, valori mancanti o incongruenze e si sa che sono state coinvolte più mietitrebbie, si può usare il flusso di lavoro **Calibration & Clean** . Si configura con i parametri `actions: [CALIBRATE, CLEAN]`.

La pulizia dei dati dopo la calibrazione contribuisce a perfezionare ulteriormente il dataset, eliminando eventuali artefatti introdotti durante la calibrazione.
{% endhint %}

### Documentazione: dettagli della mutation

La configurazione standard predefinita abilita la calibrazione e la pulizia automatiche di "YieldDataset".

{% code overflow="wrap" lineNumbers="true" %}

```graphql
mutation AutoCalibrateYieldDataset {
  calibrateYieldDataset(input: {
    fieldUuid: "<placeholder_of_field_uuid>"
    yieldDatasetUuid: "<placeholder_of_dataset_uuid>"
    actions: {
      calibrateAction: {
        calibrationAttributes:["WetMass", "VRYIELDVOL"]
        conditionPathwiseCalibration: {
          calibrationBasis: "WetMass"
          maxHomogeneityRegion: true
          syntheticMachinePath: true
        }
      }
      cleanAction: {
        condtionAutoClean: {
          targetAttribute: "WetMass"
        }
      }
      
      actions:  [CALIBRATE, CLEAN]
    }
  }) {
    uuid
    fieldUuid
    originalUuid
    statusCode
    statusMessage
  }
}
```

{% endcode %}

Un esempio più avanzato consente di controllare manualmente gli intervalli min/max e include attributi aggiuntivi.

{% code overflow="wrap" lineNumbers="true" %}

```graphql
mutation CustomCalibrateYieldDataset {
  calibrateYieldDataset(input: {
    fieldUuid: "<placeholder_of_field_uuid>"
    yieldDatasetUuid: "<placeholder_of_dataset_uuid>"
    actions: {
      calibrateAction: {
        calibrationAttributes:["WetMass", "VRYIELDVOL"]
        smoothWindowSize: 11
        conditionPathwiseCalibration: {
          calibrationBasis: "Machine"
          maxHomogeneityRegion: true
          syntheticMachinePath: false
        }
        conditionAvgTotalCalibration:[{
          calibrationAttribute: "WetMass"
          average:8.0
        }]
      }
      cleanAction: {
        condtionAutoClean: {
          targetAttribute: "WetMass"
        }
        conditionMinMaxClean: [{
          cleanAttribute: "Distance"
          min: 1.5
          max: 10.0
        }]
      }
      actions:  [CALIBRATE, CLEAN]
    }
  }) {
    uuid
    fieldUuid
    originalUuid
    statusCode
    statusMessage
  }
}
```

{% endcode %}

{% hint style="info" %}
Per seguire il protocollo USDA per l'operazione `CLEAN` è necessario specificare TUTTE le colonne in `cleanAction` -> `conditionMinMaxClean` oppure specificarne alcune in `cleanAction` -> `conditionMinMaxClean` e le restanti in `condtionAutoClean` -> `excludedAttributes`.
{% endhint %}

Parametri di input:

* `actions` come array, che consente di scegliere *le azioni di correzione e la sequenza* di applicazione; i valori supportati includono `CLEAN` e `CALIBRATE`.
* `calibrateAction` come oggetto contenente i dettagli di configurazione relativi all'operazione `CALIBRATE` .
  * `calibrationAttributes` come array di attributi che richiedono la calibrazione, in genere associati alla colonna Yield.
  * `smoothWindowSize` come numero intero dispari che rende più uniformi i valori del risultato, riducendo le variazioni brusche.
  * `conditionPathwiseCalibration` come oggetto con la **per traccia** calibrazione, che corrisponde alle tracce della macchina. Ai fini della calibrazione, ogni traccia della macchina viene elaborata come una regione indipendente.
    * `calibrationBasis` come stringa che rappresenta l'attributo usato come base per la calibrazione.
    * `maxHomogeneityRegion` come valore booleano che indica se la regione con la massima omogeneità viene usata come regione di riferimento per la calibrazione.
    * `syntheticMachinePath` come valore booleano che indica se simulare i percorsi della macchina. È utile quando l'attributo del percorso preciso della macchina è assente e occorre simularlo in base ai timestamp o a un attributo simile.
  * `conditionAvgTotalCalibration` come oggetto con la calibrazione **media/totale** , che si concentra sulla ridistribuzione dei valori degli attributi. Questo metodo è utile quando i modelli geospaziali sono accurati, ma i valori assoluti si discostano da quelli effettivi.
    * `calibrationAttribute` come stringa che rappresenta l'attributo da calibrare.
    * `average` come numero che rappresenta i valori medi dell'attributo; i valori dell'attributo devono essere conformi a questa media. È possibile utilizzare una sola opzione alla volta, `average` oppure `total`.
    * `total` come numero che rappresenta la somma totale dei valori dell'attributo; la somma aggregata di questi valori deve corrispondere al totale. È possibile utilizzare una sola opzione alla volta, `average` oppure `total`.
  * `conditionMinMaxCalibration` come oggetto con la calibrazione **condizionale** , che modifica i valori degli attributi in base alle soglie minima e massima indicate.
    * `calibrationAttribute` come stringa che rappresenta l'attributo da calibrare.
    * `min` come numero che rappresenta il valore minimo dell'attributo, ossia il limite inferiore dell'intervallo di calibrazione.
    * `minIncluded` come valore booleano che indica se includere o meno il valore minimo.
    * `max` come numero che rappresenta il valore massimo dell'attributo, ossia il limite superiore dell'intervallo di calibrazione.
    * `maxIncluded` come valore booleano che indica se includere o meno il valore massimo.
* `cleanAction` come oggetto che include i dettagli di configurazione associati all'operazione `CLEAN` .
  * `conditionAutoClean` come oggetto che include le configurazioni specifiche dell'algoritmo di pulizia automatica.
    * `targetAttribute` come stringa che rappresenta i valori target di resa (Yield).
    * `excludedAttributes` come array di stringhe che definiscono gli attributi che non influiscono sull’operazione di pulizia.
  * `conditionMinMaxClean` come array di oggetti contenenti le regole di pulizia descritte; ogni oggetto include i seguenti parametri.
    * cleanAttribute come stringa che specifica il nome della colonna a cui si applica la regola.
    * `min` come numero che indica il valore minimo.
    * `max` come numero che indica il valore massimo.

{% hint style="info" %}
Per visualizzare gli input e accedere ai valori più recenti disponibili delle enumerazioni (come `operations`), si consiglia di utilizzare [Altair](https://docs.geopard.tech/geopard-tutorials/it/documentazione-api/getting-started-with-the-geopard-api.md).
{% endhint %}

### Documentazione di Altair: query YieldDataset

In qualità di utente dell’API GeoPard, è possibile recuperare i dettagli delle correzioni applicate ai YieldDataset tramite gli attributi `appliedCorrections` e `appliedCorrectionsVersion`. Il primo fornisce un elenco delle correzioni applicate (ad es., `CALIBRATE` e `CLEAN`), il cui ordine di esecuzione è indicato dalla posizione nell’array. Il secondo `appliedCorrectionsVersion` indica la versione dell’algoritmo utilizzato.

{% code overflow="wrap" lineNumbers="true" %}

```graphql
query DetailsAboutAppliedCalibrations {
  getFields (filter: {fieldUuid: "<placeholder_of_field_uuid>"}){
    fields {
      uuid
      yieldDatasets  {
        uuid
        appliedCorrections
        appliedCorrectionsVersion
      }
    }
  }
}
```

{% endcode %}


---

# 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/documentazione-api/geopard-api-requests-overview/84.-mutation-calibrate-and-clean-yielddataset.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.
