fill in metrics.md file

[amsnyder]

I think this metrics.mdwas meant to be a placeholder for extra statistics that aren't part of the StdSuite of DScore. Is that correct? If so, it needs to be populated.

I think we should also somewhat follow the naming scheme of the other files and rename to something like Metrics_Supplementary.ipynb or something along those lines. Open to suggestions here - I think we discussed its name, but I don't remember the conclusion.

[sfoks]

Was this meant to be an overview explanation of the statistical suites as a .md file & where to find further details in the ipynbs? I can't remember.

from the structure of the _toc.yml it looks like overview material. I can generate some of this.

• caption: Model Evaluation Tutorials chapters:
  • file: evaluation/metrics sections:
    • file: evaluation/Metrics_DScore_Suite_v1
    • file: evaluation/tutorials/stats/Usage_DScore_Suite_v1
    • file: evaluation/Metrics_StdSuite_v1
    • file: evaluation/tutorials/stats/Usage_StdSuite_v1

[gzt5142]

I think this metrics.md

@amsnyder -- this is another case of some sort of file being needed as a 'container' for the sub-sections included as children in the TOC of the jupyterbook. We should definitely put text in that document, so we won't accidentally remove it, as we did with clusters.md.

Whatever gets written in there, include this as the final couple of lines:

```{tableofcontents}
```

That will instruct the book compiler to include a mini-table-of-contents for the "children" of metrics.md as clickable links.

[alaws-USGS]

@amsnyder I'm currently creating the Metrics_Supplementary.ipynb as part of my work on the analysis notebook. This is separate from the metrics.md.

[amsnyder]

What will the metrics.md be filled in with? Or is it something we should delete?

[gzt5142]

What will the metrics.md be filled in with? Or is it something we should delete?

Cannot delete.

See here and here

These near-empty files are used as 'containers' for sub-sections or sections in the jupyterbook. They are placeholders. For best effect, they should contain text to describe what they contain. I put them in as empty for the prototype/demo, which is why they look delete-able. If we want all of those metrics notebooks as sub-sections, then we need this file (or something like it) as the parent in the TOC.

[amsnyder]

Sorry @gzt5142 - I totally missed your first comment in this thread. Is there any reason we can't use the README.md in each directory to provide that content instead of creating an additional document? How will the content differ between the two files?

[gzt5142]

Sorry @gzt5142 - I totally missed your first comment in this thread. Is there any reason we can't use the README.md in each directory to provide that content instead of creating an additional document? How will the content differ between the two files?

I suppose that depends on the target structure/outline... Do you want the outline depth to stop at the evaluation chapter, or do you want sections and sub/sections (depth=2 or more).

That is... This:

• evaluation
  • Dscore definition
  • StdSuite definition
  • Dscore usage
  • Std Suite Usage
  • Streamflow Overview
  • ...
  • Conus eval

or this:

• evaluation
  • metrics
    • dscore definition
    • dscore usage
    • stdsuite definition
    • stdsuite usage
  • Streamflow Overview
  • ...
  • conus eval

The 'top' level ("evaluation" in this case) will appear as a chapter -- with a toggle to expand its sections. With the flatter definition (first option, above), all components will show at once -- all are direct children of 'evaluation'. With the hierarchical definition (second option, above), 'metrics' becomes a sub-section title, with a toggle to show the children (or not).

Both work fine. I built it as I did because I think that hierarchy occupies less of the TOC panel and lets the user drill down to what they want. If we think that flatter is better, then we need to adjust the TOC to reflect that.

Discussion of the TOC philosophy (flat vs hierarchy) should probably be taken up in #266 , since it affects the whole repo.

[amsnyder]

Got it - that makes sense @gzt5142 and I like the hierarchical structure. It is probably helpful to link to the child markdown files from the top level directory readme, so let's make sure we do that when this gets populated.

If there are more markdown files that you need added/populated, let's create an issue for each one so that we can task people to create the content.