diff --git a/doc/source/images/bayes_results_corner_plot.png b/doc/source/images/bayes_results_corner_plot.png new file mode 100644 index 00000000..a7112a80 Binary files /dev/null and b/doc/source/images/bayes_results_corner_plot.png differ diff --git a/doc/source/images/bayes_results_corner_plot_empty.png b/doc/source/images/bayes_results_corner_plot_empty.png new file mode 100644 index 00000000..31294adf Binary files /dev/null and b/doc/source/images/bayes_results_corner_plot_empty.png differ diff --git a/doc/source/images/bayes_results_diagnostics.png b/doc/source/images/bayes_results_diagnostics.png new file mode 100644 index 00000000..9dbbeebb Binary files /dev/null and b/doc/source/images/bayes_results_diagnostics.png differ diff --git a/doc/source/images/bayes_results_parameter_values.png b/doc/source/images/bayes_results_parameter_values.png new file mode 100644 index 00000000..2e6eab35 Binary files /dev/null and b/doc/source/images/bayes_results_parameter_values.png differ diff --git a/doc/source/images/bayes_results_posteriors.png b/doc/source/images/bayes_results_posteriors.png new file mode 100644 index 00000000..681c5041 Binary files /dev/null and b/doc/source/images/bayes_results_posteriors.png differ diff --git a/doc/source/images/bayes_results_shaded_plot.png b/doc/source/images/bayes_results_shaded_plot.png new file mode 100644 index 00000000..f6802bb1 Binary files /dev/null and b/doc/source/images/bayes_results_shaded_plot.png differ diff --git a/doc/source/images/controls_window.png b/doc/source/images/controls_window.png new file mode 100644 index 00000000..6bf92df7 Binary files /dev/null and b/doc/source/images/controls_window.png differ diff --git a/doc/source/images/controls_window_running.png b/doc/source/images/controls_window_running.png new file mode 100644 index 00000000..6951c23d Binary files /dev/null and b/doc/source/images/controls_window_running.png differ diff --git a/doc/source/images/pan.png b/doc/source/images/pan.png new file mode 100644 index 00000000..437bf090 Binary files /dev/null and b/doc/source/images/pan.png differ diff --git a/doc/source/images/plots_window.png b/doc/source/images/plots_window.png new file mode 100644 index 00000000..0bfe9f94 Binary files /dev/null and b/doc/source/images/plots_window.png differ diff --git a/doc/source/images/plots_window_settings.png b/doc/source/images/plots_window_settings.png new file mode 100644 index 00000000..09a73839 Binary files /dev/null and b/doc/source/images/plots_window_settings.png differ diff --git a/doc/source/images/refresh.png b/doc/source/images/refresh.png new file mode 100644 index 00000000..f2bd4fb9 Binary files /dev/null and b/doc/source/images/refresh.png differ diff --git a/doc/source/images/settings.png b/doc/source/images/settings.png new file mode 100644 index 00000000..2fa6ff7b Binary files /dev/null and b/doc/source/images/settings.png differ diff --git a/doc/source/images/terminal_window.png b/doc/source/images/terminal_window.png new file mode 100644 index 00000000..be76dfe8 Binary files /dev/null and b/doc/source/images/terminal_window.png differ diff --git a/doc/source/images/terminal_window_error.png b/doc/source/images/terminal_window_error.png new file mode 100644 index 00000000..558afbea Binary files /dev/null and b/doc/source/images/terminal_window_error.png differ diff --git a/doc/source/images/terminal_window_run_info.png b/doc/source/images/terminal_window_run_info.png new file mode 100644 index 00000000..38955bc5 Binary files /dev/null and b/doc/source/images/terminal_window_run_info.png differ diff --git a/doc/source/images/zoom.png b/doc/source/images/zoom.png new file mode 100644 index 00000000..2f897e44 Binary files /dev/null and b/doc/source/images/zoom.png differ diff --git a/doc/source/user/control.rst b/doc/source/user/control.rst index d6b9ccb1..24a263b5 100644 --- a/doc/source/user/control.rst +++ b/doc/source/user/control.rst @@ -1,2 +1,57 @@ Controls Window =============== +The fitting controls window allows the user select and configure a fit procedure, start/stop a fit, and view +the final chi-squared from a fit. + +.. image:: ../images/controls_window.png + :scale: 80 + :alt: Fitting Controls Window + :align: center + +RasCAL-2 exposes different fit procedures from the Reflectivity Algorithm Toolbox (RAT), a different procedure can +be selected in the procedure dropdown box. When the procedure is changed, the options on the right side of the window +will be updated to match the selected procedure. RAT has |general options| which are available for all procedures and +unique options for each procedure: + +1. |simplex| +2. |de| +3. |ns| +4. |dream| + +After selecting and configuring a procedure, a fit can be started by clicking the **Run** button, starting a fit will +disable the **Run** button and enable the **Stop** button, to stop a fit simply click the **Stop** button, stopping a +fit will disable the **Stop** button and enable the **Run** button. The **Run** button will be re-enabled if the fit +finishes without being stopped. + +.. note:: A calculation cannot be started while editing the project, the control window will be + disabled until the project is saved. + +.. image:: ../images/controls_window_running.png + :scale: 80 + :alt: Fitting Controls Window with Active Run + :align: center + +If the selected procedure is Simplex or DE, stopping a fit before completion will return the current best result, the +current chi-squared textbox will show the best value during the fit. For the remaining procedures, stopping a fit will +not return a result and the current chi-squared textbox is only updated on fit completion. + + +.. |general options| raw:: html + + general options + +.. |simplex| raw:: html + + Simplex + +.. |de| raw:: html + + Differential Evolution (de) + +.. |ns| raw:: html + + Nested Sampler (ns) + +.. |dream| raw:: html + + DREAM diff --git a/doc/source/user/plot.rst b/doc/source/user/plot.rst index 8235c2b7..6de12754 100644 --- a/doc/source/user/plot.rst +++ b/doc/source/user/plot.rst @@ -1,2 +1,120 @@ Plot Window =========== +The plot window displays plots of the reflectivity curve and SLD profile. The plots are automatically updated +whenever the results are updated. + +Overview +-------- +The plot window provides a pan and zoom tool for interacting with the plots. Clicking on the |pan| button will enable +panning and the plots can be panned around by clicking and dragging with the left mouse button. Click the +|pan| button again to disable panning. Clicking on the |zoom| button will enable zooming and the plots can be zoomed +into by clicking and dragging with the left mouse button to select a region. Click the |zoom| button again to disable +zooming. After panning or zooming, the plots can be reset by clicking the |reset| button. Without a reset, the plot +will keep any zoom or pan until it is updated. + +The spacing between reflectivity curves in the plot can be adjusted using the slider on the left of the plots, simply +drag and release the slider to change the spacing. The maximum spacing is achieved when the slider is dragged to the +bottom of the window. + +.. image:: ../images/plots_window.png + :scale: 80 + :alt: Plots Window + :align: center + +The plot window provides more options for customising the plots in a side panel, the |options| button toggles the +visibility of the side panel which can be hidden to amke the plots slightly bigger. The side panel contains the +following options: + +1. **X-Axis**: sets the X-Axis of the reflectivity curve to linear or log scale. +2. **Y-Axis**: sets the Y-Axis of the reflectivity curve to show ref or Q^4. +3. **Show Error Bars**: toggle the error bars in the reflectivity curve plot. +4. **Show Grid**: toggles a grid in both plots. +5. **Show Legend**: toggles the legend in both plots. + +.. image:: ../images/plots_window_settings.png + :scale: 80 + :alt: Plots Window Settings + :align: center + +Bayesian Plots +-------------- +After running a Bayesian fit, click the **View Bayes Plots** button in the top right of the plot window to view and +customize plots from the Bayesian analysis. This will open the **Bayes Results** dialog which contains the following +sections: + +.. note:: The **View Bayes Plots** button will only be visible after a Bayesian fit is completed, it will be hidden + for non-Bayesian fits. + +1. **Shaded Plot**: This displays a shaded plot with a 65% or 95% confidence interval for the Bayesian analysis. The +confidence interval can be changed using the dropdown in the left side panel. + +.. image:: ../images/bayes_results_shaded_plot.png + :scale: 60 + :alt: Bayes Results Dialog showing Shaded Plot + :align: center + +2. **Posteriors**: This displays the marginalised posteriors for selected parameters from the Bayesian analysis. In the +left side panel, the desired parameters to plot can be selected, plot smoothing can be applied or removed, and estimated +density can be plotted using 3 different methods (normal, log-normal, and KDE). + +.. image:: ../images/bayes_results_posteriors.png + :scale: 60 + :alt: Bayes Results Dialog showing Parameter Values + :align: center + +3. **Diagnostics**: This displays the MCMC chain for selected parameters from the Bayesian analysis. In the left side +panel, the desired parameters to plot can be selected, and the maximum number of points to plot can also be adjusted. + +.. image:: ../images/bayes_results_diagnostics.png + :scale: 60 + :alt: Bayes Results Dialog showing Parameter Values + :align: center + +4. **Corner Plot**: This displays the corner plot for selected parameters from the Bayesian analysis. To improve +responsiveness, the corner plot is not drawn immediately, the **Update Plot** button in the left side panel can be +used to draw the plot as needed. Clicking the **Update Plot** button will start rendering the plots in the background, +the button text will show render progress, and the plots will be displayed when rendering is completed. The desired +parameters to plot can also be selected in the side panel, and plot smoothing can be applied or removed. + +.. image:: ../images/bayes_results_corner_plot_empty.png + :scale: 60 + :alt: Bayes Results Dialog showing Parameter Values + :align: center + +.. image:: ../images/bayes_results_corner_plot.png + :scale: 60 + :alt: Bayes Results Dialog showing Parameter Values + :align: center + + +5. **Parameter Values**: This displays the mean, 65% and 95% confidence interval values for the fitted parameters in +the Bayesian analysis. + +.. image:: ../images/bayes_results_parameter_values.png + :scale: 60 + :alt: Bayes Results Dialog showing Parameter Values + :align: center + +Exporting a Plot +---------------- +To export any given plot as an image: + +1. Click the **Export Plot** button at the bottom of the left side panel. +2. Navigate to the desired save location in the file dialog +3. Enter a name for the file and press the **Save** button. + +The plot will be saved as png file with a white background by default, the background can be made transparent +by changing the **Export Background Colour** option to **none** in Settings dialog + + +.. |options| image:: ../images/settings.png + :scale: 10 + +.. |reset| image:: ../images/refresh.png + :scale: 10 + +.. |pan| image:: ../images/pan.png + :scale: 10 + +.. |zoom| image:: ../images/zoom.png + :scale: 10 diff --git a/doc/source/user/terminal.rst b/doc/source/user/terminal.rst index 602c77c9..63789945 100644 --- a/doc/source/user/terminal.rst +++ b/doc/source/user/terminal.rst @@ -1,2 +1,34 @@ Terminal Window =============== +The terminal window displays fit status, error messages and other information to the user. Messages could +be displayed when modifying a project, running a fit, or when an unexpected issue is encountered. The text +in the terminal cannot be modified but can be selected and copied, the text will be cleared automatically when a +new fit is started but can be cleared manually by clicking *Tools > Clear Terminal* in the menu. + +.. image:: ../images/terminal_window.png + :scale: 80 + :alt: Terminal Window + :align: center + +During a fit, the window will inform the user when the run is started, finished, or stopped by user. It will +also show the progress of the fit, the format of the progress information will vary with the procedure e.g. Most +procedures will print a new line of information text as the fit is progressing, but the DREAM procedure will print +a setting summary and show the progress of the fit in a progress bar at the bottom of the window. + +.. note:: + The amount of information printed during a fit can be customised using the `display` or `updateFreq` options + in the controls window. + +.. image:: ../images/terminal_window_run_info.png + :scale: 80 + :alt: Terminal Window showing Run Information + :align: center + +If an error occurs during project validation or a fit, an error message would be displayed with red text, +sometimes the message could contain extra debug information which shows the line of code where the error occurred, +this debug information is useful for finding problems with custom files. + +.. image:: ../images/terminal_window_error.png + :scale: 80 + :alt: Terminal Window showing Error Message + :align: center diff --git a/rascal2/widgets/plot.py b/rascal2/widgets/plot.py index 9367797e..867e6737 100644 --- a/rascal2/widgets/plot.py +++ b/rascal2/widgets/plot.py @@ -40,7 +40,7 @@ def __init__(self, parent): layout.setContentsMargins(0, 5, 0, 5) self.setLayout(layout) - self.bayes_plots_button = QtWidgets.QPushButton("View Bayes plots", objectName="InteractButton") + self.bayes_plots_button = QtWidgets.QPushButton("View Bayes Plots", objectName="InteractButton") self.bayes_plots_button.setVisible(False) self.bayes_plots_button.pressed.connect(self.show_bayes_plots) self.reflectivity_plot.interaction_layout.addWidget(self.bayes_plots_button) @@ -84,7 +84,7 @@ def __init__(self, parent, initial_plot_settings: list): self.plot_tabs = QtWidgets.QTabWidget() plots = { - "Shaded plot": ShadedPlotWidget, + "Shaded Plot": ShadedPlotWidget, "Posteriors": HistPlotWidget, "Diagnostics": ChainPlotWidget, "Corner Plot": CornerPlotWidget, diff --git a/rascal2/widgets/project/project.py b/rascal2/widgets/project/project.py index accd797f..41950240 100644 --- a/rascal2/widgets/project/project.py +++ b/rascal2/widgets/project/project.py @@ -117,7 +117,7 @@ def create_project_view(self) -> QtWidgets.QWidget: main_layout = QtWidgets.QVBoxLayout() main_layout.setSpacing(20) - show_sliders_button = QtWidgets.QPushButton("Show sliders") + show_sliders_button = QtWidgets.QPushButton("Show Sliders") show_sliders_button.clicked.connect(self.parent.toggle_sliders) self.edit_project_button = QtWidgets.QPushButton("Edit Project", icon=QtGui.QIcon(IconEngine("edit-light.png")))