link and formatting fix (#432)

aduquett · web-flow · commit 5b5c4902e08b · 2024-08-28T16:01:41.000-04:00
* link and formatting fix

* link and formatting fix

* link and formatting fix
diff --git a/images/explainer-lime.png b/images/explainer-lime.png
diff --git a/images/explainer-shap.png b/images/explainer-shap.png
diff --git a/modules/configuring-trustyai-with-a-database.adoc b/modules/configuring-trustyai-with-a-database.adoc
@@ -13,7 +13,7 @@ If you have a relational database in your {openshift-platform} cluster such as M
 
 * You have downloaded and installed the OpenShift command-line interface (CLI). See link:https://docs.openshift.com/container-platform/{ocp-latest-version}/cli_reference/openshift_cli/getting-started-cli.html#installing-openshift-cli[Installing the OpenShift CLI].
 
-* You have enabled the TrustyAI component, as described in _Enabling the TrustyAI component_.
+* You have enabled the TrustyAI component, as described in link:{odhdocshome}/monitoring-data-science-models/#enabling-trustyai-component_monitor[Enabling the TrustyAI component].
 
 ifndef::upstream[]
 * The data scientist has created a data science project, as described in link:{rhoaidocshome}{default-format-url}/working_on_data_science_projects/using-data-science-projects_projects#creating-a-data-science-project_projects[Creating a data science project], that contains the models that the data scientist wants to monitor.  
diff --git a/modules/creating-a-bias-metric-using-cli.adoc b/modules/creating-a-bias-metric-using-cli.adoc
@@ -9,17 +9,17 @@ You can use the OpenShift command-line interface (CLI) to create a bias metric f
 .Prerequisites
 
 ifndef::upstream[]
-* You are familiar with link:{rhoaidocshome}{default-format-url}/monitoring_data_science_models/supported-bias-metrics_monitor[the bias metrics that {productname-short} supports] and how to interpret them.
+* You are familiar with link:{rhoaidocshome}{default-format-url}/monitoring_data_science_models/supported-bias-metrics_bias-monitoring[the bias metrics that {productname-short} supports] and how to interpret them.
 endif::[]
 ifdef::upstream[]
-* You are familiar with link:{odhdocshome}/monitoring-data-science-models/#supported-bias-metrics_monitor[the bias metrics that {productname-short} supports] and how to interpret them.
+* You are familiar with link:{odhdocshome}/monitoring-data-science-models/#supported-bias-metrics_bias-monitoring[the bias metrics that {productname-short} supports] and how to interpret them.
 endif::[]
 
 * You are familiar with the specific data set schema and understand the names and meanings of the inputs and outputs.
 
 * Your OpenShift cluster administrator added you as a user to the {openshift-platform} cluster and has installed the TrustyAI service for the data science project that contains the deployed models.
 
-* You set up TrustyAI for your data science project, as described in _Setting up TrustyAI for your project_.
+* You set up TrustyAI for your data science project, as described in link:{odhdocshome}/monitoring-data-science-models/#setting-up-trustyai-for-your-project_monitor[Setting up TrustyAI for your project].
 
 .Procedure
 
diff --git a/modules/creating-a-bias-metric-using-dashboard.adoc b/modules/creating-a-bias-metric-using-dashboard.adoc
@@ -8,17 +8,17 @@ You can use the {productname-short} dashboard to create a bias metric for a mode
 
 .Prerequisites
 ifndef::upstream[]
-* You are familiar with link:{rhoaidocshome}{default-format-url}/monitoring_data_science_models/supported-bias-metrics_monitor[the bias metrics that {productname-short} supports] and how to interpret them.
+* You are familiar with link:{rhoaidocshome}{default-format-url}/monitoring_data_science_models/supported-bias-metrics_bias-monitoring[the bias metrics that {productname-short} supports] and how to interpret them.
 endif::[]
 ifdef::upstream[]
-* You are familiar with link:{odhdocshome}/monitoring-data-science-models/#supported-bias-metrics_monitor[the bias metrics that {productname-short} supports] and how to interpret them.
+* You are familiar with link:{odhdocshome}/monitoring-data-science-models/#supported-bias-metrics_bias-monitoring[the bias metrics that {productname-short} supports] and how to interpret them.
 endif::[]
 
 * You are familiar with the specific data set schema and understand the names and meanings of the inputs and outputs.
 
 * Your OpenShift cluster administrator added you as a user to the {openshift-platform} cluster and has installed the TrustyAI service for the data science project that contains the deployed models.
 
-* You set up TrustyAI for your data science project, as described in _Setting up TrustyAI for your project_.
+* You set up TrustyAI for your data science project, as described in link:{odhdocshome}/monitoring-data-science-models/#setting-up-trustyai-for-your-project_monitor[Setting up TrustyAI for your project].
 
 .Procedure
 . Optional: To set the `TRUSTY_ROUTE` variable, follow these steps. 
diff --git a/modules/creating-a-drift-metric-using-cli.adoc b/modules/creating-a-drift-metric-using-cli.adoc
@@ -12,7 +12,7 @@ You can use the OpenShift command-line interface (CLI) to create a data drift me
 
 * Your OpenShift cluster administrator added you as a user to the {openshift-platform} cluster and has installed the TrustyAI service for the data science project that contains the deployed models.
 
-* You set up TrustyAI for your data science project, as described in _Setting up TrustyAI for your project_.
+* You set up TrustyAI for your data science project, as described in link:{odhdocshome}/monitoring-data-science-models/#setting-up-trustyai-for-your-project_monitor[Setting up TrustyAI for your project].
 
 .Procedure
 
diff --git a/modules/duplicating-a-bias-metric.adoc b/modules/duplicating-a-bias-metric.adoc
@@ -8,10 +8,10 @@ If you want to edit an existing metric, you can duplicate (copy) it in the {prod
 
 .Prerequisites
 ifndef::upstream[]
-* You are familiar with link:{rhoaidocshome}{default-format-url}/monitoring_data_science_models/supported-bias-metrics_monitor[the bias metrics that {productname-short} supports] and how to interpret them.
+* You are familiar with link:{rhoaidocshome}{default-format-url}/monitoring_data_science_models/supported-bias-metrics_bias-monitoring[the bias metrics that {productname-short} supports] and how to interpret them.
 endif::[]
 ifdef::upstream[]
-* You are familiar with link:{odhdocshome}/monitoring-data-science-models/#supported-bias-metrics_monitor[the bias metrics that {productname-short} supports] and how to interpret them.
+* You are familiar with link:{odhdocshome}/monitoring-data-science-models/#supported-bias-metrics_bias-monitoring[the bias metrics that {productname-short} supports] and how to interpret them.
 endif::[]
 
 * You are familiar with the specific data set schema and understand the names and meanings of the inputs and outputs.
@@ -26,7 +26,7 @@ endif::[]
 . On the *Bias metric configuration* page, click the action menu (&#8942;) next to the metric that you want to copy and then click *Duplicate*.
 . In the *Configure bias metric* dialog, follow these steps:
 .. In the *Metric name* field, type a unique name for your bias metric. Note that you cannot change the name of this metric later.
-.. Change the values of the fields as needed. For a description of these fields, see _Creating a bias metric by using the dashboard_.
+.. Change the values of the fields as needed. For a description of these fields, see link:{odhdocshome}/monitoring-data-science-models/#creating-a-bias-metric-using-dashboard_bias-monitoring[Creating a bias metric by using the dashboard].
 .  Ensure that the values you entered are correct, and then click *Configure*.
 
 .Verification
diff --git a/modules/enabling-trustyai-component.adoc b/modules/enabling-trustyai-component.adoc
@@ -50,5 +50,5 @@ Check the status as follows:
 +
 When the status of the *trustyai-service-operator-controller-manager-_<pod-id>_* pod is *Running*, the pod is ready to use.
 
-.Next step
-link:{odhdocshome}/monitoring-data-science-models/#configuring-trustyai-with-a-database_monitor[Configuring TrustyAI with a database]
+//.Next step
+//Configuring TrustyAI with a database
diff --git a/modules/installing-trustyai-service-using-cli.adoc b/modules/installing-trustyai-service-using-cli.adoc
@@ -12,16 +12,16 @@ You can use the OpenShift command-line interface (CLI) to install an instance of
 
 * You have downloaded and installed the OpenShift command-line interface (CLI). See link:https://docs.openshift.com/container-platform/{ocp-latest-version}/cli_reference/openshift_cli/getting-started-cli.html#installing-openshift-cli[Installing the OpenShift CLI].
 
-* You have configured monitoring for the model serving platform, as described in _Configuring monitoring for the multi-model serving platform_.
+* You have configured monitoring for the model serving platform, as described in link:{odhdocshome}/monitoring-data-science-models/#configuring-monitoring-for-the-multi-model-serving-platform_monitor[Configuring monitoring for the multi-model serving platform].
 
 [NOTE]
 ====
 Model monitoring with TrustyAI is only available on the ModelMesh-based _multi-model serving platform_. Model monitoring with TrustyAI is unavailable on the KServe-based _single-model serving platform_.
 ====
 
-* You have enabled the TrustyAI component, as described in _Enabling the TrustyAI component_.
+* You have enabled the TrustyAI component, as described in link:{odhdocshome}/monitoring-data-science-models/#enabling-trustyai-component_monitor[Enabling the TrustyAI component].
 
-* If you are using TrustyAI with a database instead of PVC, you have configured TrustyAI to use the database, as described in _Configuring TrustyAI with a database_.
+* If you are using TrustyAI with a database instead of PVC, you have configured TrustyAI to use the database, as described in link:{odhdocshome}/monitoring-data-science-models/#configuring-trustyai-with-a-database_monitor[Configuring TrustyAI with a database].
 
 ifndef::upstream[]
 * The data scientist has created a data science project, as described in link:{rhoaidocshome}{default-format-url}/working_on_data_science_projects/using-data-science-projects_projects#creating-a-data-science-project_projects[Creating a data science project], that contains the models that the data scientist wants to monitor.  
diff --git a/modules/installing-trustyai-service-using-dashboard.adoc b/modules/installing-trustyai-service-using-dashboard.adoc
@@ -8,16 +8,16 @@ You can use the {productname-short} dashboard to install an instance of the Trus
 
 .Prerequisites
 
-* A cluster administrator has configured monitoring for the model serving platform, as described in _Configuring monitoring for the multi-model serving platform_.
+* A cluster administrator has configured monitoring for the model serving platform, as described in link:{odhdocshome}/monitoring-data-science-models/#configuring-monitoring-for-the-multi-model-serving-platform_monitor[Configuring monitoring for the multi-model serving platform].
 
 [NOTE]
 ====
 Model monitoring with TrustyAI is only available on the ModelMesh-based _multi-model serving platform_. Model monitoring with TrustyAI is unavailable on the KServe-based _single-model serving platform_.
 ====
 
-* A cluster administrator has enabled the TrustyAI component, as described in _Enabling the TrustyAI component_.
+* A cluster administrator has enabled the TrustyAI component, as described in link:{odhdocshome}/monitoring-data-science-models/#enabling-trustyai-component_monitor[Enabling the TrustyAI component].
 
-* If you are using TrustyAI with a database instead of PVC, a cluster administrator has configured TrustyAI to use the database, as described in _Configuring TrustyAI with a database_.
+* If you are using TrustyAI with a database instead of PVC, a cluster administrator has configured TrustyAI to use the database, as described in link:{odhdocshome}/monitoring-data-science-models/#configuring-trustyai-with-a-database_monitor[Configuring TrustyAI with a database].
 
 ifndef::upstream[]
 * If you are using specialized {productname-short} groups, you are part of the administrator group (for example, {oai-admin-group}). If you are not using specialized groups, you are part of the {openshift-platform} administrator group.
diff --git a/modules/labeling-data-fields.adoc b/modules/labeling-data-fields.adoc
@@ -10,7 +10,7 @@ After you send model training data to TrustyAI, you might want to apply a set of
 
 * Your OpenShift cluster administrator added you as a user to the {openshift-platform} cluster and has installed the TrustyAI service for the data science project that contains the deployed models.
 
-* You sent training data to TrustyAI as described in _Sending training data to TrustyAI_.
+* You sent training data to TrustyAI as described in link:{odhdocshome}/monitoring-data-science-models/#sending-training-data-to-trustyai_monitor[Sending training data to TrustyAI].
 
 .Procedure
 
diff --git a/modules/sending-training-data-to-trustyai.adoc b/modules/sending-training-data-to-trustyai.adoc
@@ -10,7 +10,7 @@ To use TrustyAI for bias monitoring or data drift detection, you must send train
 
 * Your OpenShift cluster administrator added you as a user to the {openshift-platform} cluster and has installed the TrustyAI service for the data science project that contains the deployed models.
 
-* You authenticated the TrustyAI service as described in _Authenticating the TrustyAI service_.
+* You authenticated the TrustyAI service as described in link:{odhdocshome}/serving-models/#authenticating-trustyai-service_monitor[Authenticating the TrustyAI service].
 
 * Your deployed model is registered with TrustyAI. 
 +
diff --git a/modules/supported-explainers.adoc b/modules/supported-explainers.adoc
@@ -1,5 +1,5 @@
 :_module-type: REFERENCE
-:stem:
+:stem: 
 
 [id="supported-explainers_{context}"]
 = Supported explainers
@@ -8,40 +8,24 @@
 
 *LIME*
 
-_Local Interpretable Model-agnostic Explanations_ (LIME) footnote:1[Marco Tulio Ribeiro, Sameer Singh, Carlos Guestrin. "Why Should I Trust You?": Explaining the Predictions of Any Classifier." _Proceedings of the 22nd ACM SIGKDD International Conference on Knowledge Discovery and Data mining_, 2016. Pages 1135-1144.] is a saliency explanation method. LIME aims to explain a prediction stem:[p = (x, y)] (an input-output pair) generated by a black-box model stem:[f : \mathbb{R}^d \rightarrow \mathbb{R}]. The explanations come in the form of a "saliency" stem:[w_i] attached to each feature stem:[x_i] in the prediction input stem:[x]. LIME generates a local explanation stem:[\xi(x)] according to the following model:
+_Local Interpretable Model-agnostic Explanations_ (LIME) footnote:1[Marco Tulio Ribeiro, Sameer Singh, Carlos Guestrin. "Why Should I Trust You?": Explaining the Predictions of Any Classifier." _Proceedings of the 22nd ACM SIGKDD International Conference on Knowledge Discovery and Data mining_, 2016. Pages 1135-1144.] is a saliency explanation method. LIME aims to explain a prediction &#119901; &#61; &#40;&#119909;, &#119910;&#41; (an input-output pair) generated by a black-box model &#119891; &#58;  &#8477;^&#119889;^ &#8594; &#8477;. The explanations come in the form of a "saliency" &#119908;~&#119894;~ attached to each feature &#119909;~&#119894;~ in the prediction &#119909;. LIME generates a local explanation &#958;&#40;&#119909;&#41; according to the following model:
 
-[stem]
-++++
-\xi(x) = \arg\min_{g \in G}L(f, g, \pi_x) + \Omega(g)
-++++
+image::images/explainer-lime.png[LIME model, scale=60, align="center"]
 
-* stem:[\pi_x] is a proximity function
-* stem:[G] the family of interpretable models
-* stem:[\Omega(g)] is a measure of complexity of an explanation stem:[g \in G]
-* stem:[L(f, g, \pi_x)] is a measure of how unfaithful stem:[g] is in approximating stem:[f] in the locality defined by stem:[\pi_x]
+* &#120587;~&#119909;~ is a proximity function
+* &#119866; is the family of interpretable models
+* &#937;&#40;&#119892;&#41; is a measure of complexity of an explanation &#119892; &#8712; &#119866;
+* &#119871;&#40;&#119891;, &#119892;, &#120587;~&#119909;~&#41; is a measure of how unfaithful &#119892; is in approximating &#119891; in the locality defined by &#120587;~&#119909;~ 
 
-In the original paper, G is the class of linear models and πx is an exponential kernel on a distance function stem:[D] (for example, cosine distance). LIME converts samples stem:[x_i] from the original domain into interpretable samples as binary vectors stem:[x^{\prime}_i \in {0, 1}]. An encoded data set stem:[E] is built by taking nonzero elements of stem:[x^{\prime}_i], recovering the original representation stem:[z \in \mathbb{R}^d] and then computing stem:[f(z)]. A weighted linear model stem:[g] (with weights provided via stem:[\pi_x]) is then trained on the generated sparse data set stem:[E] and the model weights stem:[w] are used as feature weights for the final explanation stem:[\xi(x)].
+In the original paper, &#119866; is the class of linear models and &#120587;~&#119909;~ is an exponential kernel on a distance function &#119863; (for example, cosine distance). LIME converts samples &#119909;~&#119894;~ from the original domain into interpretable samples as binary vectors &#119909;&#8242;~&#119894;~ &#8712; 0,1. An encoded data set &#119864; is built by taking nonzero elements of &#119909;&#8242;~&#119894;~ , recovering the original representation &#119911; &#8712; &#8477;^&#119889;^ and then computing &#119891;&#40;&#119911;&#41;. A weighted linear model &#119892; (with weights provided via &#120587;~&#119909;~) is then trained on the generated sparse data set &#119864; and the model weights &#119908; are used as feature weights for the final explanation &#958;&#40;&#119909;&#41;.
 
 *SHAP*
 
-_SHapley Additive exPlanations_ (SHAP), footnote:[Scott Lundberg, Su-In Lee. "A Unified Approach to Interpreting Model Predictions." _Advances in Neural Information Processing Systems_, 2017.] seeks to unify several common explanation methods, notably LIME footnote:1[] and DeepLIFT, footnote:[Avanti Shrikumar, Peyton Greenside, Anshul Kundaje. "Learning Important Features Through Propagating Activation Differences." _CoRR abs/1704.02685_, 2017.] under a common umbrella of additive feature attributions. These methods explain how an input stem:[x = [x_1, x_2, ..., x_M ]] affects the output of some model stem:[f] by transforming stem:[x \in \mathbb{R}^M] into simplified inputs stem:[z^{\prime} \in 0, 1^M] , such that stem:[z^{\prime}_i] indicates the inclusion or exclusion of feature stem:[i]. The simplified inputs are then passed to an explanatory model stem:[g] that takes the following form:
+_SHapley Additive exPlanations_ (SHAP), footnote:[Scott Lundberg, Su-In Lee. "A Unified Approach to Interpreting Model Predictions." _Advances in Neural Information Processing Systems_, 2017.] seeks to unify several common explanation methods, notably LIME footnote:1[] and DeepLIFT, footnote:[Avanti Shrikumar, Peyton Greenside, Anshul Kundaje. "Learning Important Features Through Propagating Activation Differences." _CoRR abs/1704.02685_, 2017.] under a common umbrella of additive feature attributions. These methods explain how an input &#119909; &#61; &#91;&#119909;~1~, &#119909;~2~, ..., &#119909;~&#119872;~&#93; affects the output of some model &#119891; by transforming &#119909; &#8712; &#8477;^&#119872;^ into simplified inputs &#119911;&#8242; &#8712; 0, 1^&#119872;^ , such that &#119911;&#8242;~&#119894;~ indicates the inclusion or exclusion of feature &#119894;. The simplified inputs are then passed to an explanatory model &#119892; that takes the following form:
 
-[stem]
-++++
-x = h_x(z^{\prime}) \\
-++++
+image::images/explainer-shap.png[SHAP explanatory model, scale=60, align="center"]
 
-[stem]
-++++
-g(z^{\prime}) = \phi_0 + \sum_{i=1}^M \phi_i z_i^{\prime} \\
-++++
-
-[stem]
-++++
-\textbf{s.t.}\quad g(z^{\prime}) \approx f (h_x(z^{\prime}))
-++++
-
-In that form, each value stem:[\phi_i] marks the contribution that feature stem:[i] had on the output model (called the attribution), and stem:[\phi_0] marks the null output of the model; the model output when every feature is excluded. Therefore, this presents an easily interpretable explanation of the importance of each feature and a framework to permute the various input features to establish their collection contributions.
+In that form, each value &#120567;~&#119894;~ marks the contribution that feature &#119894; had on the output model (called the attribution), &#120567;~0~ marks the null output of the model; the model output when every feature is excluded. Therefore, this presents an easily interpretable explanation of the importance of each feature and a framework to permute the various input features to establish their collection contributions.
 
 The final result of the algorithm are the Shapley values of each feature, which give an itemized "receipt" of all the contributing factors to the decision. For example, a SHAP explanation of a loan application might be as follows:
 

Original file line number	Diff line number	Diff line change
`@@ -50,5 +50,5 @@ Check the status as follows:`
`50`	`50`	`+`
`51`	`51`	`When the status of the trustyai-service-operator-controller-manager-_<pod-id>_ pod is Running, the pod is ready to use.`
`52`	`52`
`53`		`-.Next step`
`54`		`-link:{odhdocshome}/monitoring-data-science-models/#configuring-trustyai-with-a-database_monitor[Configuring TrustyAI with a database]`
	`53`	`+//.Next step`
	`54`	`+//Configuring TrustyAI with a database`