improve descriptions

subpages/losses.py

@@ -34,6 +34,9 @@ class LossesPage(Page):
         st.title(self.name)
         with st.expander("💡", expanded=True):
             st.write("Show count, mean and median loss per token and label.")
+            st.write(
+                "Look out for tokens that have a big gap between mean and median, indicating systematic labeling issues."
+            )
 
         col1, _, col2 = st.columns([8, 1, 6])
 
@@ -54,7 +57,7 @@ class LossesPage(Page):
             # st.dataframe(loss_by_label)
 
             st.write(
-                "_Attention: This statistic disregards that tokens have contextual representations._"
+                "_Caveat: Even though tokens have contextual representations, we average them to get these summary statistics._"
             )
 
         with col2:

subpages/lossy_samples.py

@@ -19,6 +19,15 @@ class LossySamplesPage(Page):
         st.title(self.name)
         with st.expander("💡", expanded=True):
             st.write("Show every example sorted by loss (descending) for close inspection.")
+            st.write(
+                "The **dataframe** is mostly self-explanatory. The cells are color-coded by label, a lighter color signifies a continuation label. Cells in the loss row are filled red from left to right relative to the top loss."
+            )
+            st.write(
+                "The **numbers to the left**: Top (black background) are sample number (listed here) and sample index (from the dataset). Below on yellow background is the total loss for the given sample."
+            )
+            st.write(
+                "The **annotated sample**: Every predicted entity (every token, really) gets a black border. The text color signifies the predicted label, with the first token of a sequence of token also showing the label's icon. If (and only if) the prediction is wrong, a small little box after the entity (token) contains the correct target class, with a background color corresponding to that class."
+            )
 
         st.subheader("💥 Samples ⬇loss")
         skip_correct = st.checkbox("Skip correct examples", value=True, key="skip_correct")

subpages/metrics.py

@@ -61,6 +61,9 @@ class MetricsPage(Page):
             st.write(
                 "The metrics page contains precision, recall and f-score metrics as well as a confusion matrix over all the classes. By default, the confusion matrix is normalized. There's an option to zero out the diagonal, leaving only prediction errors (here it makes sense to turn off normalization, so you get raw error counts)."
             )
+            st.write(
+                "With the confusion matrix, you don't want any of the classes to end up in the bottom right quarter: those are frequent but error-prone."
+            )
 
         eval_results = _get_evaluation(context.df)
         if len(eval_results.splitlines()) < 8:

subpages/random_samples.py

@@ -18,7 +18,7 @@ class RandomSamplesPage(Page):
         st.title("🎲 Random Samples")
         with st.expander("💡", expanded=True):
             st.write(
-                "Show random samples. Simple idea, but often it turns up some interesting things."
+                "Show random samples. Simple method, but it often turns up interesting things."
             )
 
         random_sample_size = st.number_input(

utils.py

@@ -81,12 +81,12 @@ def align_sample(row: pd.Series):
             tokens[-1] += tok.lstrip("▁").lstrip("##").rstrip("@@")
     out["tokens"] = tokens
 
-    if "labels" in columns:
-        out["labels"] = [row.labels[i] for i in indices]
-
     if "preds" in columns:
         out["preds"] = [row.preds[i] for i in indices]
 
+    if "labels" in columns:
+        out["labels"] = [row.labels[i] for i in indices]
+
     if "losses" in columns:
         out["losses"] = [row.losses[i] for i in indices]