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

# 84. ミューテーション: 収量データセットを較正・クリーニング

収量データセットをクリーニング・較正するAPI呼び出し

「YieldDataset」のキャリブレーションは、数学的原則に沿って値の分布を補正し、データ全体の整合性を高める機能です。意思決定の質を向上させ、データセットをさらに詳細な分析に活用できるようにします。

この機能の一般的な用途は次のとおりです。

* 複数の収穫機が同時に、または数日にわたって作業した場合にデータを同期し、一貫性を確保する。
* ばらつきを平滑化して、データセットの均質性と精度を高める。
* 分析結果を不明瞭にするデータノイズや不要な情報を取り除く。
* 圃場の実際のパターンや傾向を歪める可能性がある旋回箇所や異常な形状を除去する。
* 各属性の既知の平均値または合計値に合うよう、収量データを調整する。

詳しい解説と例については、 [収量のキャリブレーションとクリーニング](https://docs.geopard.tech/geopard-tutorials/jpn/nong-xue/yield-and-trials/yield-calibration-and-cleaning.md) のユースケースをご覧ください。

### WetMass属性を含む元のYieldDataset

以下に示す30 haの圃場では、5台の収穫機が並行して作業しました。1台の収穫機のキャリブレーションが他の収穫機と同期していなかったため、 <mark style="color:オレンジ;">オレンジ色の</mark> 箇所が見られます。これは、追加の `CALIBRATION` が必要であることを示しています。また、多数の旋回箇所もあり、 <mark style="color:赤い;">赤い</mark> 箇所は「圃場」の縁に近く、除去する必要があります。

<figure><img src="https://1993076779-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>WetMass属性を含む元のYieldDataset</p></figcaption></figure>

### WetMass属性を含むキャリブレーション・クリーニング済みのYieldDataset

以下は、デフォルトのパラメーターを使用して自動の `CALIBRATE` および `CLEAN` 操作を適用した後のデータセットです。結果の「YieldDataset」は均質になり、外れ値や隣接する形状間の急激な変化がなくなっています。

<figure><img src="https://1993076779-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>WetMass属性を含むキャリブレーション・クリーニング済みのYieldDataset</p></figcaption></figure>

### 軌跡別・平均値／合計値・条件別のオプション

**軌跡別キャリブレーション** は、機械の走行軌跡に基づいて処理します。キャリブレーションでは、各走行軌跡を個別の領域として扱います。GeoPardチームは、この方法を標準的なアプローチとして使用することを推奨しています。

**平均値／合計値キャリブレーション** は、属性値の再配分に重点を置きます。地理空間パターンは正確でも、絶対値が実際の値からずれている場合に有効です。最適な結果を得るには、軌跡別キャリブレーションとの併用をGeoPardは推奨しています。まず軌跡別に処理し、その後、既知の平均値／合計値に合わせて調整します。

**条件別キャリブレーション** は、指定された最小値と最大値のしきい値に基づいて属性値を調整します。地理空間パターンは正確でも、値の分布を調整する必要がある場合、特に既知の最小値と最大値がある場合に有効です。最良の結果を得るため、GeoPardは軌跡別キャリブレーションとの併用を推奨しています。まず軌跡別に処理し、その後、既知の最小値と最大値に合うよう調整します。

### ヒント

{% hint style="warning" %}
**データ異常に関するヒント**

ゼロまたはゼロに近い値、あるいは異常に大きな値（たとえば、平均値が10で最大値が8000）など、データに異常がある場合は、 **クリーニングとキャリブレーション** のワークフローを推奨します。パラメーター `actions: [CLEAN, CALIBRATE]`.

キャリブレーションの前にデータをクリーニングすることで、エラー、欠損値、不整合を確実に取り除き、データの品質と精度を高めます。
{% endhint %}

{% hint style="warning" %}
**初期エラーのないデータに関するヒント**

エラー、欠損値、不整合が当初からなく、複数の収穫機が作業したことが分かっているデータセットでは、 **キャリブレーションとクリーニング** のワークフローを検討してください。パラメーター `actions: [CALIBRATE, CLEAN]`.

キャリブレーション後にデータをクリーニングすると、キャリブレーション中に生じたアーティファクトを除去できる可能性があり、データセットをさらに整えられます。
{% endhint %}

### ドキュメント：ミューテーションの詳細

デフォルトの標準設定では、「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 %}

より高度なサンプルでは、最小値と最大値の範囲を手動で制御し、追加の属性を組み込んでいます。

{% 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" %}
USDAのプロトコルに従って `CLEAN` 操作を実行するには、 `cleanAction` -> `conditionMinMaxClean` で全列を指定するか、その一部を `cleanAction` -> `conditionMinMaxClean` で指定し、残りを `condtionAutoClean` -> `excludedAttributes`.
{% endhint %}

入力パラメーター：

* `actions` を配列として指定し、選択できます。 *適用する補正アクションとその順序* サポートされている値は次のとおりです。 `CLEAN` および `CALIBRATE`.
* `calibrateAction` は、設定情報を含むオブジェクトです。 `CALIBRATE` 操作に関連する。
  * `calibrationAttributes` キャリブレーションが必要な属性の配列。通常は収量列に関連付けられます。
  * `smoothWindowSize` 結果の値を平滑化し、値の急激な変化を抑える奇数の整数。
  * `conditionPathwiseCalibration` 次の項目を含むオブジェクト。 **走行経路別** キャリブレーションは機械の走行経路に対応します。キャリブレーションでは、機械の各走行経路を個別の領域として処理します。
    * `calibrationBasis` キャリブレーションの基準として使用する属性を表す文字列。
    * `maxHomogeneityRegion` キャリブレーションの参照領域として最大均質領域を使用するかどうかを示すブール値。
    * `syntheticMachinePath` 機械の走行経路をシミュレーションするかどうかを示すブール値。正確な機械走行経路の属性がなく、タイムスタンプなどの属性に基づいてシミュレーションする必要がある場合に役立ちます。
  * `conditionAvgTotalCalibration` 次の項目を含むオブジェクト。 **平均／合計** キャリブレーションでは、属性値の再配分に重点を置きます。地理空間パターンは正確でも、絶対値が実績と異なる場合に有効です。
    * `calibrationAttribute` キャリブレーション対象の属性を表す文字列。
    * `average` 属性値の平均を表す数値。この平均に属性値が合致するように調整されます。次のいずれか一方のみを使用してください。 `average` または `total`。
    * `total` 属性値の合計を表す数値。属性値の総和がこの値に一致するように調整されます。次のいずれか一方のみを使用してください。 `average` または `total`。
  * `conditionMinMaxCalibration` 次の項目を含むオブジェクト。 **条件付き** キャリブレーションでは、指定した最小値と最大値のしきい値に基づいて属性値を調整します。
    * `calibrationAttribute` キャリブレーション対象の属性を表す文字列。
    * `min` 属性の最小値を表す数値。キャリブレーション範囲の下限として機能します。
    * `minIncluded` 最小値を含めるかどうかを示すブール値。
    * `max` 属性の最大値を表す数値。キャリブレーション範囲の上限として機能します。
    * `maxIncluded` 最大値を含めるかどうかを示すブール値。
* `cleanAction` 次の設定の詳細を含むオブジェクト。 `CLEAN` 操作。
  * `conditionAutoClean` 自動クリーンアルゴリズム固有の設定を含むオブジェクト。
    * `targetAttribute` 目標収量値を表す文字列。
    * `excludedAttributes` クリーニング処理に影響しない属性を定義する文字列の配列として指定します。
  * `conditionMinMaxClean` 説明されているクリーニングルールを含むオブジェクトの配列として指定します。各オブジェクトには次のパラメーターが含まれます。
    * cleanAttribute は、ルールの対象となる列名を指定する文字列です。
    * `min` 最小値を示す数値です。
    * `max` 最大値を示す数値です。

{% hint style="info" %}
入力内容を確認し、列挙型（次のようなもの）の最新の値を参照するには、 `operations`など、 [Altair](https://docs.geopard.tech/geopard-tutorials/jpn/apidokyumento/getting-started-with-the-geopard-api.md).
{% endhint %}

### ドキュメント：YieldDataset クエリ

GeoPard API の利用者は、属性 `appliedCorrections` および `appliedCorrectionsVersion`を通じて、YieldDataset に適用された補正の詳細を取得できます。前者は適用された補正（例： `CALIBRATE` および `CLEAN`）のリストを返し、配列内の順序が実行順を示します。一方、 `appliedCorrectionsVersion` は使用されたアルゴリズムのバージョンを示します。

{% 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/jpn/apidokyumento/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.
