Organize

[shrit]

The aim of this PR is to make this repo usable.

The current state of this repo is a bit of a mess, this is the first attempt to organize examples based on the language and based on the ml method that is used.

[github-actions]

👈 Launch a binder notebook on branch shrit/examples/organize

[review-notebook-app]

Check out this pull request on 

See visual diffs & provide feedback on Jupyter Notebooks.

---

Powered by ReviewNB

[rcurtin]

This is really nice! Thank you for doing this. It was definitely easier to just look at the new branch to see the organization. I actually haven't looked at the diff yet, I think there are some code changes here and there that I'll check, but first, a handful of suggestions:

• c++/ -> cpp/ (I see that naming convention used more often)
• cli_bindings/ -> cli/ (just to match the rest)
• Reinforcement learning examples into jupyter/?
• Another name for jupyter/ might be notebooks/, but that's just a suggestion, I don't think I have an opinion either way.
• In the README, it would be great to change the description of what the directories are from a paragraph to bullet points (people's eyes will probably be drawn to them more).
• A couple of the examples, like rain-classification, use multiple techniques... to match the other examples which are organized by technique, does it make sense to make something like a multi-technique/ directory? In fact, does using the directory structure to name the technique make the most sense anyway? I wonder if it might be better to use a README.md in each top-level directory (cpp/, cli/, etc.) that lists the examples and the techniques they use. Then you could list each of the techniques used in the rain-classification notebook or similar.

I think the Linux shell script is wrong here: https://github.com/shrit/examples/blob/organize/.ci/linux-steps.yaml#L99 --- it only changes up one directory (which used to be correct) but now it could be more than one, and has to go back to the root directory of the repository.

Let me know what you think of the suggestions; don't feel obligated to take them all 😄

[shrit]

I agree with these suggestions, initially, I had it as jupyter_notebook but I can bring this back with no problem.
I can put the reinforcement learning in the notebook folder. However. there were some ensmallen examples that I need to figure out a place for them.

* `c++/` -> `cpp/` (I see that naming convention used more often)

* `cli_bindings/` -> `cli/` (just to match the rest)

* Reinforcement learning examples into `jupyter/`?

* Another name for `jupyter/` might be `notebooks/`, but that's just a suggestion, I don't think I have an opinion either way.

Will do this for sure.

* In the README, it would be great to change the description of what the directories are from a paragraph to bullet points (people's eyes will probably be drawn to them more).

I thought about this a lot, for the rain classification and examples that contain multiple techniques I did not find the best solution yet. However, I am 100% convinced that we need to separate them per method since most of our users will be looking for an example regarding a specific method. Also, most of our examples are named after datasets which itself does not make sense. Therefore, I really think that we need to class them per method.
This is going to be more interesting when it comes to embedded because we can show that some methods use fewer resources than others, or show examples of specific methods that can perform faster on low-resource devices.

* A couple of the examples, like `rain-classification`, use multiple techniques... to match the other examples which are organized by technique, does it make sense to make something like a `multi-technique/` directory?  In fact, does using the directory structure to name the technique make the most sense anyway?  I wonder if it might be better to use a `README.md` in each top-level directory (`cpp/`, `cli/`, etc.) that lists the examples and the techniques they use.  Then you could list each of the techniques used in the `rain-classification` notebook or similar.

Thanks for pointing this out, I started fixing it and I need to continue

I think the Linux shell script is wrong here: https://github.com/shrit/examples/blob/organize/.ci/linux-steps.yaml#L99 --- it only changes up one directory (which used to be correct) but now it could be more than one, and has to go back to the root directory of the repository.

[rcurtin]

I thought about this a lot, for the rain classification and examples that contain multiple techniques I did not find the best solution yet. However, I am 100% convinced that we need to separate them per method since most of our users will be looking for an example regarding a specific method. Also, most of our examples are named after datasets which itself does not make sense. Therefore, I really think that we need to class them per method.
This is going to be more interesting when it comes to embedded because we can show that some methods use fewer resources than others, or show examples of specific methods that can perform faster on low-resource devices.

Yeah, I agree with how the users will approach the examples. And it is probably true that many users will just poke into the directory structure to see what they are interested in. The question is just what to do with the multi-method examples. The best I can think of---and maybe you can think of something better---is just a multi-technique/ directory or something like this, and then an associated README that has quick descriptions of the examples and links between them. So e.g. you can put the "rain classification" example in the 'random forest' and 'logistic regression' sections in the README.

The perfect is the enemy of the good, so I agree it would be good to merge this even if we don't work out all the CI issues right now, and then come back for incremental improvements later.

[mlpack-bot]

Second approval provided automatically after 24 hours. 👍