beginners example using lmfit

[zoernchen]

Hi,
I learned about this package today and I found the examples to be commented on very sparsely.
I am relatively new to python and I think a lot of others are too, thus I wrote an example python document with A LOT of commenting that is (hopefully) beginner friendly. I don't know how to add it to the list of examples though, and I don't know whether it is appropriate to open a pull request for such a small thing.

Thanks for the help!

This is my code:
easy_lmfit_example.zip

[reneeotten]

hi @zoernchen - to be honest I think the amount of descriptive text in the examples is quite okay. But I can see that for beginners it might be difficult to follow here and there. Just to be clear though - the examples are not intended as a standalone introduction to the package; that's what the documentation is intended for. Additionally we assume that people are familiar (enough) with Python to be able to read/understand very basic expressions using NumPy / matplotlib. It is our hope that the examples are self-explanatory once someone spend the time going through the documentation.

So in all honesty I am not that interested in adding this example to gallery since in my opinion it doesn't add anything, but let's see what others think about it. If you feel that certain examples would benefit from a bit more explanatory text regarding the use of the lmfit package we would certainly welcome updates to those. However explaining things like plt.ylim or plt.legend() which are matplotlib functions is, at least to me, outside of the scope of our documentation.

[newville]

@zoernchen Yeah, thanks for this. I may not be the best one to write a guide for novices, but I'll make some suggestions anyway ;). I tend to agree with @reneeotten here: if you're looking into using lmfit, you might be a novice to Python, or you might be a Python expert. But it is doubtful that you haven't heard of numpy, scipy, matplotlib, etc.

I would definitely suggest starting a beginner's guide with curve-fitting with Model. That avoids "objective function" altogether and has the user start with a function that they write that simulates their data. I would start with something like a Gaussian peak - no ambiguities, everyone gets a peak with a centroid, height, and width.
You could start that way:

 1. read in data, plot it
 2. write a function that takes takes `x` and some parameters and calculates something like your data.
 3. run that function a few times with different values, plotting the results to see how those different values affect the result and how closely the result matches the data.
 4. map that function to a lmfit.Model, and generate parameters from it.  Repeat Step 3 with 'Model.eval()'.
 5. do a fit of that model to your data with 'Model.fit()'
 6. inspect the results (report and plot, probably using `ModelResult.plot` because it does not emphasize matplotlib stuff). 

With that, you show what the fit does, and then (part 2?), you can then go on to discuss uncertainties, goodness-of-fit statistics, starting values, trying other models, and other technical aspects of the fitting. Then you can go on the including data uncertainties, Composite Models, bounds, and mathematical constraints. And then, finally, you can go to objective functions that are not simply '(data-model)/uncertainty'.

In fact, the current docs do sort of have some of this. But: putting that in an annotated Jupyter notebook might be helpful.

I don't have a strong opinion on whether It would belong in the gallery - I'll defer to @reneeotten on that. Maybe a few Notebooks and some Youtube videos?