First Pass Notes on Cookbook

[jukent]

Hi @jnmorley here are some first pass notes from your Cookbook. Great work putting this together. Let's polish it into something you can be really proud of.

First your nightly build badge and contributor's images are broken. Is part of this because you aren't in the Cookbook organization?

The link to take you to the source repository still directs you to the cookbooks-template repository instead (which made finding this repo a little harder than necessary).

"Intro to Cartopy" link is broken.

It's good that you linked to the Mesowest’s HRRR data page. I think it would be worth adding a line or two (both in the intake notebook and in the structure where you first mention Mesowest) about this data: Is it satellite, station, or model? If it's a station where is it located? If it's a model what is it's specialty or team like? Is it crowd-sourced data? Something along those lines.

You're opening data from a catalog.yaml file that is hidden in the Cookbook view. It would be nice to have either a page that just displays the yaml in the Cookbook or a link to the raw GitHub link so that readers can scroll through this and see the structure of the file. Some readers may be new to YAML so a line on what it is could be useful here too.

The hrrrzarr descrition says, "See readme source for more information." Can you demonstrate opening the README after that?

"Unfortunately, the data is not quite ready to use after reading it in with intake." All that is obvious to me is that the coordinates are currently projections on x and y. What and why needs to be changed? Are you going to change the names to follow standards or is there some analysis that needs to be done? (And the time piece, which you covered). And why is metpy used for this? Can Xarray not assign the coordinates on its own?

"Intro to Intake" link not there in second notebook.

Great work @jnmorley I hope these points are useful and not too nitpicky. Let me know if you'd like more or less feedback at once going forward.

[jnmorley]

@jukent Thanks for looking through the cookbook.

First your nightly build badge and contributor's images are broken. Is part of this because you aren't in the Cookbook organization?

Yes, that is the reason they are broken. I wanted to get some feedback on the cookbook before I moved it into the organization.

It's good that you linked to the [Mesowest’s HRRR data](https://mesowest.utah.edu/html/hrrr/) page. I think it would be worth adding a line or two (both in the intake notebook and in the structure where you first mention Mesowest) about this data: Is it satellite, station, or model? If it's a station where is it located? If it's a model what is it's specialty or team like? Is it crowd-sourced data? Something along those lines.

I think this is a great idea. It might be good to link to Kevin Tyle's "HRRR on AWS Cookbook" as well. We use the same data, and it provides a good example of using the data without Intake.

Intro to Cartopy" link is broken.

"Intro to Intake" link not there in second notebook.

Thanks for pointing these out.

You're opening data from a catalog.yaml file that is hidden in the Cookbook view. It would be nice to have either a page that just displays the yaml in the Cookbook or a link to the raw GitHub link so that readers can scroll through this and see the structure of the file. Some readers may be new to YAML so a line on what it is could be useful here too.

The hrrrzarr descrition says, "See readme source for more information." Can you demonstrate opening the README after that?

I like the idea of linking to the catalog on Github. I think it will help keep the cookbook a little cleaner than displaying the file on the page. However, I am trying to think of ways of displaying large objects like a yaml or readme file without breaking the flow of the document. This is the reason I am not yet using Intake to read the readme in the Intro notebook. The readme is more troublesome because it blends into the rest of the notebook. I am thinking about adding pre and post arguments to the intake markdown driver so the user can specify dividers for markdown sources.

source = intake.open_markdown(url, pre="-----", post="-----")

"Unfortunately, the data is not quite ready to use after reading it in with intake." All that is obvious to me is that the coordinates are currently projections on x and y. What and why needs to be changed? Are you going to change the names to follow standards or is there some analysis that needs to be done? (And the time piece, which you covered). And why is metpy used for this? Can Xarray not assign the coordinates on its own?

Thanks for bringing this up. This is a remnant of the tutorial I based the example off of that I don't completely understand. I will look at it some more and see what I can come up with.

I hope these points are useful and not too nitpicky. Let me know if you'd like more or less feedback at once going forward.

I don't think this feedback is too nitpicky. The more feedback the better.

I will start working on a PR to address this issue.

[jukent]

Great ideas James. I think linking between Cookbooks is a great way to promote all Pythia material.

What do you mean by "The readme is more troublesome because it blends into the rest of the notebook." It's just too long? You could still have text saying you'd call it by just changing the key name and that it is very verbose.

[jnmorley]

When I use intake to access a markdown file such as a readme, it displays in the notebook just like a markdown cell would. If there is a markdown cell right after the displayed readme it is hard to tell where the readme ends and the rest of the tutorial picks back up.

[jukent]

Even if you type cat.readme ? I didn't know that. We could maybe change the fontsize or add a line after if you're interested.

[jnmorley]

If you type cat.readme it will return information about the readme source in the catalog.

readme:
  args:
    urlpath: /home/jmorley/Documents/intake-cookbook/notebooks//README.md
  description: Learn more about how to use this catalog
  driver: intake_markdown.intake_markdown.MarkdownSource
  metadata:
    catalog_dir: /home/jmorley/Documents/intake-cookbook/notebooks/

if you type cat.readme.read() it displays the whole markdown file.

I think that adding a line after the displayed readme is a great idea.

[jukent]

Ahh thanks for explaining that

[brian-rose]

These look like good discussions from a previous "work in progress". @jnmorley @jukent are there any action items left here, or can we close this issue?

[jukent]

I haven't heard from @jnmorley or if he has any plans to continue this work. I think we close the issue.