Usage example for rebin algorithm

[Anders Markvardsen]

A full example of usage example for rebin algorithm

[Anders Markvardsen]

Out of the box sphinx.ext.doctest include options to

1. use :hide: to testcode:: and testoutput::. However, testsetup:: does not have the option, which should be fine since it may just contain from mantid.simpleapi import *

2. doctest_global_setup, code in here gets run for every test. To me it seems a better option to use than testsetup::

3. There is no global option for doing this, although if .rst organished the same a 'replace all' could be used as a switch

About whether or not to display testsetup:: we can set up the .rst such that by default they are not visible. For example you have

.. Expected result
.. testoutput:: Ex1
   :hide:
   
   [ 0.  2.  4.  6.  8.  9.]

which could be 'replace all' with

Expected result
.. testoutput:: Ex1
..   :hide:
   
   [ 0.  2.  4.  6.  8.  9.]

[Anders Markvardsen]

The following rst

Usage
-----

Example - rebin histogram workspace:   

.. testcode:: ExHistSimple

   # create histogram workspace
   dataX = [0,1,2,3,4,5,6,7,8,9] # or use dataX=range(0,10) 
   dataY = [0,1,2,3,4,5,6,7,8] # or use dataY=range(0,9)
   ws = CreateWorkspace(dataX, dataY)
   
   # rebin from min to max with size bin = 2
   ws = Rebin(ws, 2)   
   
   # print out rebinned x values
   print ws.readX(0)   

.. testcleanup:: ExHistSimple

   DeleteWorkspace(ws)
   
.. testoutput:: ExHistSimple
   :hide:
   
   [ 0.  2.  4.  6.  8.  9.]

Example - rebin histogram workspace - logarithmic binning:   

.. testcode:: ExHistLog

   # create histogram workspace
   dataX = [1,2,3,4,5,6,7,8,9,10] # or use dataX=range(1,11) 
   dataY = [1,2,3,4,5,6,7,8,9] # or use dataY=range(1,10)
   ws = CreateWorkspace(dataX, dataY)
   
   # rebin from min to max with logarithmic bins of 0.5
   ws = Rebin(ws, -0.5)   
   
   # print out rebinned x values
   print ws.readX(0)   

.. testcleanup:: ExHistLog

   DeleteWorkspace(ws)
   
.. testoutput:: ExHistLog
   :hide:
   
   [  1.        1.5       2.25      3.375     5.0625    7.59375  10.     ]   

Example - custom rebin histogram workspace:
   
.. testcode:: ExHistCustom

   # create histogram workspace
   dataX = [0,1,2,3,4,5,6,7,8,9] # or use dataX=range(0,10) 
   dataY = [0,1,2,3,4,5,6,7,8] # or use dataY=range(0,9)
   ws = CreateWorkspace(dataX, dataY)
   
   # rebin from 0 to 3 in steps of 2 and from 3 to 9 in steps of 3
   ws = Rebin(ws, "1,2,3,3,9")   
   
   # print out rebinned x values
   print ws.readX(0)   

.. testcleanup:: ExHistCustom

   DeleteWorkspace(ws)
   
.. testoutput:: ExHistCustom
   :hide:
   
   [ 1.  3.  6.  9.]   

Example - use option FullBinsOnly:
   
.. testcode:: ExHistFullBinsOnly

   # create histogram workspace
   dataX = [0,1,2,3,4,5,6,7,8,9] # or use dataX=range(0,10) 
   dataY = [0,1,2,3,4,5,6,7,8] # or use dataY=range(0,9)
   ws = CreateWorkspace(dataX, dataY)
   
   # rebin from min to max with size bin = 2
   ws = Rebin(ws, 2, FullBinsOnly=True)   
   
   # print out rebinned x values
   print ws.readX(0)   

.. testcleanup:: ExHistFullBinsOnly

   DeleteWorkspace(ws)
   
.. testoutput:: ExHistFullBinsOnly
   :hide:
   
   [ 0.  2.  4.  6.  8.]

generates the attached html in pic1.PNG

Not have here added the following to doctest conf.py

doctest_global_setup = """ from mantid.simpleapi import * """

[Anders Markvardsen]

The 4 usage examples in comment 3 covers in my opinion 90% of added documentation user experience for this section of Rebin.

You could add more examples, e.g. eventworkspace example, but for me that has little added user experience benefit.

Hence TO TESTER: pass this ticket if you agree with the above

[Peter Peterson]

There don't appear to be any changes to the repository related to this.

[Anders Markvardsen]

This ticket is suggested to be tested by someone at SNS and easiest done by someone which some experience with sphinx

Today added a temporary repository, ​https://github.com/Anders-Markvardsen/sphinxDocTest, for testing of this ticket beyond what is mentioned in comments. In fact the comments in this ticket are now somewhat out of date.

Hence for tester please download this repository and run make html.

For this ticket check ONLY if you agree with the usage example for the Rebin algorithm. Note there are no examples demonstrating Rebin option PreserveEvents . This will be added later. Nick is working on creating an algorithm for creating suitable event workspaces for this.

BUT it would be useful if someone from SNS today could give either thumb up or down for the Rebin usage example in ​https://github.com/Anders-Markvardsen/sphinxDocTest and/or any other comments

[Peter Peterson]

Another example of this is at ​http://download.mantidproject.org/devwiki/html/Algorithms/doc/Rebin.html

I think the three examples look pretty good.

[Peter Peterson]

As I already commented. This looks good. Since there aren't commits, there is nothing to merge.

[Stuart Campbell]

This ticket has been transferred to github issue ​10317