Adding a curve on DensityPlot: Epilog -> First[ContourPlot[...]] why the first?

I would like to understand why I have to add First around ContourPlot in the following example to have it working:

DensityPlot[LogTQ+LogA,{LogTQ,0,4},{LogA,0,4},PlotLegends->BarLegend[Automatic],ColorFunction->"SunsetColors",Epilog->First[ContourPlot[LogA==(LogTQ)^2,{LogTQ,0,4},{LogA,0,4}]]]


I looked at the documentation of ContourPlot which says: "ContourPlot returns Graphics[GraphicsComplex[data]]"

So I guess it means that as Epilog needs to take an object of the same type as First[ContourPlot] to work.

But I find it hard to understand it from the documentation.

My questions:

• In order to be more efficient with looking info on the documentation I would like some help to see where it is written. Indeed the only usefull info I found was that ContourPlot returns a Graphics. But where is it explained that Epilog should eat the first element of a Graphics. Furthermore what type is the first element of Graphics ?

• Also, for instance on the Epilog documentation is written:

"is an option for graphics functions that gives a list of graphics primitives to be rendered after the main part of the graphics is rendered" This explain what Epilog returns, but not what it "eats". Does that actually means that Epilog must "eat" list of graphic primitives ?

• There is in fact a documentation example of this needing First in an Epilog here wolfram.com/xid/0y8dpu-ek0xn . Epilog needs the primitives, not the Graphics. Oct 2 '20 at 13:24
• @flinty Yes but imagine that you are trying to learn and stackexchange doesn't exist. How can you guess you have to do apply First. I mean it is a total guess in the fog. This link is in a sub section of the examples of Epilog. It is very hard to find. Oct 2 '20 at 13:25
• My comment doesn't refer to stackexchange. That link points to an exact usage in the documentation. The documentation does a good job of spoon-feeding the answers with tutorials, neat-usages, applications etc. but admittedly it's missing some details. For that stuff I would investigate using Mathematica itself, as it gives you all the reflective tools (Head, Part, etc.) to inspect expressions. Oct 2 '20 at 13:33

1 Answer

If you look at the documentation for Graphics, you'll note that there is a list of all allowed primitives given, and that those primitives go into the first argument of Graphics (the rest is options). So if you have a graphics expression, the first element is a list of primitives, which is what Epilog wants. The only question now is what ContourPlot returns, and as you noted, ContourPlot is documented to return a graphics expression (which is technically not always the case when legends are added).

Combined this means: Epilog needs a list of graphics primitives, which are always in the first argument of a Graphics expression, and ContourPlot (as almost all plotting function) returns such an expression.

• Thank you for your answer. I still have an issue (which probably deserves a new question I don't know). By reading Graphics documentation the way I would understand "primitives" is the first parameter to give to Graphics which I understand as a function. Not as the first element (in the sense [[1]]) of a "Graphics" list. Why do you interpret primitives in this page as the first element of Graphics and not as an input parameters it must take ? I am super confused by reading the documentation. Thanks ! Oct 1 '20 at 17:19
• In a way maybe I interpret Graphics as a function and not as something different conceptually (an object ?!). If it shouldn't be understood as a function I would like to see where it is explained (I don't see any conceptual difference between the doc of Graphics and ContourPlot for instance, if the latter should indeed be understood as a function and the first as something different "an object ?!"). Oct 1 '20 at 17:23
• Graphics is an inert wrapper (as indicated by the wording "represents a two-dimensional graphical image") - that means that Graphics isn't a function that evaluates to something else, it just stays like it is, and the frontend knows how to display them. If you look at the first example in "Properties & Relations" (the one with InputForm), you'll see that the underlying structure is still the same as what you input. So in this sense, Graphics is like another version of List, with the difference that it is displayed differently. Oct 1 '20 at 17:28
• Allright so in general how can I make sure to understand properly the object I am looking for ? As soon as there is written "xxx represents something" it means it should not be understood as a function ? Is there a tutorial explaining those concepts with further details ? Oct 1 '20 at 17:31
• Unfortunately, it's not quite as consistently formulated in the documentation. Some indicators for inert objects: "represents, wrapper, formats as, ..." - in general, reading the documentation carefully and looking at the examples usually tells you whether a function is inert. Another option is to just look at whether it evaluates in a meaningful way (probably by using InputForm to make sure there's no formatting going on Oct 1 '20 at 18:28