feat: update installation guidances

Author: EdenWuyifan

content/docs/get-started/explore-matches.md

@@ -1,161 +1,186 @@
 ---
 weight: 200
 title: "Explore Matches"
-description: "Once the files finished loading, you will be presented with the main BDIViz interface."
+description: "Explore schema alignment candidates using the BDIViz interactive heatmap interface."
 icon: "zoom_in"
 date: "2025-04-19T13:38:17-04:00"
-lastmod: "2025-04-19T13:38:17-04:00"
+lastmod: "2025-04-21T11:00:00-04:00"
 draft: false
 toc: true
 ---
 
-> Once your files are uploaded, BDIViz will load the full interface for exploring match candidates between your source and target datasets.
+## Overview
+
+After uploading your files, BDIViz launches its main interface, allowing you to visually explore match candidates between your source dataset and the target schema.
+
+---
 
 ## Interactive Heatmap
 
-This is the central visual of BDIViz. Each cell in the heatmap represents a match candidate between a source attribute (on the y-axis) and a target attribute (on the x-axis).
+The heatmap is the primary visualization tool in BDIViz. Each cell represents a match candidate between a source attribute (y-axis) and a target attribute (x-axis).
 
 ![heatmap-gif](./images/interactive-heatmap.gif)
 
-
-### Heatmap Components
+### Key Features
 
 {{< tabs tabTotal="4">}}
-{{% tab tabName="Heatmap Nodes" %}}
 
-Each cell in the heatmap represents a match candidate between a source attribute (on the y-axis) and a target attribute (on the x-axis).
+{{% tab tabName="Heatmap Cells" %}}
 
-- Color intensity represents match strength: darker = higher match score.
-- Green indicates accepted matches; red indicates rejected ones.
-- Click on a node to inspect further details.
+Each cell corresponds to a potential match:
 
-{{% /tab %}}
-{{% tab tabName="X-Axis" %}}
+- **Color intensity** indicates similarity score (darker = stronger match).
+- **Green** = accepted match, **Red** = rejected match.
+- Click on a cell to inspect match details.
 
-![schema-hierarchy-gif](./images/schema-hierarchy.gif)
+{{% /tab %}}
 
-The x-axis of the heatmap represents the target schema’s attribute space in a structured, hierarchical layout—specifically designed to support the complexity of biomedical data models like the Genomic Data Commons (GDC).
+{{% tab tabName="X-Axis Hierarchy" %}}
 
-This hierarchy includes:
+![schema-hierarchy-gif](./images/schema-hierarchy.gif)
 
-- **Categories** (e.g., "clinical," "biospecimen")
-- **Nodes** (e.g., "diagnosis," "treatment")
-- **Target Attributes** as leaf nodes
+The x-axis displays the target schema's structure as a semantic hierarchy:
 
-Color coding helps differentiate between categories, while curved connectors visually represent hierarchical relationships. Users can hover over any part of the hierarchy to highlight supercategories, specific categories, or individual columns, aiding navigation and contextual understanding.
+- **Category Level**: e.g., `clinical`, `biospecimen`
+- **Node Level**: e.g., `diagnosis`, `treatment`
+- **Leaf Nodes**: individual target attributes
 
+Color and curved connectors help clarify relationships and improve navigation.
 
 {{% /tab %}}
-{{% tab tabName="Expandable Node" %}}
 
-Once you click on a heatmap node, the node expand and shows a stacked heatmap.
+{{% tab tabName="Expandable Nodes" %}}
 
-- **The upper histogram** shows the distribution of values from the source column.
+Clicking a heatmap node reveals a stacked histogram panel:
 
-- **The lower histogram** shows the distribution from the target column.
+- **Top Chart**: Source column value distribution
+- **Bottom Chart**: Target column value distribution
 
-These visuals help assess whether the values in the two columns are statistically or categorically aligned. For example, if both columns share similar categories with comparable frequency distributions, it suggests a strong match.
+Use this to evaluate whether the two columns share meaningful overlap.
 
-_**Interpretation Tip:** Matching distributions with similar peaks (e.g., a high frequency of "Male" and "Female" values) may indicate semantic alignment. Dissimilar distributions can signal a mismatch or a need for closer inspection._
+**Tip:** Similar distributions (e.g., shared categories like "Male" and "Female") often suggest semantic alignment.
 
 ![embedded-node](./images/embedded-node.png)
 
 {{% /tab %}}
-{{% tab tabName="Top Tabs (above heatmap)" %}}
 
-![upper-tab](./images/upper-tab.png)
-
-- **All:** Displays all potential matches.
+{{% tab tabName="Heatmap Top Tabs" %}}
 
-- **Accepted:** Shows only those that have been manually confirmed.
+![upper-tab](./images/upper-tab.png)
 
-- **Unmatched:** Lists only those source attributes with no confirmed match.
+The top-level filter tabs help narrow your focus:
 
-- **Expand On Hover:** _This toggle controls if the expandable node will be expanded on mouse hover or not(on click)._
+- **All**: View all candidate matches
+- **Accepted**: Only show confirmed matches
+- **Unmatched**: Only show source columns with no confirmed match
+- **Expand on Hover**: Toggle whether expanded histograms appear on hover or click
 
 {{% /tab %}}
+
 {{< /tabs >}}
 
-## Filters and Search Tools
+---
+
+## Filters and Search Controls
 
-BDIViz provides several ways to customize and narrow your view:
+Fine-tune the heatmap view using a suite of filters:
 
 {{< tabs tabTotal="4">}}
-{{% tab tabName="Source Attribute" %}}
 
-Lets you choose which column to focus on.
+{{% tab tabName="Source Attribute Selector" %}}
+
+Select a specific source column to examine.
 
 ![source-attribute](./images/source-attribute.png)
 
-Once click you will able to see this dropdown menu showing all the source attributes:
-- **All:** Shows all source attributes in a paginatable manner.
-- **Attributes in green:** The attributes that already have at least one accpeted candidate.
-- **Attributes in grey:** The attributes that is discarded by user.
+Dropdown key:
+
+- **Green**: Already matched
+- **Grey**: Manually discarded
+- **All**: Show all source attributes
 
 ![source-attribute-drop](./images/source-attribute-drop.png)
 
 {{% /tab %}}
+
 {{% tab tabName="Similarity Threshold" %}}
 
-Adjusts the minimum score a candidate must meet to appear. Values range from 0 (show all) to 1 (only highest similarity).
+Set a minimum similarity score for visible candidates. Range: `0.0 – 1.0`.
+
+- `0.0`: Show all matches
+- `1.0`: Show only perfect matches
 
 {{% /tab %}}
-{{% tab tabName="Similar Attributes" %}}
 
-Determines how many similar source columns appear in the y-axis for better comparative context.
+{{% tab tabName="Similar Attributes Displayed" %}}
 
-**Note:** This only apply when **Source Attribute** is not set to **All**.
+Controls how many similar source attributes appear on the heatmap when a single source column is selected.
 
+> Note: Only applies when Source Attribute ≠ "All".
 
 {{% /tab %}}
-{{% tab tabName="Search Bar" %}}
 
-Lets you highlight specific target attributes by name or keyword.
+{{% tab tabName="Search Bar" %}}
 
+Quickly locate and highlight target attributes by name or keyword.
 
 {{% /tab %}}
+
 {{< /tabs >}}
 
+---
 
-## Lower Panel Visuals
+## Lower Panel: Match Details
 
-When a node is selected from the heatmap, the bottom panels expand to provide deeper insights:
+Clicking on any heatmap node reveals deeper insights below:
 
 {{< tabs tabTotal="2">}}
+
 {{% tab tabName="Value Comparisons" %}}
 
 ![value-comparisons](./images/value-comparisons.png)
 
-Visual representation of fuzzy-matched value pairs between the selected source and target columns.
-
-Each row shows a unique source value and its closest string-matched counterpart(s) from the target.
+Visualizes string-based fuzzy matching between source and target values.
 
-Helps validate or question whether two attributes should be considered a match.
+- Each row: one source value + its closest matches
+- Use to validate whether mapping is semantically and syntactically justified
 
 {{% /tab %}}
+
 {{% tab tabName="UpSet Plot" %}}
 
 ![upset-plot](./images/upset-plot.png)
 
-the UpSet Plot provides a detailed breakdown of how each individual matcher contributed to the overall score of the selected candidate.
+Visualizes how different matchers contributed to the candidate match score.
 
-Each matcher is represented as a row, and each column represents a candidate match. A dot is shown where a matcher supports a given match.
+- Each row: a matcher
+- Each column: a candidate
+- Dots indicate support from that matcher
 
 {{% /tab %}}
+
 {{< /tabs >}}
 
+---
+
 ## LLM Agent Panel
 
 ![agent-panel](./images/agent-panel.png)
 
-- **Overview Diagnosis:** Summarizes whether the current match is likely valid or not, based on metadata, column names, and prior interactions.
+An embedded LLM-powered assistant provides contextual insights:
 
-- **Explanation Cards:**
+- **Diagnosis Summary**: Determines if a match is likely valid based on metadata, column names, and user history
+- **Explanation Cards**: Highlight key reasons (e.g., name similarity, value overlap)
+  - Click to expand for more detail
+  - Provide feedback via 👍/👎 to refine model accuracy
+- **Target Schema Metadata**: Enriched descriptions pulled from sources such as GDC
 
-  - Each card explains one rationale (e.g., shared terms, similar distributions, matching patterns).
+---
 
-  - Click to expand each explanation.
+## What’s Next?
 
-  - Feedback Buttons: Let you provide a **thumbs-up** or **thumbs-down** to help improve the model’s future reasoning.
+After reviewing the matches:
 
-- **Target Schema Descriptions:** Additional metadata from sources like GDC are displayed for further context.
+- Accept or reject individual match suggestions
+- Use filtering to prioritize high-confidence matches
+- Proceed to export, refine, or apply your matched schema for downstream harmonization tasks