Updated documentation

examples/processing/centering_the_zero_beam.py

@@ -43,14 +43,15 @@
 # Centering the Zero Beam with constant deflection magnitude
 # ----------------------------------------------------------
 # In the presence of electromagnetic fields in the entire sample area,
-# the plane fitting can fail. In this case, two seperate effects can be observed:
+# the plane fitting can fail. In this case, two separate effects can be observed:
 #
 # 1. The zero beam position varies systematically with the scan position due to the effects of descan
 # 2. The zero beam will be deflected from electromagnetic fields in the sample
 #
-# Assuming that the effects of 1 are systematic and that the electomagnetic fields are
-# large we can try to fit a plane to correct for effects of 1 by minimizing the magnitude
-# variance. You may need a mask for good performance.
+# Assuming that the effects of 1 are systematic and that the electromagnetic fields have
+# constant strengths, we can try to fit a plane to correct for effects of 1 by minimizing the 
+# magnitude variance. You may need use a mask and/or have several electromagnetic 
+# domains for good performance.
 
 s_probes = pxm.data.simulated_constant_shift_magnitude()
 
@@ -76,4 +77,9 @@
 s_shifts -= s_linear_plane
 s_shifts.get_magnitude_phase_signal().plot()
 
+# For more realistic data, the linear plane optimization algorithm can give poor results. In this case,
+# you can change the initial values for the optimization algorithm by using the `initial_values` parameter
+# in `get_linear_plane`. See the docstring for more information. Try varying this and see if the plane
+# changes significantly.
+
 # %%

pyxem/signals/beam_shift.py

@@ -90,13 +90,16 @@ def get_linear_plane(
         initial_values : array of floats, optional
             Initial guess for the plane parameters. Useful to vary if the plane fitting
             does not give desirable results. 
-            The x- and y-shifts are described by two linear planes with three parameters. 
-            The two first parameters, d/dx and d/dy, are the changes in x- or y-shift 
-            as you move one position in the navigation space in respectively the x- and y-
-            directions. The third parameter, x_0 or y_0, are respectively the x- and y-
-            shifts in the (0, 0) navigation position. The parameters are laid out thusly,
-            with the first three being for the x-shifts and the rest for the y-shifts:
-            [d/dx, d/dy, x_0, d/dx, d/dy, y_0]
+            The horizontal- and vertical-shifts are described by two linear planes 
+            with three parameters. The two first parameters, d/dx and d/dy, are the changes 
+            in horizontal-shift as you move one position in the navigation space in 
+            respectively the x- and y-directions. I. e. they are the steps in 
+            horizontal-shift as you change x- or y-coordinates. The third parameter,
+            shift_0, is the horizontal-shift in the (0, 0) navigation position. The 
+            vertical-shift are described by similar parameters. In this argument
+            supply the plane parameters in the following way, with the first three 
+            being for the horizontal-shift and the rest for the vertical-shift:
+            [d/dx, d/dy, shift_0, d/dx, d/dy, shift_0]
             Currently only implemented for the case when `constrain_magnitude_variance` 
             is `True`.
         constrain_magnitude_variance : bool, optional