cmd: pending plots changes by 1.0 release

[jorgeorpinel]

Extracted from #1382 (comment) et al.

• Apply changes from metrics & plots: help output improvements dvc#3963 once that is merged. - cmd: pending plots changes by 1.0 release #1414 (comment)
• Add YAML and TSV examples to plot show? Or maybe just translate JSON example to YAML and CSV to TSV.
• Per Regular updates & plots 1.0 update #1382 (review) double check about "All plots are used" in plot show -h usage (targets arg). - cmd: pending plots changes by 1.0 release #1414 (comment)
• modify: how to make a regular output into a plot? See Refactor plots dvc#3994 (review) - cmd: example on modifying any outputs into a plots #1946
• Review term "props" in plots commands once the code base is final/stable (per Regular updates & plots 1.0 update #1382 (review))
• term: "column index" vs "column number"? See Regular updates & plots 1.0 update #1382 (comment) and Regular updates & plots 1.0 update #1382 (review) - cmd: example on modifying any outputs into a plots #1946
• For JSON plot files we say "every object should have the same structure" but actually I'm not sure what the exact restriction is. Ask/test/check. See Regular updates & plots 1.0 update #1382 (review)
• Double check how to apply all Vega spec props in plots: modify subcmd only has a limited no. of options. Why isn't it like dvc config BTW, where you can give any key/value pair (core repo Q)? Moved to plots: allow to modify any (Vega) prop dvc#4909

---

• EXTRA: Possibly change the modify example explained in Regular updates & plots 1.0 update #1382 (comment)
• EXTRA: Maybe address some of the discrepancies mentioned in this docs: rename dvc lock -> dvc freeze #1380 (comment)
• EXTRA: Is plots diff really a diff? See discussion in Regular updates & plots 1.0 update #1382 (review)
• EXTRA: See plots: update docs #1800

[jorgeorpinel]

@imhardikj some answers to #1946 (comment):

Apply changes from treeverse/dvc/pull/3963

These changes are already applied

No, they're not. Several cmd ref Synopsis/usage sections and maybe some option descriptions still need the updates, I think (please double check).

maybe just translate JSON example to YAML and CSV to TSV

But this will result in same plot

Just add an expandable section under the sample data of https://dvc.org/doc/command-reference/plots/show#example-hierarchical-data to show how it looks in other formats.
Changing the extensions in some other unrelated sections doesn't sound like a useful alternative BTW.

Per #1382 (review)

I checked this with examples which has 2 and 3 plot files, plots show generated image with 2 and 3 plots respectively.

Sounds good. Can you share the example dvc.yaml file with 2-3 plots though? And DVC version, command, and result. Thanks
UPDATE: Evidence in #1414 (comment)

[jorgeorpinel]

@imhardikj remaining answers to #1946 (comment):

For JSON plot files we say "every object should have the same structure" but actually I'm not sure... Ask/test/check

doesn't hold true...

OK that's great investigation from your part, with the plots example and everything. So we need to update the plots ref(s) to explain what the behavior and restrictions (if any) are. 1. Update the description of <DVC_METRIC_Y> to specify only the first row matters; 2. Update the text in the plots index to something like "array of consistent objects is expected: " (also not sure "expected" is the right term, feel free to rewrite the whole paragraph if needed).

• Please do that update in it's own PR. - cmd: Updating description of <DVC_METRIC_Y> in plots #1961

Double check how to apply all Vega spec props...

I passed properties like this... dvc plots modify logs.csv --width 1000

Why did you expect arbitrary -- flags to have an effect? The valid options for the command are listed in https://dvc.org/doc/command-reference/plots/modify#options and no others will work (did it give you an error message, BTW?).

Details

Some of the options (from x to title correspond to Vega properties). You can learn more about Vega and how it relates to DVC plots here: https://dvc.org/doc/command-reference/plots/show#example-vega-specification-file. The question was whether it's possible to modify any Vega props besides the options that the modify command provides (as options). I guess probably only via a custom template (see https://dvc.org/doc/command-reference/plots#plot-templates).

This topic is a bit advanced so feel free to give it a shot to understand and if you can come up with a new section or example somewhere on how to modify any Vega property that would be great but don't worry too much about it. It's not key info we need to provide (I'm removing the check box for now). Thanks

[imhardikj]

Can you share the example dvc.yaml file with 2-3 plots though

@jorgeorpinel I used dvc.yaml from example-get-staretd. I modified plots in evaluate stage like this:

- prc.json:
        ...
- prc1.json:
        ...
- prc2.json:
        ...

Edited similarly in evaluate.py to generate these files.. I changed x and y fields so plots are different
Command:

$ dvc plots show

Result:

DVC version:

$ dvc version
DVC version: 1.10.0 (pip)
---------------------------------
Platform: Python 3.6.9 on Linux-4.19.112+-x86_64-with-Ubuntu-18.04-bionic
Supports: All remotes
Cache types: hardlink, symlink
Cache directory: overlay on overlay
Workspace directory: overlay on overlay
Repo: dvc, git

[imhardikj]

Several cmd ref Synopsis/usage sections and maybe some option descriptions still need the updates.

@jorgeorpinel I checked all changes in treeverse/dvc/pull/3963 and those are already there in metrics and plot docs. I think all are covered by #1382 and #1444. One thing migth plots diff description as per treeverse/dvc#3963 (review)
According to review I think "Show multiple versions of plot metrics by overlaying them in a single plot." should be changed to "Show multiple versions of plot metrics by overlaying them in a single image."