Thanks for your work on margins. We use it quite a bit.

For my own edification, I was trying to understand how margins really works. Your documentation references Stata, which I've never used.

I started reading the Stata margins docs. Stata example 1 made complete sense to me (difference in preds for all data points setting sex first to "male", then to "female"), and I was able to recreate their (simple) calculations.

However, none of the examples I read seem to correspond closely to the first example in your margins docs (mtcars, cyl, wt, hp).

I think it would be useful to describe in the docs the types of mathematical quantities and calculations that go into calculating the margins to someone who doesn't know Stata, and doesn't have the Stata manual, but has a reasonable understanding of mathematics.

Ideally I'd get the intuition (e.g., "difference between predictions on the data set when setting the sex of all data points to 'male', and setting the sex of all data points to 'female'), along with an example that I could compute by hand to make sure I understood it.

Thanks for your consideration.