Make Jupyter Notebook Tutorials more understandable for programming Newcomers

[pkassing]

I worked through all the Jupyter Notebook tutorials and took notes on points that I, as a newcomer to programming found hard to understand: These are the points that I already worked into Part 1 of the Jupyer Notebook @Ludee, please have a look at it. My explanations might interfere with a fluid working through the notebook. these are the points that I explained in part 1:

• Explanation that the request package is handling http protocol communication
• Where are the tables stored? – link to “schemas” and “tables”
• Missing explanation of the data structure of tables
• Which operations do I need an authorization token for?
• Explanation that authorization token has to be included as a header in the request
• “insert data”, if you want to insert multiple lines of data, like the two power plants in this case, each row is a dictionary in a list?

I pushed the altered version to github.

I found that the following points still have to be explained: in part 1:

• "Query table columns" -is the returned json the specification of the column header “capacity”? this should be explained shortly
• “insert data into a specific row” – does this replace the original row, or is the originals row shifted one step downwards?
• Alter data in table? What does /rows/{id}'.format(id=row), stand for ?

in part 2:

• Filter: if something is searched for, the url has to include a “?” after rows/ ? This should be mentioned
• “limit” – missing explanation: the limit filter limits the number of results that you get if you search for rows or columns. In this case, as the filter is equal to two, only to rows are returned
• “more options” – more detailed explanation / some examples of usage of “where”- filter ?

in part 3:

• a bit more explanation of what is done in this part would be great, - what does vg stand for? Which relation do the data included in “boundaries” and “supply” have ?
• Short explanation of the modules ?

Btw, the "order by" filter is working now

[EdithaK]

Great

[klarareder]

Include also how to add a virtual envionment for first time users. - From SzenarienDB 2. project meeting

[klarareder]

In all parts it says:

This tutorial gives you an overview of the OpenEnergy Platform and how you can work with the REST-ful-HTTP API in Python. The full API documentaion can be found on ReadtheDocs.io.

What is the 'ReadtheDocs.io'? The documentation look different there. Which one am I supposed to use?

[klarareder]

We need to add a link to how to use the Jupyther Tutorials: https://github.com/OpenEnergyPlatform/oeplatform/wiki FYI: should this Wiki not be found at examples?

[klarareder]

I worked through the Tutorials and had the impression that one is supposed to work through all of them. As a first time user I just want to download or upload or similar. In that case it is very difficult to navigate.

1. How to we link the Tutorials - give them speaking names?

2. The order of the Turorials could be more intuitive. At the moment we have: Tutorial 1 - upload and modify table Tutorial 2 - select with conditions Tutorial 3 - generate dataframe and plot it Tutorial 4 - download to pandas df, csv, excel

I would suggest to change it into: Tutorial 1 - upload data Tutorial 2 - modify data Tutorial 3 - download to pandas df, csv, excel Tutorial 4 - select with conditions Tutorial 5 - plot data

[klarareder]

A major concern I have with the selection of tables with conditions is the syntax. It is not SQL or python. That way I have to learn a new syntax. I tried to modify it without reading all previous tutorials and that did not work. It would be much better to just send SQL statements.

[jh-RLI]

Working on solving this issue in #69 and #73.

[jh-RLI]

This ticket can be closed if the team agrees to the revised version.

[christian-rli]

I agree with the revised versions. @klarareder this repository is being restructured with new directories for upload and download. Additionally, a subpage for tutorials that is supposed to pick up first time users is under development on the oep. The ticket can be closed.

@jh-RLI : There should be a merge of develop into master however, which I'm going to carry out today. This hasn't been done in a while, so I hope I'm not running into any conflicts. In any case, let's try to stick to the driessen workflow afterwards.