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. حالة دعم توجيه البيانات الوصفية#
يدعم جميع المستهلكين (أي المقدرات البسيطة التي تستهلك البيانات الوصفية فقط ولا توجهها) توجيه البيانات الوصفية، مما يعني أنه يمكن استخدامها داخل المقدرات الوصفية التي تدعم توجيه البيانات الوصفية. ومع ذلك، فإن تطوير دعم توجيه البيانات الوصفية للمقدرات الوصفية قيد التقدم، وهنا قائمة بالمقدرات الوصفية والأدوات التي تدعم ولا تدعم توجيه البيانات الوصفية بعد.
المقدرات الوصفية والوظائف التي تدعم توجيه البيانات الوصفية:
المقدرات الوصفية والأدوات التي لا تدعم توجيه البيانات الوصفية بعد: