-
-
Notifications
You must be signed in to change notification settings - Fork 611
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
A new linear regression tutorial #2016
Conversation
Should we consider having a "getting started" on the website in addition to
the docs?
…On Wed, Jul 6, 2022, 01:53 Saransh ***@***.***> wrote:
This PR -
- Adds a new "Getting Started" section in the docs which I will be
working on for the next couple of weeks
- Moves basics.md and overview.md to the "Getting Started" section.
Currently, there are no changes in the files, but they will be changed soon.
- Adds a Linear Regression example to the "Getting Started" section
For the linear regression guide -
- Should I add the backpropagation step in the first half, or should I
leave it to the Flux.Optimise.update! step?
- This guide overlaps with a lot of other textual information present
but scattered in Flux's docs. These other texts will also be updated or
moved to a better place soon. Basics.md, for example, does something very
similar with dummy data, and the current "Getting Started" guide does
something similar but with pre-defined weights.
PR Checklist
- Tests are added
- Entry in NEWS.md
- Documentation, if applicable
------------------------------
You can view, comment on, or merge this pull request online at:
#2016
Commit Summary
- c52dc2c
<c52dc2c>
Create a getting started section and add a new linear regression example
File Changes
(9 files <https://github.com/FluxML/Flux.jl/pull/2016/files>)
- *M* docs/Project.toml
<https://github.com/FluxML/Flux.jl/pull/2016/files#diff-6e0adb5e01dce01db395f52201532ad8fec022922489f34827886053953ce93f>
(3)
- *M* docs/make.jl
<https://github.com/FluxML/Flux.jl/pull/2016/files#diff-4aae2d1c783cade58bd2cb13748da956e568b7f2aed5fafd9e2a46fb97daf613>
(11)
- *R* docs/src/getting_started/basics.md
<https://github.com/FluxML/Flux.jl/pull/2016/files#diff-4224422c0fa149eeb1d03330e17a6a2029d129db92bed998c99986f034dfc4fb>
(2)
- *A* docs/src/getting_started/linear_regression.md
<https://github.com/FluxML/Flux.jl/pull/2016/files#diff-fba702b6c13d725a8429905593e78fdf3d263cbde6f5c769af63ee1a20fd8424>
(496)
- *R* docs/src/getting_started/overview.md
<https://github.com/FluxML/Flux.jl/pull/2016/files#diff-f33b3f58a594c426aed1cddeaabc6569c071cdee3799b15fdf52a278142eeb66>
(0)
- *M* docs/src/gpu.md
<https://github.com/FluxML/Flux.jl/pull/2016/files#diff-813fc68aeb136c3af32fae13632adf27c24229ce9b56b151d13b836db8a7aa2d>
(2)
- *M* docs/src/models/advanced.md
<https://github.com/FluxML/Flux.jl/pull/2016/files#diff-01d4481e127f0cef79438231dbde6fca65d618f29070e0f2835ed6a7f8b13df7>
(2)
- *M* docs/src/training/optimisers.md
<https://github.com/FluxML/Flux.jl/pull/2016/files#diff-e9c792a4e565cbb6cd7f78a85ab25ad5bb66a6fc0f1e4d49ab39ac821dd69b4c>
(2)
- *M* docs/src/training/training.md
<https://github.com/FluxML/Flux.jl/pull/2016/files#diff-791e8b024a9ce7e7f89b45b7582d628d3d8d55f0bb5e17c39f8a50bd6aa21aea>
(6)
Patch Links:
- https://github.com/FluxML/Flux.jl/pull/2016.patch
- https://github.com/FluxML/Flux.jl/pull/2016.diff
—
Reply to this email directly, view it on GitHub
<#2016>, or unsubscribe
<https://github.com/notifications/unsubscribe-auth/AJOZVVPWCTKUTEJDXS5J7ILVSSKTHANCNFSM52XLUU3A>
.
You are receiving this because you are subscribed to this thread.Message
ID: ***@***.***>
|
The first thought I had was to add a hyperlink on the website's Should I also add the same tutorial (once approved) to the website, or should we link the section? |
I think there is a consensus to not use |
Thank you for the suggestion! I took some time to go through |
Agree we should move away from the whole weird But perhaps this linear regression example should delay introducing Optimisers.jl as long as possible. For simple gradient descent, just writing out something like this:
might be a better level than immediately introducing optimiser state etc. It's unfortunate that this has quite a few moving parts, unlike Even something like this seems OK to me, pretty explicit, and makes you understand why you are about to see a tool for walking over the arrays:
One more comment. In such tutorials, things like (Link to rendered version: https://github.com/Saransh-cpp/Flux.jl/blob/linear-regression/docs/src/getting_started/linear_regression.md ) |
Agreed, we should keep the linear regression example simple. I will update the tutorial to show the gradient descent algorithm in action. I have been working on the logistic regression example locally and will update that with the same. |
f3f6933
to
fdc67c0
Compare
d66b311
to
a8f4788
Compare
418a778
to
1884275
Compare
I'll update this with the new |
1884275
to
06cb07c
Compare
Test: @ModelZookeeper commands |
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.
I had some comments on an earlier version... perhaps useful but not a full review.
## Copy-pastable code | ||
### Dummy dataset | ||
```julia | ||
using Flux | ||
using Plots | ||
|
||
# data | ||
x = hcat(collect(Float32, -3:0.1:3)...) |
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.
It's nice to encourage people to try this out. I fear that nobody will find this section until they have done plenty of copying pieces above.
And that they will tend to drift out of sync. (Maybe this section should at least run as a smoke-test.)
Should we consider making these pages with Pluto, so that they are just a static version of something you can download and run?
f5cfd16
to
adb49b2
Compare
Thanks for the review, @mcabbott! Pluto sounds good! We can get rid of the copy-paste section if this is converted to a Pluto notebook (or file, not sure, will go through it in detail). ( Edit: A discussion about the documentation of |
@mcabbott, JuliaManifolds/Manopt.jl renders This does look a bit hacky, and it also distorts the documentation when a user opens one of the rendered SidebarNormal pageRendered Pluto notebookSettingsNormal pageRendered Pluto notebookIs there a legitimate way to render Here is how the converted Note: I am just redirecting users to the |
Currently, https://fluxml.ai/Flux.jl/stable/models/overview/ does something similar but is not as extensive as this guide. Should it be removed, or should it also be put under the "Getting Started" guide with a better title? |
What if anything do we lose if it's removed? I think it would be nice to do so, but any material in it which isn't covered elsewhere would need a new home. |
I think the following text can be used at the top of this guide. The rest of this page is definitely a subset of this guide. Flux is a pure Julia ML stack that allows you to build predictive models. Here are the steps for a typical Flux program:
Under the hood, Flux uses a technique called automatic differentiation to take gradients that help improve predictions. Flux is also fully written in Julia so you can easily replace any layer of Flux with your own code to improve your understanding or satisfy special requirements. Here's how you'd use Flux to build and train the most basic of models, step by step. |
da20b62
to
2c9cdd1
Compare
One virtue of that page is that it's much shorter. I like this PR's story, it's a nice ground-up explanation. But if you have met some of this before, and want a faster path to seeing how to write it in Julia's syntax and using Flux's pieces, then perhaps you prefer the older one. Not sure what the ideal way to organise this material is... |
Yes, this makes sense. Maybe converting it into a "Quickstart" page under the "Getting Started" section? |
In addition to the main manual https://fluxml.ai/Flux.jl/stable/models/overview/ we also have some quite nice tutorials here: https://fluxml.ai/tutorials.html How do we make these all findable, and where does this new page go? The main docs also seem a slightly awkward combination of introduction and reference. It's possible that the "Building models" heading should be split in two? Not sure. |
While drafting the "Getting Started" section, I wanted to include only the guides that will get a user started with flux. The website tutorials should be the ones introducing something that a user doesn't find themselves engaged with when they begin with ML/DL or an ML/DL package, for example, GANs and Transfer Learning. I think the Ideally, there should be a "Tutorials" heading on the docs' sidebar which should redirect users to the website's tutorials page. Similarly, the website's getting started page should redirect users to the docs' getting started section. A nice infographic - IMO, the |
Co-authored-by: Michael Abbott <32575566+mcabbott@users.noreply.github.com>
Co-authored-by: Michael Abbott <32575566+mcabbott@users.noreply.github.com>
Co-authored-by: Michael Abbott <32575566+mcabbott@users.noreply.github.com>
e1b88d1
to
0350e03
Compare
docs/make.jl
Outdated
"Gradients and Layers" => "models/basics.md", | ||
"Quick Start" => "getting_started/quickstart.md", | ||
"Fitting a Line" => "getting_started/overview.md", | ||
"Gradients and Layers" => "getting_started/basics.md", |
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.
Can I suggest leaving files where they are, until sure? I think moving them may break some links elsewhere. And we may re-organise this into Guide / Reference.
(Adding id
& linking by that, not heading name nor file name, seems like the right solution.)
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.
All the references associated with these pages now use id
s! I have also reverted back the structural changes.
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.
Let's do it. Tutorials is the right section, IMO.
This PR -
basics.md
andoverview.md
to the "Getting Started" section. Currently, there are no changes in the files, but they will be changed soon.For the linear regression guide -
Flux.Optimise.update!
step?PR Checklist