Added usage_guide.ipynb

[ayushanand18]

Overview

This PR aims to resolve #15 partly by

• adding the usage_guide.ipynb notebook containing examples for prospective pyobis users.

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]

Minor (really minor) correction :-)

Suggested change

	## We Develop with Github
	## We Develop with GitHub

[ayushanand18]

Thanks @ocefpaf for the review! I will update these corrections.

[ocefpaf]

Suggested change

	## We Use [Github Flow](https://guides.github.com/introduction/flow/index.html), So All Code Changes Happen Through Pull Requests
	## We Use [GitHub Flow](https://guides.github.com/introduction/flow/index.html), So All Code Changes Happen Through Pull Requests

[ocefpaf]

Suggested change

	1. Fork the repo and create your branch from `master`.
	1. Fork the repo and create your branch from `main`.

[ayushanand18]

Thanks @ocefpaf for the review! Actually, we have master as the HEAD upstream for this repo. Maybe this was older than when GitHub introduced the change of nomenclature. Should I do away with this change?

[ocefpaf]

Suggested change

	Pull requests are the best way to propose changes to the codebase (we use [Github Flow](https://guides.github.com/introduction/flow/index.html)). We actively welcome your pull requests:
	Pull requests are the best way to propose changes to the codebase (we use [GitHub Flow](https://guides.github.com/introduction/flow/index.html)). We actively welcome your pull requests:

[ocefpaf]

@dopplershift (pinging here just for credit), made some awesome docs on contributing, opening issues, PRs, etc, that could serve an inspiration here. See https://github.com/Unidata/MetPy

[ayushanand18]

Thanks @ocefpaf for the resource! I'll get some insights from there and update the document.

[ocefpaf]

@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]

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]

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]

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]

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.

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.

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]

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]

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]

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.

[ayushanand18]

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]

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]

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]

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]

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!