-
Notifications
You must be signed in to change notification settings - Fork 119
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.
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
rewrite the tutorials #302
rewrite the tutorials #302
Conversation
use actual Primary-Energy-values from MESSAGE-CD-LINKS scenarios
@znicholls, can you take please a look at the updated "checking_consistency" notebook? I created a smaller, more specific example to better highlight what is being checked and why each validation fails. I also replaced the term "database" with "scenario ensemble" to describe the content of an |
@byersiiasa, can you take a look whether the updated "first-steps" notebook satisfies the issues #290 and #298? (if you have a minute) |
Hi @danielhuppmann. Thanks for reworking these tutorials! I think you have done a great job of making this first steps tutorial accessible. Some quite minor points:
In general, when using pyam in practice for processing purposes, there can be a lot of converting between different forms. It would be good to make it as clear as possible when one has a wide or long format, and when it is a pyam.IamDataFrame and when it is a pandas.DataFrame. A new user would probably assume that everything that goes in as a pyam.IamDataFrame also returns one. Thus, every time that this not the case, it should be very clear (e.g. under 'displaying timeseries data' it is a bit too easy to miss right now). (this also holds for when a pandas.Series [e.g. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
lgtm, small suggestions:
- 'sum of wind and coal in that region' --> 'sum of wind and coal in region_a and region_b
- ' is Primary Energy should be equal to Primary Energy|Coal plus Primary Energy|Coal' --> 'is Primary Energy equal to Primary Energy|Coal plus Primary Energy|Coal'
- 'Note that the detailed output (i.e., where the aggregation validation fails) is not shown in a notebook when calling the function within a loop.', maybe add a pointer to a resource which explains how notebooks work for those who are confused by this
The one other thing you might want to add is an explainer of the handling of Bunkers. It's super confusing to everyone and having that in there might make it easier for people. Alternately it could be a separate tutorial just for 'advanced users' who have to deal with this stuff.
Hi @danielhuppmann , Great tutorial notebook, very illustrative and clear, even for not-very-experienced readers as myself. Minor comments:
I think a preposition is missing before categorization. Moreover, I think a clear reference to the meta table section should be included instead of the parenthesis, stating sth like: "the second latest cell in XX shows the meta table" (I found it confusing talking about a meta table whose format it was not clarified until the command
|
response to @znicholls:
Any good reference for this? Re "handling of bunkers" - this wasn't included in the tutorial before. I'll see if I have time to extend the tutorial when I tackle #299. |
Ah ok cool makes sense. |
Thank you @jkikstra and @francescolovat for these great suggestions! Highlights of my changes:
About the suggestion by @jkikstra to create an overview table of functions and their return types - I understand that this is confusing for new users, but I'm worried about adding new parts to the documentation, because this will be difficult to maintain and keep up to date... |
thanks - yes, nicely implemented! |
lgtm @danielhuppmann ! I tried restarting the mac CI that failed, not sure why it is failing or if this is a known issue. |
no idea why Appveyor is now failing with ever more confusing error messages - maybe it's because now running on merging to see if this resolves the issue |
Please confirm that this PR has done the following:
Adding to RELEASE_NOTES.md (remove section after adding to RELEASE_NOTES.md)
Please add a single line in the release notes similar to the following:
Description of PR
This PR reworks most of the tutorials, in particular the "first-steps" tutorial. It updates the tutorial data source to the IAMC 1.5°C data for consistency with the IIASA-db tutorial, and improves consistency of the formatting and notation.
closes #298
closes #290