search

iobis / pyobis

OBIS Python client
https://iobis.github.io/pyobis
MIT License
15 stars 10 forks source link

Added usage_guide.ipynb #27

Closed ayushanand18 closed 2 years ago

ayushanand18 commented 2 years ago

Overview

This PR aims to resolve #15 partly by

Notes for Reviewers

This PR is two commits ahead of #26 (one change ahead).

Next Steps

I will now be working on creating Jupyter Notebooks for analyzing and visualizing data grabbed through occurrences.search()

ocefpaf commented 2 years ago

@ayushanand18 if you can split your PRs it will make reviewing them a bit easier.

Edit: Oh, I just saw #26 and it seems that you just pull those commits here.

ocefpaf commented 2 years ago

Regarding the notebook:

  1. We don't need the same results printed twice. A table is probably easier to visualize. Also, don't print pandas tables, let the HTML render do its magic. 
    res=nodes.activities(id="4bf79a01-65a9-4db6-b37b-18434f26ddfc")
print(res["results"])
print(pd.DataFrame(res["results"]))
  2. Try to filter out the results to make them easier to understand. Maybe create a map/graph with the data,
  3. Try to tell a story with the example, it can be either about the API or the data itself, but something that users will find useful and that they can modify for their use cases.
ayushanand18 commented 2 years ago

Edit: Oh, I just saw #26 and it seems that you just pull those commits here.

This PR is actually some commits ahead of #26, I thought of basing this branch on the previous so that there won't be merge conflicts in the future (I had been witnessing quite a few while creating this PR).

ocefpaf commented 2 years ago

I thought of basing this branch on the previous so that there won't be merge conflicts in the future (I had been witnessing quite a few while creating this PR).

The separation of context helps to avoid conflicts. If this PR only edits the notebook and the other one the markdown contributing file, we should be OK.

ayushanand18 commented 2 years ago
  1. We don't need the same results printed twice. A table is probably easier to visualize. Also, don't print pandas tables, let the HTML render do its magic.

I will update the notebook accordingly. Actually, for some results a pandas DataFrame doesn't speak much due to the huge volume of columns and few rows. I am thinking of keeping the raw response for some (cleaned up as a dictionary) and pandas DataFrame for some.

  1. Try to filter out the results to make them easier to understand. Maybe create a map/graph with the data,
  2. Try to tell a story with the example, it can be either about the API or the data itself, but something that users will find useful and that they can modify for their use cases.

I was thinking to keep this notebook only for explaining about the functions inside modules, and their input parameters. Analyzing data through each function might make this notebook bit heavy, so I thought of diving deep into each module in a separate notebook. How should I approach this?

ayushanand18 commented 2 years ago

The separation of context helps to avoid conflicts. If this PR only edits the notebook and the other one the markdown contributing file, we should be OK.

Noted. I'll make sure about this for future. Should I pull out the changes of the markdown contributing guide or update the changes here and close #26?

ocefpaf commented 2 years ago

Should I pull out the changes of the markdown contributing guide or update the changes here and close #26?

Wait for @7yl4r input. I'm in favor of the easiest path here.My comment was more for future PRs.

7yl4r commented 2 years ago

Uh oh. It looks like CONTRIBUTING.md got rolled in with this PR but #26 is specifically for that. We should either:

  1. close that PR and just use this one
  2. rm CONTRIBUTING.md from this PR and implement Felipe's changes over on #26.

Whichever way is easiest is fine. 🩹 We are going to have to practice this workflow a few times until we get it perfected.

ayushanand18 commented 2 years ago

Uh oh. It looks like CONTRIBUTING.md got rolled in with this PR but #26 is specifically for that. We should either:

  1. close that PR and just use this one
  2. rm CONTRIBUTING.md from this PR and implement Felipe's changes over on Contributing guidelines #26.

Whichever way is easiest is fine. 🩹 We are going to have to practice this workflow a few times until we get it perfected.

Thanks @7yl4r! I am going to remove CONTRIBUTING.md from this PR and inculcate changes suggested by you and @ocefpaf in #26. I'll make sure I don't mix up PRs in future.

7yl4r commented 2 years ago

This PR is actually some commits ahead of #26, I thought of basing this branch on the previous so that there won't be merge conflicts in the future (I had been witnessing quite a few while creating this PR).

I think the best approach here would have been to base a new fork off of the latest in the master. One critical piece that may be missing is using git rebase to keep forks up-to-date. As a general rule you should not merge-pull from master to a PR fork. I am not 100% sure, but I think this commit should have been a rebase instead of a merge.

ayushanand18 commented 2 years ago

I think the best approach here would have been to base a new fork off of the latest in the master. One critical piece that may be missing is using git rebase to keep forks up-to-date. As a general rule you should not merge-pull from master to a PR fork. I am not 100% sure, but I think this commit should have been a rebase instead of a merge.

Thanks a ton @7yl4r! I actually didn't have a sound practice with git rebase previously. I feared that it might result into lost commits and then merge conflicts. I'll surely use git pull --rebase for future pulls.

7yl4r commented 2 years ago

I feared that it might result into lost commits and then merge conflicts. I'll surely use git pull --rebase for future pulls.

It is something to be careful with, since rebasing does edit history. It makes me nervous too, but unfortunately it seems to be essential to the typical git PR workflow.

ayushanand18 commented 2 years ago

It is something to be careful with, since rebasing does edit history. It makes me nervous too, but unfortunately it seems to be essential to the typical git PR workflow.

I'm learning new things every day, and this journey hasn't been so good before. And I have so much more to learn. Thank you so much!