# Каталог користувацьких функцій

GeoPard пропонує комплексний каталог користувацьких функцій, розроблених для покращення читабельності та функціональності аналітики на основі рівнянь. Ці функції інкапсулюють складний `python` код, дозволяючи вам легко реалізовувати складні маніпуляції з даними та обчислення.

### Введіть рівняння

<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>Введіть рівняння</p></figcaption></figure>

Список доступних готових функцій для створення більш інтуїтивних і зручних для підтримки рівнянь у GeoPard включено до `geopard` пакета:

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

```python
# input_data — це шар атрибута Dataset (наприклад, Yield, NDVI)
filled_layer = geopard.fill_gaps_with_k_neighbors(yield_layer, k=5)
```

Ця функція відновлює прогалини в даних або нулі в наборі даних за допомогою алгоритму K-Neighbors. Вказавши `input_data` змінну (як Dataset із вибраним атрибутом) і кількість сусідів `k`, ви можете безперешкодно заповнювати відсутні значення, забезпечуючи безперервність і цілісність даних.

Ця функція добре працює, коли прогалини в даних розподілені по полю і не зосереджені в якійсь конкретній частині межі поля.

### determine\_data\_similarity

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

Використовуйте цю функцію для обчислення попіксельної подібності між двома наборами даних. Змінні `data_layer_1` та `data_layer_2` мають представляти **те саме вимірювання** в **тих самих одиницях** щоб забезпечити змістовне порівняння. Надавши змінні `data_layer_1` та `data_layer_2` пов’язані з Datasets, ви можете створити карту подібності зі значеннями в діапазоні від 0 до 1, що полегшує порівняльні дослідження та розпізнавання закономірностей.

### 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)
```

Використовуйте цю функцію для обчислення попіксельної подібності між двома нормалізованими наборами даних. Нормалізація рекомендована, коли вихідні `data_layer_1` та `data_layer_2` мають різні масштаби або одиниці. Надавши ці набори даних як вхідні, функція генерує карту подібності зі значеннями від 0 до 1, що робить її придатною для порівняльних досліджень, розпізнавання закономірностей та аналізу просторової узгодженості.

### determine\_low\_high\_similarity

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

Ця функція оцінює низько-високу подібність між двома наборами даних. Вводячи змінні `data_layer_1` та `data_layer_2` пов’язані з Datasets, ви отримуєте категоризовану карту подібності, що вказує такі комбінації, як low-low, low-high, high-low і high-high, що корисно для детальної класифікації даних.

### get\_value\_for\_zone

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

Використовуйте цю функцію для вилучення всіх значень атрибута Dataset в межах однієї зони. Надайте `data_layer` (шар атрибута), `zones_layer` (карту зон) і `zone_id` (номер зони), щоб ізолювати значення для аналізу, такі як урожайність, норма внесення або норма висіву, всередині цієї зони.

### drop\_value

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

Ця функція дозволяє видаляти певні значення з атрибута набору даних. Вказавши `data_layer` та `value_to_drop`, ви можете очистити набір даних, вилучивши ці значення з результату, технічно замінивши їх на `NaN`.

### normalize\_data

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

Нормалізуйте атрибут набору даних за допомогою цієї функції. Передавши `data_layer`, ви можете масштабувати дані до стандартизованого діапазону від 0 до 1, полегшуючи порівняння та інтеграцію між різними наборами даних.

### calculate\_total\_applied\_fertilizer

```python
applications = [urea_rate, map_rate]
coefficients = [1.0, 1.0]  # використовуйте 1.0, щоб зберегти одиниці, або скоригуйте для концентрації продукту

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

Обчисліть загальну кількість внесеного добрива в одиницях на площу (наприклад, у кг/га, л/га, gal/ac тощо). Надавши `application_list` Datasets з атрибутами AppliedRate та відповідні `active_ingredient_coefficient_list` з продуктами добрив, щоб отримати фактичну загальну кількість внесеного добрива в одиницях (наприклад, у кг, л, gal тощо).

### calculate\_total\_applied\_nitrogen

```python
applications = [urea_rate, uan_rate]
nitrogen_coefficients = [0.46, 0.32]  # частка N (діючої речовини) в кожному продукті

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

Обчисліть загальну кількість внесеного азоту в кг/га за допомогою цієї функції. Надавши `application_list` Datasets з атрибутами AppliedRate та відповідні `active_ingredient_coefficient_list` з азотними продуктами для перетворення фактичного азоту в кг/га, ви можете точно обчислити загальну кількість внесеного азоту, що є важливим для сільськогосподарського планування та оцінки сталості. Результат використовується як `N_total_applied` у[`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
)
```

Визначте поглинання азоту в кг/га за допомогою цієї функції. Надавши `yield_wet_tha`, `moisture_pct`, `protein_pct` з набору даних Yield і `protein_crop_correction_coefficient` що представляє зв’язок білка з поглинанням азоту, ви можете оцінити ефективність використання азоту у виробництві культур. Результат використовується як `N_uptake` у[`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)
```

Оцініть ефективність використання азоту у відсотках за допомогою цієї функції. Вводячи [`N_total_applied`](#calculate_total_applied_nitrogen) та [`N_uptake`](#calculate_nitrogen_uptake) змінні (з попередніх функцій), ви можете виміряти ефективність внесення азоту, що допомагає оптимізувати використання добрив.

### calculate\_costs

```python
rates = [seed_rate, fertilizer_rate]
prices = [1.2, 0.8]  # ціна за одиницю для кожного шару норм
costs = geopard.calculate_costs(rates, prices)
```

Обчисліть загальні витрати на основі норм внесення та цін за допомогою цієї функції. Надавши `application_rate_list` із Datasets з атрибутами AppliedRate та відповідний `price_per_unit_list`, ви можете агрегувати витрати, пов’язані з різними сільськогосподарськими операціями, підтримуючи управління бюджетом і фінансове планування. Результат використовується як `costs` у[`geopard.calculate_profit`](#calculate_profit).

### calculate\_revenue

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

Обчисліть дохід із набору даних Yield за допомогою цієї функції. Вводячи `yield_as_mass` пов’язаний з атрибутом набору даних Yield і `yield_price_per_unit`, ви можете оцінити дохід, отриманий від виробництва культур, що полегшує економічні оцінки. Результат використовується як `costs` у[`geopard.calculate_profit`](#calculate_profit) .

### calculate\_profit

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

Визначте прибуток, віднявши витрати від доходу, за допомогою цієї функції. Надавши [`revenue`](#calculate_revenue) та [`costs`](#calculate_costs) змінні (з попередніх функцій), ви можете легко обчислити фінансовий прибуток від сільськогосподарських операцій, підтримуючи аналіз прибутковості та стратегічне прийняття рішень.

### fill\_value\_for\_range

```python
# залишити лише значення між 10 і 20, решту замінити на 0
filtered = geopard.fill_value_for_range(layer, min_value=10, max_value=20, value_to_fill=0)
```

Ця функція фільтрує значення в заданому діапазоні у `input` масиві. Надавши `input` масив разом із необов’язковим `min_value` та необов’язковим `max_value` порогами, ви можете ізолювати значення, що потрапляють у бажаний діапазон. Параметр `value_to_fill` дозволяє замінювати значення поза діапазоном вказаним значенням, покращуючи процеси фільтрації та нормалізації даних.

### calculate\_per\_pixel\_mae

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

Використовуйте цю функцію для обчислення середньої абсолютної похибки (MAE) на піксель між двома наборами даних. Вона надає просторову карту абсолютних відмінностей. «Абсолютна різниця» — це просто величина розриву між відповідними значеннями пікселів, без урахування того, яке з них більше чи менше.

Функція допомагає виявляти області з більшими розбіжностями.

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

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

Ця функція обчислює відносне відхилення для кожного пікселя між двома наборами даних, виражаючи різницю у відсотках від значення в `dataset_1`. По суті, вона показує, наскільки значення одного пікселя відхиляється від відповідного значення в `dataset_1` у пропорційних величинах.

Такий підхід особливо цінний під час аналізу варіацій властивостей ґрунту, урожайності культур або даних дистанційного зондування, оскільки допомагає швидко виявляти області зі значними пропорційними відмінностями.

### calculate\_difference

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

Ця функція віднімає один набір даних від іншого, щоб створити карту різниці. Вона виділяє області, де значення в одному наборі даних вищі або нижчі порівняно з іншим, що полегшує виявлення тенденцій і змін з часом.

Цей інструмент особливо корисний для візуалізації варіацій властивостей ґрунту, урожайності культур або даних дистанційного зондування, допомагаючи швидко визначати області, які можуть потребувати подальшого аналізу або втручання.

### calculate\_relative\_difference

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

Ця функція обчислює відносну різницю для кожного пікселя, нормалізуючи різницю між наборами даних із використанням значень із `dataset_2`. Це означає, що вона показує, наскільки значущою є зміна відносно величини `dataset_2`.

Таке пропорційне порівняння особливо корисне під час роботи з наборами даних різних масштабів, допомагаючи виявляти відносні зміщення у властивостях ґрунту, урожайності культур або показниках сенсорів. Цей підхід допомагає визначати області з помітною варіацією.

### calculate\_normalized\_difference

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

Ця функція обчислює нормалізовану різницю для кожного пікселя, масштабуючи обидва набори даних відносно їхнього глобального максимального значення. Цей процес робить набори даних безпосередньо порівнюваними, навіть якщо вони спочатку мають різні діапазони.

Отримана карта надає чітке уявлення про варіації властивостей ґрунту, урожайності культур і даних дистанційного зондування, дозволяючи швидко визначати та оцінювати ключові відмінності.

### build\_zones\_by\_intervals

```python
# інтервали для зонування
intervals = [
    (4, 8),
    (8, 12),
    (12, 16)
]

# використання
zones = geopard.build_zones_by_intervals(
    layer, 
    intervals
)
```

Ця функція створює карту управлінських зон, класифікуючи безперервний растровий шар на дискретні зони на основі визначених користувачем інтервалів значень.

Кожен інтервал визначає зону, і кожному пікселю призначається зона, до діапазону значень якої він належить. Пікселі, що не відповідають жодному інтервалу, позначаються як -1.

Цей підхід до зонування зазвичай використовується для перетворення карт урожайності, властивостей ґрунту або індексів дистанційного зондування на практичні управлінські зони для диференційованого внесення.

**Типові випадки використання**

* Створення управлінських зон із шарів урожайності, NDVI або ґрунту
* Підготовка карт зон для розрахунків норм поживних речовин або висіву
* Сегментація полів на однорідні зони для прийняття рішень

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

```python
# параметри target_nutrient
target_nutrient_option1 = 50 # постійне число
# АБО
target_nutrient_option2 = {1: 20, 2: 40} # словник по зонах
# АБО
target_nutrient_option3 = np.array([[1, 1], [2, 3]], dtype=float) # безперервний растровий шар

# параметри applied_nutrient_operations
applied_operations = [
    5,                                      # operation1 як постійне число
    {1: 2, 2: 4},                           # operation2 як словник по зонах
    np.array([[1, 1], [2, 3]], dtype=float) # operation3 як безперервний растровий шар
]

# використання
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 # або []
)
```

Ця функція обчислює необхідну норму внесення поживних речовин (діючої речовини) для кожної управлінської зони.

Розрахунок базується на:

* цільовому рівні поживної речовини,
* забезпеченні рослинодоступними поживними речовинами з ґрунту,
* поживних речовинах, уже внесених у попередніх операціях (гній, добрива, дигестат тощо).

Операції внесення поживних речовин можуть надаватися як константи, значення по зонах, растрові шари або будь-яка комбінація з них. Усі вхідні дані автоматично обробляються та агрегуються по зонах.

За замовчуванням необхідна норма обчислюється як різниця між цільовим рівнем поживної речовини та сумою ґрунтового забезпечення і внесених поживних речовин. Результат повертається як растрова карта, де кожна зона містить однорідну норму поживної речовини.

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

```python
# коефіцієнт перетворення діючої речовини у продукт і навпаки
corrected_coefficient = 1.5  # постійний коефіцієнт
# АБО
corrected_coefficient = np.array([[np.nan, 5], [np.nan, 1]], dtype=float)  # коефіцієнти для кожного пікселя

# використання
rates_as_products = geopard.convert_active_ingredient_and_product(
    layer, 
    corrected_coefficient
)
```

Ця функція перетворює растровий шар між **нормами діючої речовини та нормами продукту** за допомогою коригувального коефіцієнта.

Параметр `corrected_coefficient` може бути одним **float** (застосовується до всіх пікселів) або коефіцієнтною **matrix** (перетворення для кожного пікселя). Зазвичай вона використовується для перетворення розрахованих потреб у поживних речовинах (діюча речовина) на фактичні норми внесення продукту або навпаки, залежно від складу добрива чи концентрації поживної речовини.

Перетворення застосовується попіксельно, зберігаючи просторову структуру вихідного шару.

**Типові випадки використання**

* Перетворення норм поживних речовин на норми продукту добрива
* Коригування карт внесення на основі концентрації поживної речовини
* Підготовка фінальних карт-завдань для техніки

### 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
)
```

Ця функція оцінює текстуру ґрунту USDA для кожного пікселя, використовуючи відсотковий вміст піску, мулу та глини.

Надайте три растрові шари у відсотках (0–100), які представляють фракції за розміром частинок. Результатом є <mark style="background-color:green;">назви класів USDA, такі як</mark> *<mark style="background-color:green;">sand, loamy\_sand, sandy\_loam, loam, silt\_loam, sandy\_clay\_loam, clay\_loam, silty\_clay\_loam, silty\_clay або undefined</mark>* <mark style="background-color:green;">коли вхідні дані є недійсними.</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
)
```

Ця функція оцінює клас текстури ґрунту FAO/WRB (ISO 11277) для кожного пікселя на основі відсоткового вмісту піску, мулу та глини.

Надайте три растрові шари у відсотках (0–100), які представляють фракції за розміром частинок. Результатом є <mark style="background-color:green;">коди класів FAO/WRB, такі як</mark> *<mark style="background-color:green;">S, LS, SL, L, SiL, Si, SCL, CL, SiCL, SC, SiC, C, HC або undefined</mark>* <mark style="background-color:green;">коли вхідні дані є недійсними</mark>.

### calculate\_soil\_bulk\_density

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

Ця функція обчислює <mark style="background-color:green;">щільність складення ґрунту (г/см³) на основі класу текстури та необов’язкового вмісту органічної речовини ґрунту (SOM)</mark>.

Параметр `texture_class_layer` має містити назви класів або коди, створені [функцією текстури USDA](#estimate_texture_class_based_on_usda) або [функцією текстури FAO/WRB](#estimate_texture_class_based_on_fao_wrb) згаданою вище.

Якщо `som_pct_layer` надано у відсотках, функція коригує щільність складення з використанням SOM. Інакше вона повертає значення щільності складення ґрунту в г/см³, пов’язані з класами текстури відповідно до таблиці відповідності USDA або FAO/WRB.