Document plot scaling; improve plot key command docs

Author: briantoby

MDhelp/docs/images/KeyPress.png

@@ -52,8 +52,8 @@ An index on the topics covered in these help pages is given below.
         * [ISODISTORT tab](./phaseisodistort.md)
         * [Dysnomia tab](./phasedysnomia.md)
     3. [Image (IMG)](./image.md) Data Tree entries
-    4. Powder histogram (PWDR) [overview](./powder.md) 
-        * [Parent PWDR data tree entry](./powderparent.md)
+    4. [Powder histogram (PWDR) overview](./powder.md) 
+        * [Parent (main) PWDR data tree entry](./powderparent.md)
         * [Comments](./powdercomments.md)
         * [Limits](./powderlimits.md)
         * [Background](./powderbkg.md)
@@ -70,4 +70,4 @@ An index on the topics covered in these help pages is given below.
     8. [Small Angle Scattering (SASD)](./smallanglescattering.md) Data Tree entries
     9. [Reflectometry (REFD)](./reflectometry.md) Data Tree entries 
     9. [Powder Peaks (PKS)](./peaks.md) Data Tree entries 
- 5. [Others](./others.md): Macintosh notes, Configuration options and Programmers' documentation
+ 5. [Misc](./others.md): Macintosh notes, Configuration options and Programmers' documentation

MDhelp/docs/images/homestack.png

@@ -1,10 +1,10 @@
 <!--- Don't change the HTML version of this file; edit the .md version -->
 <a name="PWDR_overview"></a>
-#  Overview on **PWDR** data tree entries: Powder Diffraction
+#  Overview on **PWDR** (Powder Diffraction) data tree entries 
 
 This is where to find information on the Tree item in GSAS-II associated with powder diffraction (labeled PWDR) and its associated subitems. Note that GSAS-II uses the label of "histogram" for datasets of any type (single-crystal, powder,...) Powder diffraction histograms are added to a project using the Import/"Powder Data" menu items. After data are read, if there are phases present, you will be offered a chance to link the imported histograms to the previously imported phase(s). Likewise, if phase(s) are imported after histograms you will also be asked to link the new phase(s) to existing histograms. It is also possible to add histograms to a phase later by selecting that phase in the data tree and then selecting the "Data" tab and finally using the "Edit Phase"/"Add powder histograms" menu command. Note that there is no limit to the number of histograms that can be included in a GSAS-II project (other than as limited by available computer memory) and histograms that are not linked to at least one phase are ignored in refinements. 
 
-Each powder diffraction dataset has a number of children (subdata tree items) in the tree, as are shown below. 
+Each powder diffraction dataset has a  [main (parent) entry](./powderparent.md) and a number of children (subdata tree items) in the tree: 
 
 * [Comments](./powdercomments.md)
 * [Limits](./powderlimits.md)
@@ -29,8 +29,30 @@ Clicking on the parent or on the subdata tree items, as well as [main (parent) e
 
 <H3 style="color:blue;font-size:1.1em">What are the general options for the plot?</H3>
 
+### Plot scaling
+
+When the histogram is displayed by clicking on a data tree entry, the axes are initially scaled to fit the selected histogram. The plot can be rescaled a number of ways:
+
+* ![](./images/zoom.png) Clicking on the "Zoom" button allows you to trace out a box to use as new limits for the plot.
+* ![](./images/pan.png) Clicking on "Pan" button allows the limits to be repositioned, by dragging with the left mouse button, or the increase or decrease the scaling by dragging either vertically or horizontally with the right button (control+left also works on Macs). 
+* ![](./images/homestack.png) The "Home" button resets the scale to allow the data to fit into the plot. Note that a stack of scaling values are stored. Clicking left arrow provides access to a previous scaling values and then the right button returns to later values. 
+* Pressing the "s" key with the graphics window active causes the plot to enter "sqrt" plotting mode, where intensity values are shown as $\sqrt I$. This also causes the tickmarks and difference plot positions to be repositioned to their initial locations. Pressing the key again exits  "sqrt" plotting mode. 
+Pressing this key twice is a convenient way to reset the plotting scaling and tickmark positioning. 
+* ![](./images/KeyPress.png) An alternative to remembering what key to press is to use the "K" button which provides a menu of all defined key strokes and allows the action to be selected from that menu, so  "sqrt" plotting mode can also be selected using this button. 
+* When the main data tree item is selected, tickmarks and the difference plot location can be selected by dragging the plot item (using the left mouse button) to the desired location. 
+* To specify exact values for plot limits, one can use the Commands/Set plot limits... menu command associated with main data tree item. One can select which limits are to b specified in the window that is opened, so it is possible to scale only the "x" axis. 
+
+Note that plot scaling and difference/tickmark positioning is usually retained when selecting other histograms from the data tree, but only when the histogram type is the same. When moving from x-ray to neutron data, it is assumed that the scaling should be reset. 
+
+It is also possible to define default scaling/appearance settings for a histogram. Use the commands above to define the scaling, as well as position difference & tickmark items (and then press the "!" key (or access from the "K" button. The current display settings for the histogram are saved and these settings will be used when the histogram is redisplayed by clicking on a data tree entry. This is of particular value when working with several histograms having different Q and/or intensity ranges. 
+
 <a name="PWDR_plot_actions"></a>
 <a name="PWDR_dragticks"></a>
+### Plot Actions 
+
+Here is a list of things that one can do with the plot of diffraction patterns from the 
+PWDR entry and some of its subtree entries.
+
 #### For all plots
 
 * **Move mouse**: As the mouse cursor is moved across the plot, the plot status line will show the cursor position as \(2\theta\) (or TOF), d-spacing, Q and the intensity.
@@ -42,23 +64,41 @@ Clicking on the parent or on the subdata tree items, as well as [main (parent) e
 * **Highlight reflection positions** - By selecting the "Reflection Lists" tree item and a phase, if the mouse is moved to the region of a reflection in that phase, a "tool tip" (temporarily displayed text) with the indices for nearby reflections is displayed.
 * **Label reflection positions** - Right-clicking on a reflection tickmark (in the PWDR and "Reflection Lists" plots) will cause an hkl label with the indices for nearby reflection(s) to be displayed. Once a reflection label is shown, it can be dragged to a new position vertically with the left mouse button. Right-clicking on the label will delete it. All hkl labels can be deleted with a menu command. The hkl labels, including their positions, are saved in the GSAS-II project (.gpx) file.
 
+<a name="PWDR_keylist"></a>
+### Plot Key Commands
+
 The following key press characters have defined actions. These actions can also be initiated from the Key Press button on the plot toolbar. Not all actions are available for all PWDR subdata tree items.
 
-<a name="PWDR_keylist"></a>
 #### For line plots
 
-* **s: Sqrt(I) on/off** - changes the y-axis to be the square-root of the intensity. The tick mark and the difference curve location is reset.
-* **w: toggle diff plot mode** - for the pattern selected from the data tree, this will replace the difference (obs-calc) curve with the differences divided by their standard uncertainty (esd) values [(obs-calc)/sigma], which shows the significance of the deviations in the fit of the pattern. (Recommended for proper evaluation of the differences). In this mode both plots have separate zoom control.
+* **a: add magnification region** - Adds a magnification region to the plot and sets the magnification amount to x2. This can be edited (or deleted) in the table that is shown when the main PWDR tree entry is selected.
 * **b: subtract background** - Subtracts the fitted background from the powder pattern. Pressing this again turns the mode off.
+* **c: contour on/off** - if multiple powder profiles, then a contour plot is shown of the observed intensities. Data sets of differing length are padded/trimmed to match the 1st pattern.
+* **f: toggle full length reflection tick marks** - Reflection positions are indicated when the main PDWR tree entry is selected, or when the "Reflection Lists" entry is selected by display of vertical lines. These lines can be shown as tickmarks, short lines or a thin vertical line the full length of the plot. The 'f' key toggles between the two modes.
+* **g: grid lines** - Toggle drawing vertical and horizontal grid lines at all axis label positions. Applies to all plot modes.
+* **m: toggle single/multiple plot** - In single mode, this will show only the one selected from the data tree. In multiple “waterfall” mode all are superimposed; offset options (below) can be used to shift them. The selected one is displayed as points & curve for obs/calc; others as obs lines only.
 * **n: log(I) on/off** - changes the y-axis to be the log10 of the intensity; difference curve is not shown for log(I) on.
-* **q: toggle Q plot** - changes the x-axis to Q. This will put multiple powder patterns taken at different wavelengths/types on the same x-axis scale.
-* **t: toggle d-space plot** - changes the x-axis d-space. This will put multiple powder patterns taken at different wavelengths/types on the same x-axis scale. May not be very useful with data over a wide range.
-* **e: set excluded region** - Defines a new excluded region: press the "e" key with the mouse on one side of the region. Move the mouse to the other side and press "e" again. The region markers (magenta dashed lines) can be dragged to new positions. Available only when the Limits tree entry is selected.
-* **f: toggle full length reflection tick marks** - Reflection positions are indicated when the main PDWR tree entry is selected, or when the "Reflection Lists" entry is selected by display of vertical lines. These lines can be shown as tick marks, short lines or thin vertical line the full length of the plot. The 'f' key toggles between the two modes.
+* **o: remove obs...** - toggle removal of the labels for obs, calc, etc (only phase names for tickmarks remain).
+* **p: plot partials** - plots the partial contributions from each phase, if they have been computed (using Calculate/Compute partials) in addition to the 
+* **q: toggle Q plot** - changes the x-axis to Q (in Å$^{-1}$). This will put multiple powder patterns taken at different wavelengths/types on the same x-axis scale.
+* **s: Sqrt(I) on/off** - changes the y-axis to be the square-root of the intensity. The tick mark and the difference curve location is reset.
+* **t: toggle d-space plot** - changes the x-axis to d-space (in Å). This will put multiple powder patterns taken at different wavelengths/types on the same x-axis scale.
+* **T: toggle plot title** - Removes or returns the plot title
+* **v: Save CSV output** - exports the contents of the plot as a .csv file for use in plotting and spreadsheet programs.
+* **w: toggle diff plot mode** - for the pattern selected from the data tree, this will replace the difference (obs-calc) curve with the differences divided by their standard uncertainty (esd) values [(obs-calc)/sigma], which shows the significance of the deviations in the fit of the pattern. (Recommended for proper evaluation of the differences). In this mode both plots have separate zoom control.
 * **x: show excluded region** - Normally all observed data is plotted. When the "x" key is pressed, data inside excluded regions are not shown.
-* **g: grid lines** - Toggle drawing vertical and horizontal grid lines at all axis label positions. Applies to all plot modes.
-* **a: add magnification region** - Adds a magnification region to the plot and sets the magnification amount to x2. This can be edited (or deleted) in the table that is shown when the main PWDR tree entry is selected.
-* **.: scaling diagnostic** - When the '.' key is pressed, data are plotted as intensity*weight. Normally this = 1.0 for CW data and proportional to incident spectrum for normalized neutron TOF data. Does not include effect of selected weight factor but is equal to number of detectors in multidetector data.
+* **X: cumulative** $\chi^2$ - Superimposes a cumulative** $\chi^2$ plot that shows the data regions most contributing to the disparities in the fit.
+* **+,=: no selection** - This is a three-way toggle. In the default mode, observed points are shown as blue "+" signs (the color can be changed in preferences) and the fitted pattern as a green line. Pressing this once adds a line for the observed points and pressing it again removes the "+" signs and for single histogram plots removes the difference curve. 
+* **.: scaling diagnostic** - When the '.' key is pressed, data are plotted as intensity*weight. Normally this = 1.0 for CW data and proportional to incident spectrum for normalized neutron TOF data. Does not include effect of selected weight factor but is equal to number of detectors in multidetector data. (not in menu)
+* **!: save plot parameters as default** - When the "!" key is pressed, the current display settings for the histogram are saved and these settings will be used when the histogram is displayed by clicking on a data tree entry. To reset the scaling, use either the "s" key (sqrt plotting mode) twice or press the "Home" button to the left on the Matplotlib toolbar. 
+
+* **e: set excluded region** - Defines a new excluded region: press the "e" key with the mouse on one side of the region. Move the mouse to the other side and press "e" again. The region markers (magenta dashed lines) can be dragged to new positions.
+Available only when the Limits tree entry is selected. 
+* **d: highlight next peak** - Selects a peak in the table, or the next peak. 
+Available only when the Peak List or Index Peak List tree entries are selected. 
+* **u: highlight previous peak** - Selects a peak in the table, or the previous peak. 
+Available only when the Peak List or Index Peak List tree entries are selected. 
+ 
 
 #### For line plots with more than one powder pattern
 
@@ -100,7 +140,9 @@ These two key commands allow one to step through the output from k-SUBGROUPSMAG
 <a name="PublicationPlots"></a>
 ### Publication Plots
 
-When the green "P" button is pressed, a copy of the current powder diffraction plot is presented in a separate window. This can only be done with plots of a single histogram, not for waterfall or contour plots. The separate plot offers GUI controls to modify aspects of the plot, for example by changing colors, line widths, plot limits the contents or size of displayed text. The displayed plot, including any changes made, can be exported in a number of formats. These include a number of bitmap formats (JPEG, PNG, TIFF,...) that can then be imported into other programs; several formats offer vector graphics (Postscript, PDF, SVG), that will render at whatever resolution is desired, which can be of great value for posters or other applications where pixilation would be problematic; other formats are intended to be read into other software: Input for the Grace, Igor Pro and Origin programs is offered, as well as a generic .csv file that can be used with custom software. Note that Igor Pro and Origin are commercial products. (Origin export is only available on Windows and requires that Origin 2021 or later be installed on the computer where GSAS-II is installed.) The Grace program is open-source, runs on all major computing platforms, and is available in several versions. 
+![](./images/Publish.png) When the green "P" button is pressed, a copy of the current powder diffraction plot is presented in a separate window. This can only be done with plots of a single histogram, not for waterfall or contour plots. The separate plot offers GUI controls to modify aspects of the plot, for example by changing colors, line widths, plot limits the contents or size of displayed text. The displayed plot, including any changes made, can be exported in a number of formats. These include a number of bitmap formats (JPEG, PNG, TIFF,...) that can then be imported into other programs; several formats offer vector graphics (Postscript, PDF, SVG), that will render at whatever resolution is desired, which can be of great value for posters or other applications where pixilation would be problematic; other formats are intended to be read into other software: Input for the Grace, Igor Pro and Origin programs is offered, as well as a generic .csv file that can be used with custom software. Note that Igor Pro and Origin are commercial products. (Origin export is only available on Windows and requires that Origin 2021 or later be installed on the computer where GSAS-II is installed.) The Grace program is open-source, runs on all major computing platforms, and is available in several versions. 
+
+#### Publication .csv contents
 
 **The `.csv` file** consists of 10 or more columns (depending on the number of phases included in the histogram). The columns are described below, noting that N is the total number of phases and if there are M data points in the histogram, will be M datapoints in each column except in the Phase, tick-pos, and Axis-limits columns.
 

MDhelp/docs/images/pan.png

@@ -22,11 +22,11 @@ where the sum is over the points (N) in the profile delimited by the Limits (see
 
 <H3 style="color:blue;font-size:1.1em">What is plotted here?</H3>
 
-The powder patterns that are part of your project are shown on this page. 
+The powder patterns that are part of your project are shown in the graphics window. 
 They can be displayed as a stack of powder patterns, just a single pattern, or as a contour image of the peak intensities, or be plotted individually. 
 What can be done here will depend on how many patterns are shown as well as what mode is selected. Note that the tick marks and difference curve positions can be customized, as discussed below.
 
-<H3 style="color:blue;font-size:1.1em">What is plotted here?</H3>
+<H3 style="color:blue;font-size:1.1em">What can I do with the plot?</H3>
 
-The plot is the largely the same for the main PWDR Powder Histograms tree entry and
-most subtree entries. See the [overview](./powder.md) section for the [same plot actions](./powder.md#PWDR_plot_actions) and [key press commands](./powder.md#PWDR_keylist). 
+There are a huge number of options that can be used with the plot to change different aspects of how pattern(s) are plotted. The controls are largely the same for graphics associated with the main PWDR Powder Histograms tree entry and
+most subtree entries. See the [overview](./powder.md) section for the [plot actions](./powder.md#PWDR_plot_actions) and [key press commands](./powder.md#PWDR_keylist).