1. توجيه (إدارة) البيانات الوصفية#

ملاحظة

واجهة برمجة تطبيقات توجيه البيانات الوصفية تجريبية، ولم يتم تنفيذها بعد لجميع المقدرات. يرجى الرجوع إلى قائمة النماذج المدعومة وغير المدعومة لمزيد من المعلومات. قد تتغير بدون دورة الإهلاك المعتادة. افتراضيًا، هذه الميزة غير ممكّنة. يمكنك تمكينه عن طريق تعيين علامة enable_metadata_routing إلى True:

>>> import sklearn
>>> sklearn.set_config(enable_metadata_routing=True)

لاحظ أن الطرق والمتطلبات المقدمة في هذه الوثيقة ذات صلة فقط إذا كنت تريد تمرير metadata (على سبيل المثال sample_weight) إلى طريقة. إذا كنت تمرر فقط X و y ولا توجد معلمة / بيانات وصفية أخرى إلى طرق مثل fit، transform، وما إلى ذلك، فلن تحتاج إلى تعيين أي شيء.

يوضح هذا الدليل كيف يمكن توجيه metadata وتمريرها بين الكائنات في scikit-learn. إذا كنت تقوم بتطوير مقدر أو مقدر وصفية متوافق مع scikit-learn، فيمكنك مراجعة دليل المطور ذي الصلة: توجيه البيانات الوصفية.

البيانات الوصفية هي بيانات يأخذها المقدر أو المسجل أو مقسم CV في الاعتبار إذا قام المستخدم بتمريرها صراحةً كمعلمة. على سبيل المثال، يقبل KMeans sample_weight في طريقة fit() ويعتبرها لحساب مراكزها. يتم استهلاك classes بواسطة بعض المصنفات ويتم استخدام groups في بعض الموصلات، ولكن يمكن اعتبار أي بيانات يتم تمريرها إلى طرق كائن بصرف النظر عن X و y كبيانات وصفية. قبل إصدار scikit-learn 1.3، لم تكن هناك واجهة برمجة تطبيقات واحدة لتمرير البيانات الوصفية مثل ذلك إذا تم استخدام هذه الكائنات جنبًا إلى جنب مع كائنات أخرى، على سبيل المثال مسجل يقبل sample_weight داخل GridSearchCV.

مع Metadata Routing API، يمكننا نقل البيانات الوصفية إلى المقدرات والمسجلين ومقسمات CV باستخدام meta-estimators (مثل Pipeline أو GridSearchCV) أو وظائف مثل cross_validate التي توجه البيانات إلى كائنات أخرى. من أجل تمرير البيانات الوصفية إلى طريقة مثل fit أو score، يجب أن يطلبها الكائن الذي يستهلك البيانات الوصفية. يتم ذلك عبر طرق set_{method}_request()، حيث يتم استبدال {method} باسم الطريقة التي تطلب البيانات الوصفية. على سبيل المثال، ستستخدم المقدرات التي تستخدم البيانات الوصفية في طريقة fit() set_fit_request()، وسيستخدم المسجلون set_score_request(). تسمح لنا هذه الطرق بتحديد البيانات الوصفية المطلوبة، على سبيل المثال set_fit_request(sample_weight=True).

بالنسبة للموصلات المجمعة مثل GroupKFold، يتم طلب معلمة groups افتراضيًا. من الأفضل توضيح ذلك من خلال الأمثلة التالية.

1.1. أمثلة الاستخدام#

نقدم هنا بعض الأمثلة لإظهار بعض حالات الاستخدام الشائعة. هدفنا هو تمرير sample_weight و groups من خلال cross_validate، التي توجه البيانات الوصفية إلى LogisticRegressionCV وإلى مسجل مخصص تم إجراؤه باستخدام make_scorer، وكلاهما يمكنه استخدام البيانات الوصفية في طرقهما. في هذه الأمثلة، نريد تعيين ما إذا كان سيتم استخدام البيانات الوصفية بشكل فردي داخل consumers المختلفة.

تتطلب الأمثلة في هذا القسم الواردات والبيانات التالية:

>>> import numpy as np
>>> from sklearn.metrics import make_scorer, accuracy_score
>>> from sklearn.linear_model import LogisticRegressionCV, LogisticRegression
>>> from sklearn.model_selection import cross_validate, GridSearchCV, GroupKFold
>>> from sklearn.feature_selection import SelectKBest
>>> from sklearn.pipeline import make_pipeline
>>> n_samples, n_features = 100, 4
>>> rng = np.random.RandomState(42)
>>> X = rng.rand(n_samples, n_features)
>>> y = rng.randint(0, 2, size=n_samples)
>>> my_groups = rng.randint(0, 10, size=n_samples)
>>> my_weights = rng.rand(n_samples)
>>> my_other_weights = rng.rand(n_samples)

1.1.1. التسجيل المرجح والملاءمة#

يطلب الموصل المستخدم داخليًا في LogisticRegressionCV، GroupKFold، groups افتراضيًا. ومع ذلك، نحتاج إلى طلب sample_weight صراحةً له وللمسجل المخصص لدينا عن طريق تحديد sample_weight=True في طريقة LogisticRegressionCV`s `set_fit_request() وفي طريقة make_scorer`s `set_score_request. يعرف كل من consumers كيفية استخدام sample_weight في طرقهما fit() أو score(). يمكننا بعد ذلك تمرير البيانات الوصفية في cross_validate التي ستوجهها إلى أي مستهلكين نشطين:

>>> weighted_acc = make_scorer(accuracy_score).set_score_request(sample_weight=True)
>>> lr = LogisticRegressionCV(
...     cv=GroupKFold(),
...     scoring=weighted_acc
... ).set_fit_request(sample_weight=True)
>>> cv_results = cross_validate(
...     lr,
...     X,
...     y,
...     params={"sample_weight": my_weights, "groups": my_groups},
...     cv=GroupKFold(),
...     scoring=weighted_acc,
... )

لاحظ أنه في هذا المثال، تقوم cross_validate بتوجيه my_weights إلى كل من المسجل و LogisticRegressionCV.

إذا مررنا sample_weight في معلمات cross_validate، ولكن لم نقم بتعيين أي كائن لطلبه، فسيتم رفع UnsetMetadataPassedError، مما يشير إلينا إلى أننا نحتاج إلى تعيين مكان توجيهه صراحةً. ينطبق الشيء نفسه إذا تم تمرير params={"sample_weights": my_weights، ...} (لاحظ الخطأ المطبعي، أي weights بدلاً من weight)، نظرًا لأن sample_weights لم يتم طلبها بواسطة أي من الكائنات الأساسية.

1.1.2. التسجيل المرجح والملاءمة غير المرجحة#

عند تمرير البيانات الوصفية مثل sample_weight إلى router (meta-estimators أو دالة التوجيه)، تتطلب جميع consumers sample_weight أن يتم طلب الأوزان صراحةً أو عدم طلبها صراحةً (على سبيل المثال True أو False). وبالتالي، لإجراء ملاءمة غير مرجحة، نحتاج إلى تكوين LogisticRegressionCV لعدم طلب أوزان العينة، بحيث لا تمرر cross_validate الأوزان على طول:

>>> weighted_acc = make_scorer(accuracy_score).set_score_request(sample_weight=True)
>>> lr = LogisticRegressionCV(
...     cv=GroupKFold(), scoring=weighted_acc,
... ).set_fit_request(sample_weight=False)
>>> cv_results = cross_validate(
...     lr,
...     X,
...     y,
...     cv=GroupKFold(),
...     params={"sample_weight": my_weights, "groups": my_groups},
...     scoring=weighted_acc,
... )

إذا لم يتم استدعاء linear_model.LogisticRegressionCV.set_fit_request، فستثير cross_validate خطأً لأن sample_weight تم تمريره ولكن LogisticRegressionCV لن يتم تكوينه صراحةً للتعرف على الأوزان.

1.1.3. اختيار الميزة غير المرجحة#

لا يكون توجيه البيانات الوصفية ممكنًا إلا إذا كانت طريقة الكائن تعرف كيفية استخدام البيانات الوصفية، مما يعني في معظم الحالات أنها تحتوي عليها كمعلمة صريحة. عندها فقط يمكننا تعيين قيم الطلب للبيانات الوصفية باستخدام set_fit_request(sample_weight=True)، على سبيل المثال. هذا يجعل الكائن consumer.

على عكس LogisticRegressionCV، لا يمكن لـ SelectKBest استهلاك الأوزان وبالتالي لا يتم تعيين قيمة طلب لـ sample_weight على مثيله ولا يتم توجيه sample_weight إليه:

>>> weighted_acc = make_scorer(accuracy_score).set_score_request(sample_weight=True)
>>> lr = LogisticRegressionCV(
...     cv=GroupKFold(), scoring=weighted_acc,
... ).set_fit_request(sample_weight=True)
>>> sel = SelectKBest(k=2)
>>> pipe = make_pipeline(sel, lr)
>>> cv_results = cross_validate(
...     pipe,
...     X,
...     y,
...     cv=GroupKFold(),
...     params={"sample_weight": my_weights, "groups": my_groups},
...     scoring=weighted_acc,
... )

1.1.4. أوزان تسجيل وملاءمة مختلفة#

على الرغم من أن كل من make_scorer و LogisticRegressionCV يتوقعان المفتاح sample_weight، يمكننا استخدام الأسماء المستعارة لتمرير أوزان مختلفة إلى مستهلكين مختلفين. في هذا المثال، نمرر scoring_weight إلى المسجل، و fitting_weight إلى LogisticRegressionCV:

>>> weighted_acc = make_scorer(accuracy_score).set_score_request(
...    sample_weight="scoring_weight"
... )
>>> lr = LogisticRegressionCV(
...     cv=GroupKFold(), scoring=weighted_acc,
... ).set_fit_request(sample_weight="fitting_weight")
>>> cv_results = cross_validate(
...     lr,
...     X,
...     y,
...     cv=GroupKFold(),
...     params={
...         "scoring_weight": my_weights,
...         "fitting_weight": my_other_weights,
...         "groups": my_groups,
...     },
...     scoring=weighted_acc,
... )

1.2. واجهة API#

consumer هو كائن (مقدر، مقدر وصفية، مسجل، مقسم) يقبل ويستخدم بعض metadata في طريقة واحدة على الأقل من طرقه (على سبيل المثال fit، predict، inverse_transform، transform، score، split). المقدرات الوصفية التي تقوم فقط بإعادة توجيه البيانات الوصفية إلى كائنات أخرى (مقدرات تابعة، أو مسجلون، أو مقسمات) ولا تستخدم البيانات الوصفية نفسها ليست مستهلكين. (Meta-) المقدرات التي توجه البيانات الوصفية إلى كائنات أخرى هي routers. يمكن أن يكون (n) (meta-) المقدر consumer و router في نفس الوقت. تعرض (Meta-) المقدرات والموصلات طريقة set_{method}_request لكل طريقة تقبل بيانات وصفية واحدة على الأقل. على سبيل المثال، إذا كان المقدر يدعم sample_weight في fit و score، فإنه يعرض estimator.set_fit_request(sample_weight=value) و estimator.set_score_request(sample_weight=value). هنا يمكن أن تكون value:

  • True: تطلب الطريقة sample_weight. هذا يعني أنه إذا تم توفير البيانات الوصفية، فسيتم استخدامها، وإلا فلن يتم رفع أي خطأ.

  • False: لا تطلب الطريقة sample_weight.

  • None: سيرفع جهاز التوجيه خطأً إذا تم تمرير sample_weight. هذه هي القيمة الافتراضية في جميع الحالات تقريبًا عند إنشاء مثيل لكائن وتضمن أن يقوم المستخدم بتعيين طلبات البيانات الوصفية صراحةً عند تمرير البيانات الوصفية. الاستثناء الوحيد هو مقسمات Group*Fold.

  • "param_name": اسم مستعار لـ sample_weight إذا أردنا تمرير أوزان مختلفة إلى مستهلكين مختلفين. إذا تم استخدام الاسم المستعار، فلا ينبغي أن يقوم المقدر الوصفي بإعادة توجيه "param_name" إلى المستهلك، ولكن sample_weight بدلاً من ذلك، لأن المستهلك سيتوقع معلمة تسمى sample_weight. هذا يعني أن التعيين بين البيانات الوصفية التي يتطلبها الكائن، على سبيل المثال sample_weight واسم المتغير الذي يوفره المستخدم، على سبيل المثال my_weights يتم على مستوى جهاز التوجيه، وليس بواسطة الكائن المستهلك نفسه.

يتم طلب البيانات الوصفية بنفس الطريقة للمسجلين باستخدام set_score_request.

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

>>> param_grid = {"C": [0.1, 1]}
>>> lr = LogisticRegression().set_fit_request(sample_weight=True)
>>> try:
...     GridSearchCV(
...         estimator=lr, param_grid=param_grid
...     ).fit(X, y, sample_weight=my_weights)
... except ValueError as e:
...     print(e)
[sample_weight] تم تمريرها ولكن لم يتم تعيينها صراحةً على أنها مطلوبة أو غير مطلوبة لـ LogisticRegression.score، والتي يتم استخدامها داخل GridSearchCV.fit.
اتصل بـ `LogisticRegression.set_score_request({metadata}=True/False)` لكل بيانات وصفية
تريد طلبها / تجاهلها.

يمكن إصلاح المشكلة عن طريق تعيين قيمة الطلب صراحةً:

>>> lr = LogisticRegression().set_fit_request(
...     sample_weight=True
... ).set_score_request(sample_weight=False)

في نهاية قسم أمثلة الاستخدام، نقوم بتعطيل علامة التكوين لتوجيه البيانات الوصفية:

>>> sklearn.set_config(enable_metadata_routing=False)

1.3. حالة دعم توجيه البيانات الوصفية#

يدعم جميع المستهلكين (أي المقدرات البسيطة التي تستهلك البيانات الوصفية فقط ولا توجهها) توجيه البيانات الوصفية، مما يعني أنه يمكن استخدامها داخل المقدرات الوصفية التي تدعم توجيه البيانات الوصفية. ومع ذلك، فإن تطوير دعم توجيه البيانات الوصفية للمقدرات الوصفية قيد التقدم، وهنا قائمة بالمقدرات الوصفية والأدوات التي تدعم ولا تدعم توجيه البيانات الوصفية بعد.

المقدرات الوصفية والوظائف التي تدعم توجيه البيانات الوصفية:

المقدرات الوصفية والأدوات التي لا تدعم توجيه البيانات الوصفية بعد: