Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

plots: copy edit walkthrough and dashboard tooltips #1922

Merged
merged 13 commits into from
Jun 23, 2022
Merged

plots: copy edit walkthrough and dashboard tooltips #1922

Show file tree
Hide file tree
Changes from 4 commits
Commits
Show all changes
13 commits
Select commit Hold shift + click to select a range
49eec05
walks: link to Vega-lite docs from Plots and
jorgeorpinel Jun 17, 2022
2b6b8f1
plots: better tooltips from Dashboard
jorgeorpinel Jun 17, 2022
64b624d
walks: copy edit Plots
jorgeorpinel Jun 17, 2022
4b641c8
Merge branch 'main' into editors/plots-dashboard
jorgeorpinel Jun 20, 2022
51e4f48
Update extension/resources/walkthrough/plots.md
jorgeorpinel Jun 20, 2022
abc0ff8
Update webview/src/plots/components/PlotsContainer.tsx
shcheklein Jun 20, 2022
c6bed38
Update extension/resources/walkthrough/plots.md
shcheklein Jun 20, 2022
562bae5
walks: shorten Plots
jorgeorpinel Jun 20, 2022
5f4d273
Merge branch 'editors/plots-dashboard' of github.com:iterative/vscode…
jorgeorpinel Jun 20, 2022
a9bb31b
plots: graph -> plot/visualize
jorgeorpinel Jun 20, 2022
2151326
walks: Plots +Dashboard
jorgeorpinel Jun 20, 2022
376b3d0
move code
jorgeorpinel Jun 20, 2022
76a5b79
Update extension/resources/walkthrough/plots.md
jorgeorpinel Jun 20, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
69 changes: 45 additions & 24 deletions extension/resources/walkthrough/plots.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,61 +1,82 @@
# Plots

Select one or more experiments to visualize them in the
[`Plots Dashboard`](command:dvc.showPlots). This is the extension's equivalent
of the `dvc plots show` and `dvc plots diff` commands.
Select one or more experiments to visualize in the
[**Plots Dashboard**](command:dvc.showPlots).

💡 If you don't have any DVC
[plots](https://dvc.org/doc/command-reference/plots) in the project, start
writing data points into JSON, YAML, CSV or TSV or saving plots as images
(`.png`, etc) (check the [DVCLive](https://dvc.org/doc/dvclive) helper library
if you use Python):
> This is the similar to the [`dvc plots show`] and [`dvc plots diff`] commands.
jorgeorpinel marked this conversation as resolved.
Show resolved Hide resolved

[`dvc plots show`]: https://dvc.org/doc/command-reference/plots/show
[`dvc plots diff`]: https://dvc.org/doc/command-reference/plots/diff

💡 To add [DVC plots] to the project, start writing data series into JSON, YAML,
CSV, or TSV files; or save your own plot images (`.png`, etc.).

<p align="center">
<img src="images/plots-dump-with-open-file.png"
alt="Code to Dump a JSON Plot File" />
<img src="images/plots-dump-with-dvclive.png"
alt="Code to Dump a JSON Plot File with DVCLive" />
<img src="images/plots-dump-image.png"
alt="Code to Dump an Image Plot File" />
</p>

Use `DVC: Show Plots` from the
[Command Palette](command:workbench.action.quickOpen?%22>DVC:%20Show%20Plots%22)
to open up the plots dashboard. The extension will display the following
sections for selected experiments, that correspond to the different
[types of plots](https://dvc.org/doc/command-reference/plots#supported-file-formats)
supported by DVC:
If you're using Python, the [DVCLive] helper library can save plots data for
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You are adding too much context to the page, too much structure. It tried as much as I can to keep it in a way that at least on my 13'' screen I can see some actual plots screenshots when open it

This comment was marked as resolved.

Sign in to view

Copy link
Contributor Author

@jorgeorpinel jorgeorpinel Jun 20, 2022 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

too much structure

Are you referring to the H2s further down? Also not a strong opinion, I guess it's a stylistic choice. IMO it looks better and clearer (# Plots > ## Plot types) and again it doesn't make the page longer. But I'm happy to flatten it if you confirm that's what we're talking about.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's not about the page length per se. It's about when I can see any plots on the page that is called "Plots". We want the screenshot with them visible asap. Adding more paragraphs, structure, etc are making it more and more like a tutorial. We should be throwing out things if possible, not adding them. It's similar to DVC's get started - we are fighting for every symbol here.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We should be throwing out things if possible... we are fighting for every symbol

OK, I compressed it again, in fact I merged a few things to make it even shorter. PTAL

It's about when I can see any plots on the page that is called "Plots"

Maybe we should move the 💡 tip about setting up plots to the bottom then? Or just link to DVC docs

you!

<p align="center">
<img src="images/plots-dump-with-dvclive.png"
alt="Code to Dump a JSON Plot File with DVCLive" />
</p>

[dvc plots]: https://dvc.org/doc/start/experiments/visualization
[dvclive]: https://dvc.org/doc/dvclive

Use
[`DVC: Show Plots`](command:workbench.action.quickOpen?%22>DVC:%20Show%20Plots%22)
from the command palette to open the **Plots Dashboard**. It displays the
following types of plots (for the selected experiments).

## Data Series

<p align="center">
<img src="images/plots-data-series.png"
alt="Plots: Data Series" />
</p>

`Data Series`. JSON, YAML, CSV or TSV files visualized using the predefined
(e.g. confusion matrix, linear) or custom (Vega-lite) templates.
JSON, YAML, CSV, or TSV files graphed using [plot templates], which may be
jorgeorpinel marked this conversation as resolved.
Show resolved Hide resolved
predefined (e.g. confusion matrix, linear) or custom ([Vega-lite] files)

[plot templates]:
https://dvc.org/doc/command-reference/plots#plot-templates-data-series-only
[vega-lite]: https://vega.github.io/vega-lite/

<p align="center">
<img src="images/plots-images.png"
alt="Plots: Images" />
</p>

`Images`. Any image file (e,g `.png`) can be visualized as a plot. They will be
rendered side by side in the table.
## Images

<p align="center">
<img src="images/plots-trends.png"
alt="Plots: Trends" />
</p>

`Trends`. Linear plots based on data from the experiments table if you use
[checkpoints](https://dvc.org/doc/user-guide/experiment-management/checkpoints).
Any image file (e.g. `.jpg` or `.svg`) can be visualized here. They will be
rendered side by side for the selected experiments.

The plots dashboard can be configured and accessed using using the `Plots` and
`Experiments` views:
## Trends

<p float="left">
<img src="images/plots-plots-view-icon.png"
alt="Plots View" width="49%" />
<img src="images/plots-experiments-view-icon.png"
alt="Experiments View" width="49%" />
</p>

Real-time graphs based on scalar [metrics] from the **Experiments Table**;
available when you use [checkpoints]
shcheklein marked this conversation as resolved.
Show resolved Hide resolved

The **Plots Dashboard** can be configured and accessed from the _Plots_ and
_Experiments_ side panels in the **DVC view**.
jorgeorpinel marked this conversation as resolved.
Show resolved Hide resolved

[metrics]: https://dvc.org/doc/command-reference/metrics
[checkpoints]: https://dvc.org/doc/user-guide/experiment-management/checkpoints
9 changes: 6 additions & 3 deletions webview/src/plots/components/PlotsContainer.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,12 +31,15 @@ export type BasicContainerProps = Pick<
>

export const SectionDescription = {
// "Trends"
[Section.CHECKPOINT_PLOTS]:
'Linear plots based on data from the experiments table.',
'Real-time graphs based on metrics from the Experiments Table',
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's create a ticket please to being able to include links into these descriptions.

  • keep all three sections visible, if section is empty, show the same message instead of it's content

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ticket created: #1933

Copy link
Contributor Author

@jorgeorpinel jorgeorpinel Jun 20, 2022 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do you also think "graphs" is also not good here? I like it better here since trends charts are not regular DVC plots but rather an extension-specific feature I think. Or does DVCLive also update regular plots in your browser? Anyway, feel free to also commit this if you prefer so:

Suggested change
'Real-time graphs based on metrics from the Experiments Table',
'Real-time plots based on metrics from the Experiments Table',

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

yes. Also not sure about making it the "Experiments Table" tbh.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It was already "Experiments Table". That's the official name we give to that custom VS Code Editor I think?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

sorry, I meant capitalization - should it be "Experiments Table" or just "experiments table" in these descriptions?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I like capitalization and bolding since each one has a walkthrough page. No strong opinion

BTW this page should be Plots Dashboard, I think (bit stronger opinion there).

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

okay, let's keep it

// "Images"
[Section.COMPARISON_TABLE]:
'A table used to display image plots side by side.',
'Displays image plots side by side across experiments.',
// "Data Series"
[Section.TEMPLATE_PLOTS]:
'JSON, YAML, CSV or TSV files visualized using Vega pre-defined or custom Vega-Lite templates.'
'Graphs of JSON, YAML, CSV, or TSV plot files, visualized using `dvc plots` templates'
shcheklein marked this conversation as resolved.
Show resolved Hide resolved
}
jorgeorpinel marked this conversation as resolved.
Show resolved Hide resolved

const InfoIcon = () => (
Expand Down