فهرس الدوال المخصصة

تغلف هذه الدوال شيفرة Python معقدة، مما يتيح لك تنفيذ عمليات معالجة وحسابات متقدمة للبيانات بسهولة.

تقدّم GeoPard فهرسًا شاملًا من الدوال المخصّصة المصممة لتحسين قابلية قراءة ووظائف التحليلات القائمة على المعادلات. تُجسّد هذه الدوال العمليات المعقدة بايثون من الكود، مما يتيح لك تنفيذ عمليات معالجة البيانات والحسابات المتقدمة بسهولة.

إدخال المعادلة

أدخل معادلة

تتضمن القائمة المتاحة من الدوال الجاهزة لإنشاء معادلات أكثر وضوحًا وسهولةً في الصيانة داخل GeoPard في geopard الحزمة:

fill_gaps_with_k_neighbors

# input_data هو طبقة سمة لمجموعة البيانات (مثل: الغلة، NDVI)
filled_layer = geopard.fill_gaps_with_k_neighbors(yield_layer, k=5)

تُعيد هذه الدالة ملء الفجوات أو الأصفار في مجموعة البيانات باستخدام خوارزمية K-Neighbors. ومن خلال تحديد المتغير input_data (كـ Dataset مع السمة المحددة) وعدد الجيران k، يمكنك ملء القيم المفقودة بسلاسة، مما يضمن استمرارية البيانات وسلامتها.

تعمل هذه الدالة بشكل جيد عندما تكون الفجوات في البيانات موزعة عبر الحقل وليست متركزة في أي جزء محدد من حدود الحقل.

determine_data_similarity

similarity = geopard.determine_data_similarity(yield_2023, yield_2024)

استخدم هذه الدالة لحساب التشابه لكل بكسل بين مجموعتي بيانات. يجب أن تمثل المتغيرات data_layer_1 و data_layer_2 نفس القياس وبالوحدات نفسها في الوحدات نفسها لضمان مقارنة ذات معنى. ومن خلال توفير المتغيرات data_layer_1 و data_layer_2 المرتبطة بمجموعات البيانات، يمكنك إنشاء خريطة تشابه بقيم تتراوح من 0 إلى 1، مما يسهّل الدراسات المقارنة والتعرّف على الأنماط.

determine_data_similarity_from_normalized

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

zones = geopard.determine_low_high_similarity(soil_ph, yield_layer)

تُقيّم هذه الدالة التشابه منخفض-مرتفع بين مجموعتي بيانات. ومن خلال إدخال المتغيرات data_layer_1 و data_layer_2 المرتبطة بمجموعات البيانات، تحصل على خريطة تشابه مُصنّفة تُظهر تراكيب مثل منخفض-منخفض، منخفض-مرتفع، مرتفع-منخفض، ومرتفع-مرتفع، وهو أمر مفيد للتصنيف الدقيق للبيانات.

get_value_for_zone

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

استخدم هذه الدالة لاستخراج جميع القيم من سمة مجموعة بيانات داخل منطقة واحدة. قدّم data_layer (طبقة السمة)، zones_layer (خريطة المناطق)، و zone_id (رقم المنطقة) لعزل القيم لأغراض التحليل، مثل الغلة أو معدل الإضافة أو معدل البذر داخل تلك المنطقة.

drop_value

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

تتيح لك هذه الدالة إزالة قيم محددة من سمة مجموعة البيانات. ومن خلال تحديد data_layer و value_to_drop، يمكنك تنظيف مجموعة البيانات عبر حذف تلك القيم من الناتج، أي استبدالها تقنيًا بـ NaN.

normalize_data

ndvi_normalized = geopard.normalize_data(ndvi_layer)

قم بتطبيع سمة مجموعة بيانات باستخدام هذه الدالة. ومن خلال تمرير data_layer، يمكنك تحجيم البيانات إلى نطاق معياري من 0 إلى 1، مما يسهل المقارنة والتكامل بين مجموعات بيانات مختلفة.

calculate_total_applied_fertilizer

applications = [urea_rate, map_rate]
coefficients = [1.0, 1.0]  # استخدم 1.0 للإبقاء على الوحدات، أو عدّل حسب تركيز المنتج

total_applied = geopard.calculate_total_applied_fertilizer(applications, coefficients)

احسب إجمالي السماد المضاف بوحدات لكل وحدة مساحة (على سبيل المثال، كغ/هكتار، ل/هكتار، غال/فدان، إلخ). ومن خلال توفير application_list من مجموعات بيانات تحتوي على سمات AppliedRate وبالمقابل active_ingredient_coefficient_list المرتبطة بمنتجات السماد للحصول على إجمالي السماد المضاف الفعلي بالوحدات (على سبيل المثال، كغ، ل، غال، إلخ).

calculate_total_applied_nitrogen

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 من مجموعات بيانات تحتوي على سمات AppliedRate وبالمقابل active_ingredient_coefficient_list مع منتجات النيتروجين لتحويل النيتروجين الفعلي إلى كغ/هكتار، يمكنك حساب إجمالي النيتروجين المضاف بدقة، وهو أمر أساسي للتخطيط الزراعي وتقييمات الاستدامة. ويُستخدم الناتج كـ N_total_applied فيgeopard.calculate_nitrogen_use_efficiency.

calculate_nitrogen_uptake

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 من مجموعة بيانات الغلة و protein_crop_correction_coefficient الذي يمثّل ارتباط البروتين بامتصاص النيتروجين، يمكنك تقييم كفاءة استخدام النيتروجين في إنتاج المحاصيل. ويُستخدم الناتج كـ N_uptake فيgeopard.calculate_nitrogen_use_efficiency .

calculate_nitrogen_use_efficiency

NUE_pct = geopard.calculate_nitrogen_use_efficiency(N_total_applied, N_uptake)

قيّم كفاءة استخدام النيتروجين كنسبة مئوية باستخدام هذه الدالة. ومن خلال إدخال N_total_applied و N_uptake المتغيرات (من الدوال السابقة)، يمكنك قياس فعالية إضافة النيتروجين، مما يساعد في تحسين استخدام السماد.

calculate_costs

rates = [seed_rate, fertilizer_rate]
prices = [1.2, 0.8]  # السعر لكل وحدة لكل طبقة معدل
costs = geopard.calculate_costs(rates, prices)

احسب التكاليف الإجمالية بناءً على معدلات الإضافة والأسعار باستخدام هذه الدالة. ومن خلال توفير application_rate_list من مجموعات بيانات تحتوي على السمات AppliedRate وبالمقابل price_per_unit_list، يمكنك تجميع النفقات المرتبطة بالأنشطة الزراعية المختلفة، بما يدعم إدارة الميزانية والتخطيط المالي. ويُستخدم الناتج كـ costs فيgeopard.calculate_profit.

calculate_revenue

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

احسب الإيرادات من مجموعة بيانات الغلة باستخدام هذه الدالة. ومن خلال إدخال yield_as_mass المرتبط بسمة مجموعة بيانات الغلة و yield_price_per_unit، يمكنك تقدير الدخل الناتج من إنتاج المحاصيل، مما يسهّل التقييمات الاقتصادية. ويُستخدم الناتج كـ costs فيgeopard.calculate_profit .

calculate_profit

profit = geopard.calculate_profit(revenue, costs)

حدّد الربح بطرح التكاليف من الإيرادات باستخدام هذه الدالة. ومن خلال توفير revenue و costs المتغيرات (من الدوال السابقة)، يمكنك بسهولة حساب المكسب المالي من العمليات الزراعية، مما يدعم تحليل الربحية واتخاذ القرار الاستراتيجي.

fill_value_for_range

# احتفظ فقط بالقيم بين 10 و20، واستبدل الباقي بـ 0
filtered = geopard.fill_value_for_range(layer, min_value=10, max_value=20, value_to_fill=0)

تقوم هذه الدالة بتصفية القيم ضمن نطاق محدد في الإدخال المصفوفة. ومن خلال توفير الإدخال المصفوفة، إلى جانب min_value الاختياري و max_value الاختياري، يمكنك عزل القيم التي تقع ضمن النطاق المطلوب. وتتيح المعلمة value_to_fill استبدال القيم خارج النطاق بقيمة محددة، مما يعزز عمليات تصفية البيانات وتطبيعها.

calculate_per_pixel_mae

mae_layer = geopard.calculate_per_pixel_mae(predicted_yield, observed_yield)

استخدم هذه الدالة لحساب متوسط الخطأ المطلق (MAE) لكل بكسل بين مجموعتي بيانات. وهي توفّر خريطة مكانية للفروق المطلقة. و"الفرق المطلق" هو ببساطة حجم الفجوة بين قيم البكسلات المناظرة، بغض النظر عمّا إذا كانت إحدى القيم أعلى أو أقل.

تساعد الدالة على تحديد المناطق ذات الفروقات الأكبر.

calculate_per_pixel_relative_deviation

relative_dev = geopard.calculate_per_pixel_relative_deviation(observed_yield, modeled_yield)

تحسب هذه الدالة الانحراف النسبي لكل بكسل بين مجموعتي بيانات، مع التعبير عن الفرق كنسبة مئوية من القيمة في dataset_1. وببساطة، تُظهر مقدار انحراف قيمة أحد البكسلات عن القيمة المناظرة في dataset_1 بالمعنى النسبي.

يُعد هذا النهج ذا قيمة خاصة عند تحليل التباينات في خصائص التربة أو غلة المحاصيل أو بيانات الاستشعار عن بُعد، لأنه يساعدك على رصد المناطق ذات الفروقات النسبية الكبيرة بسرعة.

calculate_difference

difference = geopard.calculate_difference(yield_2024, yield_2023)

تطرح هذه الدالة مجموعة بيانات من أخرى لإنشاء خريطة فروق. وهي تبرز المناطق التي تكون فيها القيم في إحدى مجموعتي البيانات أعلى أو أقل مقارنة بالأخرى، مما يسهل رصد الاتجاهات والتغيرات بمرور الوقت.

تُعد هذه الأداة مفيدة بشكل خاص لتصور التباينات في خصائص التربة أو غلة المحاصيل أو بيانات الاستشعار عن بُعد، مما يساعدك على تحديد المناطق التي قد تتطلب مزيدًا من التحليل أو التدخل بسرعة.

calculate_relative_difference

relative_diff = geopard.calculate_relative_difference(yield_2024, yield_2023)

تحسب هذه الدالة الفرق النسبي لكل بكسل من خلال تطبيع الفرق بين مجموعتي البيانات باستخدام القيم من dataset_2. وهذا يعني أنها تُظهر مدى أهمية التغير بالنسبة إلى مقدار dataset_2.

تُعد هذه المقارنة النسبية مفيدة بشكل خاص عند العمل مع مجموعات بيانات ذات مقاييس مختلفة، إذ تساعد على كشف التحولات النسبية في خصائص التربة أو غلال المحاصيل أو مخرجات الحساسات. ويساعد هذا النهج على تحديد المناطق ذات التباين الملحوظ.

calculate_normalized_difference

normalized_diff = geopard.calculate_normalized_difference(layer_1, layer_2)

تحسب هذه الدالة الفرق المُطبّع لكل بكسل من خلال تحجيم مجموعتي البيانات مقارنةً بأكبر قيمة عالمية فيهما. تجعل هذه العملية مجموعات البيانات قابلة للمقارنة مباشرة حتى إذا كانت تمتلك نطاقات مختلفة أصلًا.

توفر الخريطة الناتجة رؤية واضحة للتباينات في خصائص التربة وغلة المحاصيل وبيانات الاستشعار عن بُعد، مما يتيح لك تحديد الفروق الرئيسية وتقييمها بسرعة.

build_zones_by_intervals

# فواصل للتقسيم إلى مناطق
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

# خيارات 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,                                      # العملية1 كرقم ثابت
    {1: 2, 2: 4},                           # العملية2 كقاموس لكل منطقة
    np.array([[1, 1], [2, 3]], dtype=float) # العملية3 كطبقة راستر مستمرة
]

# الاستخدام
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 # أو []
)

تحسب هذه الدالة معدل إضافة المغذيات المطلوب (المادة الفعالة) لكل منطقة إدارة.

ويعتمد الحساب على:

• مستوى مغذٍ مستهدف،

• إمداد المغذيات المتاحة للنبات من التربة،

• والمغذيات المضافة بالفعل عبر العمليات السابقة (سماد عضوي، أسمدة، digestate، إلخ).

يمكن توفير عمليات المغذيات المضافة كثوابت، أو قيم لكل منطقة، أو طبقات راستر، أو أي مزيج من هذه الخيارات. ويتم حل جميع المدخلات وتجميعها تلقائيًا لكل منطقة.

افتراضيًا، يُحسب المعدل المطلوب على أنه الفرق بين المستوى المستهدف للمغذيات ومجموع إمداد التربة والمغذيات المضافة. وتُعاد النتيجة كخريطة راستر تحتوي كل منطقة فيها على معدل مغذيات موحّد.

convert_active_ingredient_and_product

# معامل التحويل من المادة الفعالة إلى المنتج والعكس
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

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

تقدّر هذه الدالة نسيج التربة حسب USDA لكل بكسل باستخدام نسب الرمل والطمي والطين.

قدّم ثلاث طبقات راستر بالنِّسب المئوية (0-100) تمثل كسور حجم الحبيبات. والناتج هو أسماء فئات USDA مثل sand, loamy_sand, sandy_loam, loam, silt_loam, sandy_clay_loam, clay_loam, silty_clay_loam, silty_clay, أو undefined عند كون المدخلات غير صالحة.

estimate_texture_class_based_on_fao_wrb

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) تمثل كسور حجم الحبيبات. والناتج هو رموز فئات FAO/WRB مثل S, LS, SL, L, SiL, Si, SCL, CL, SiCL, SC, SiC, C, HC, أو undefined عند كون المدخلات غير صالحة.

calculate_soil_bulk_density

bulk_density = geopard.calculate_soil_bulk_density(texture_class_layer, som_pct_layer)

تحسب هذه الدالة الكثافة الظاهرية للتربة (غ/سم³) بناءً على فئة النسيج ومادة التربة العضوية الاختيارية (SOM).

يمكن أن يكون texture_class_layer يجب أن تحتوي على أسماء الفئات أو الرموز الناتجة عن دالة النسيج USDA أو دالة النسيج FAO/WRB المذكورتين أعلاه.

إذا تم توفير som_pct_layer كنسبة مئوية، فإن الدالة تعدّل الكثافة الظاهرية باستخدام SOM. وإلا، فإنها تُرجع قيم الكثافة الظاهرية للتربة بوحدة غ/سم³ المرتبطة بفئات النسيج وفقًا لمرجع USDA أو FAO/WRB.