add series type introduction pages (#322)

Author: Ininterrompue

docs/make.jl

@@ -111,6 +111,10 @@ const PAGES = Any[
         "Installation" => "install.md",
         "Basics" => "basics.md",
         "Tutorial" => "tutorial.md",
+        "Series Types" => [
+            "Contour Plots" => "series_types/contour.md",
+            "Histograms" => "series_types/histogram.md",
+        ],
     ],
     "Manual" => [
         "Input Data" => "input_data.md",

docs/src/series_types/contour.md

@@ -0,0 +1,150 @@
+```@setup contour
+using Plots
+Plots.reset_defaults()
+```
+
+# [Contour Plots](@id contour)
+
+The easiest way to get started with contour plots is to use the PyPlot backend. PyPlot requires the `PyPlot.jl` 
+package which can be installed by typing `]` and then `add PyPlot` into the REPL. The first time you call `pyplot()`,
+Julia may install matplotlib for you. All of the plots generated on this page use PyPlot, although the code will work
+for the default GR backend as well.
+
+Let's define some ranges and a function `f(x, y)` to plot. Notice the `'` in the line defining `z`.
+This is the adjoint operator and makes `x` a row vector. You can check the shape of `x'` by typing `size(x')`. In the
+tutorial, we mentioned that the `@.` macro evaluates whatever is to the right of it in an element-wise manner. More
+precisely, the dot `.` is shorthand for broadcasting; since `x'` is of size `(1, 100)` and y is of size `(50, )`, 
+`z = @. f(x', y)` will broadcast the function `f` over `x'` and `y` and yield a matrix of size `(50, 100)`.
+
+```@example contour
+using Plots; pyplot()
+
+f(x, y) = (3x + y^2) * abs(sin(x) + cos(y))
+
+x = range(0, 5, length=100)
+y = range(0, 3, length=50)
+z = @. f(x', y)
+contour(x, y, z)
+```
+
+Much like with `plot!` and `scatter!`, the `contour` function also has a mutating version `contour!` which can be
+used to modify the plot after it has been generated.
+
+With the PyPlot backend, `contour` can also take in a row vector for `x`, so alternatively, you can define `x` as 
+a row vector as shown below and PyPlot will know how to plot it correctly. Beware that this will NOT work for other 
+backends such as the default GR backend, which require `x` and `y` to both be column vectors.
+
+```julia
+x = range(0, 5, length=100)'
+y = range(0, 3, length=50)
+z = @. f(x, y)
+contour(x, y, z)
+```
+
+## Common Attributes
+
+Let's make this plot more presentable with the following attributes:
+
+1. The number of levels can be changed with `levels`. 
+2. Besides the title and axes labels, we can also add contour labels via the attribute `contour_labels`, which has the
+alias `clabels`. We'll use the LaTeXStrings.jl package to write the function expression in the title. (To install this
+package, type `]` and then `add LaTeXStrings` into the REPL.)
+3. The colormap can be changed using `seriescolor`, which has the alias `color`, or even `c`. The default colormap is 
+`:inferno`, from matplotlib. A full list of colormaps can be found in the ColorSchemes section of the manual.
+4. The colorbar location can be changed with the attribute `colorbar`, alias `cbar`. We can remove it by setting
+`cbar=false`.
+5. The widths of the isocontours can be changed using `linewidth`, or `lw`.
+
+Note that `levels`, `color`, and `contour_labels` need to be specified in `contour`.
+
+```@example contour
+using LaTeXStrings
+
+f(x, y) = (3x + y^2) * abs(sin(x) + cos(y))
+
+x = range(0, 5, length=100)
+y = range(0, 3, length=50)
+z = @. f(x', y)
+
+contour(x, y, z, levels=10, color=:turbo, clabels=true, cbar=false, lw=1)
+title!(L"Plot of $(3x + y^2)|\sin(x) + \cos(y)|$")
+xlabel!(L"x")
+ylabel!(L"y")
+```
+
+If only black lines are desired, you can set the `color` attribute like so:
+
+```julia
+contour(x, y, z, color=[:black])
+```
+
+and for alternating black and red lines of a specific hex value, you could type `color=[:black, "#E52B50"]`, and so on.
+
+To get a full list of the available values that an attribute can take, type `plotattr("attribute")` into the REPL. For
+example, `plotattr("cbar")` shows that it can take either symbols from a predefined list (e.g. `:left` and `:top`), 
+which move the colorbar from its default location; or a boolean `true` or `false`, the latter of which hides the 
+colorbar.
+
+## Filled Contours
+
+We can also specify that the contours should be filled in. One way to do this is by using the attribute `fill`:
+
+```julia
+contour(x, y, z, fill=true)
+```
+
+Another way is to use the function `contourf`, along with its mutating version `contourf!`:
+
+```@example contour
+contourf(x, y, z, levels=20, color=:turbo)
+title!(L"(3x + y^2)|\sin(x) + \cos(y)|")
+xlabel!(L"x")
+ylabel!(L"y")
+```
+
+If you are using the GR backend to plot filled contours, there will be black lines separating the filled regions. If
+these lines are undesirable, you can set the line width to 0: `lw=0`.
+
+## Logarithmic Contour Plots
+
+Much like with line and scatter plots, the X and Y axes can be made logarithmic through the `xscale` and `yscale`
+attributes. If both axes need to be logarithmic, then you can set `scale=:log10`.
+
+It will be easier for the backend to generate the plot if the attributes are specified in the `contourf` command 
+directly instead of using their mutating versions.
+
+```@example contour
+g(x, y) = log(x*y)
+
+x = 10 .^ range(0, 6, length=100)
+y = 10 .^ range(0, 6, length=100)
+z = @. g(x', y)
+contourf(x, y, z, color=:plasma, scale=:log10,
+    title=L"\log(xy)", xlabel=L"x", ylabel=L"y")
+```
+
+It is often desired that the colorbar be logarithmic. The process to get this working correctly is a bit more involved
+and will require some manual tweaking. First, we define a function `h(x, y) = exp(x^2 + y^2)`, which we will plot the 
+logarithm of. Then we adjust the `levels` and `colorbar_ticks` attributes.
+
+The `colorbar_ticks` attribute can take in a tuple of two vectors `(tickvalues, ticklabels)`. Since `h(x, y)` varies
+from 10<sup>0</sup> to 10<sup>8</sup> over the prescribed domain, tickvalues will be a vector `tv = 0:8`. We can format
+the labels with superscripts by using LaTeXStrings again. Note that the string interpolation operator changes from `$` 
+to `%$` when working within `L"..."` to avoid clashing with `$` as normally used in LaTeX.
+
+```@example contour
+h(x, y) = exp(x^2 + y^2)
+
+x = range(-3, 3, length=100)
+y = range(-3, 3, length=100)
+z = @. h(x', y)
+
+tv = 0:8
+tl = [L"10^{%$i}" for i in tv]
+contourf(x, y, log10.(z), color=:turbo, levels=8, 
+    colorbar_ticks=(tv, tl), aspect_ratio=:equal, 
+    title=L"\exp(x^{2} + y^{2})", xlabel=L"x", ylabel=L"y")
+```
+
+If you want the fill boundaries to correspond to the orders of magnitude, `levels=8`. Depending on the data, this
+number may require some tweaking. If you want a smoother plot, then you can set `levels` to a much larger number.

docs/src/series_types/histogram.md

@@ -0,0 +1,123 @@
+```@setup histogram
+using Plots; gr()
+Plots.reset_defaults()
+```
+
+# [Histograms](@id histogram)
+
+One-dimensional histograms are accessed through the function `histogram` and its mutating variant `histogram!`. We
+will use the default GR backend on this page.
+
+The most basic plot of a histogram is that of a vector of random numbers sampled from the unit normal distribution.
+
+```@example histogram
+using Plots
+
+x = randn(10^3)
+histogram(x)
+```
+
+The default number of bins is determined by the 
+[Freedman-Diaconis rule](https://en.wikipedia.org/wiki/Histogram#Freedman%E2%80%93Diaconis'_choice). You can select
+other bin algorithms using the attribute `bins`, which can take on values like `:sqrt`, or `:scott` for
+[Scott's rule](https://en.wikipedia.org/wiki/Histogram#Scott's_normal_reference_rule). Alternatively, you can pass
+in a range to more precisely control the number of bins and their minimum and maximum. For example, to plot 20 bins 
+from -5 to +5, type
+
+```julia
+range(-5, 5, length=21)
+```
+
+where we have to add 1 to the length because the length counts the number of bin boundaries. Finally, you can also pass 
+in an integer, like `bins=15`, but this will only be an approximation and the actual number of bins may vary.
+
+## Normalization
+
+It is often desirable to normalize the histogram in some way. To do this, the `normalize` attribute is used, and
+we want `normalize=:pdf` (or `:true`) to normalize the total area of the bins to 1. Since we sampled from the normal 
+distribution, we may as well plot it too. Of course, other common attributes like the title, axis labels, and colors
+can be changed as well.
+
+```@example histogram
+p(x) = 1/sqrt(2pi) * exp(-x^2/2)
+b_range = range(-5, 5, length=21)
+
+histogram(x, label="Experimental", bins=b_range, normalize=:pdf, color=:gray)
+plot!(p, label="Analytical", lw=3, color=:red)
+xlims!(-5, 5)
+ylims!(0, 0.4)
+title!("Normal distribution, 1000 samples")
+xlabel!("x")
+ylabel!("P(x)")
+```
+
+`normalize` can take on other values, including:
+
+* `:probability`, which sums all the bin heights to 1
+* `:density`, which makes the area of each bin equal to the counts
+
+## Weighted Histograms
+
+Another common feature is to weight the values in `x`. Say that `x` consists of data sampled from a uniform
+distribution and we wanted to weight the values according to an exponential function. We would pass in a vector of 
+weights of the same length as `x`. To check that the weighting is done correctly, we plot the exponential function
+multiplied by a normalization factor.
+
+```@example histogram
+f_exp(x) = exp(x)/(exp(1)-1)
+
+x = rand(10^4)
+w = exp.(x)
+
+histogram(x, label="Experimental", bins=:scott, weights=w, normalize=:pdf, color=:gray)
+plot!(f_exp, label="Analytical", lw=3, color=:red)
+plot!(legend=:topleft)
+xlims!(0, 1.0)
+ylims!(0, 1.6)
+title!("Uniform distribution, weighted by exp(x)")
+xlabel!("x")
+ylabel!("P(x)")
+```
+
+## Other Variations
+
+* Histogram scatter plots can be made via `scatterhist` and `scatterhist!`, where points substitute in for bars.
+* Histogram step plots can be made via `stephist` and `stephist!`, where an outline substitutes in for bars.
+
+```@example histogram
+p1 = histogram(x, title="Bar")
+p2 = scatterhist(x, title="Scatter")
+p3 = stephist(x, title="Step")
+plot(p1, p2, p3, layout=(1, 3), legend=false)
+```
+
+## 2D Histograms
+
+Two-dimensional histograms are accessed through the function `histogram2d` and its mutating variant `histogram2d!`.
+To plot them, two vectors `x` and `y` of the same length are needed. 
+
+The histogram is plotted in 2D as a heatmap instead of as 3D bars. The default colormap is `:inferno`, as with contour 
+plots and heatmaps. Bins without any count are not plotted at all by default.
+
+```@example histogram
+x = randn(10^4)
+y = randn(10^4)
+histogram2d(x, y)
+```
+
+Things like custom bin numbers, weights, and normalization work in 2D, along with changing things like the
+colormap. However, the bin numbers need to be passed in via tuples; if only one number is passed in for
+the bins, for example, it is assumed that both axes will set the same number of bins. Additionally, the weights 
+only accept a single vector for the `x` values.
+
+Not plotting the bins at all may not be visually appealing, especially if a colormap is used with dark colors on the 
+low end. To rectify this, use the attribute `show_empty_bins=true`.
+
+```@example histogram
+w = exp.(x)
+histogram2d(x, y, bins=(40, 20), show_empty_bins=true,
+    normalize=:pdf, weights=w, color=:plasma)
+title!("Normalized 2D Histogram")
+xlabel!("x")
+ylabel!("y")
+```