Merge pull request #75 from dihm/lyse-docs

Initial Pass at Lyse docs

Author: philipstarkey

docs/source/api/analysis_subprocess.rst

@@ -0,0 +1,7 @@
+Analysis Subprocess
+=====================
+
+.. automodule:: lyse.analysis_subprocess
+	:members:
+	:undoc-members:
+	:show-inheritance:

docs/source/api/dataframe_utilities.rst

@@ -0,0 +1,8 @@
+Dataframe Utilities
+======================
+
+.. automodule:: lyse.dataframe_utilities
+	:members:
+	:undoc-members:
+	:inherited-members:
+	:show-inheritance:

docs/source/api/index.rst

@@ -0,0 +1,12 @@
+
+API Reference
+=============
+
+.. toctree::
+   :maxdepth: 2
+
+   lyse_functions
+   run
+   sequence
+   dataframe_utilities
+   analysis_subprocess

docs/source/api/lyse_functions.rst

@@ -0,0 +1,7 @@
+Lyse Helper Functions
+========================
+
+.. automodule:: lyse
+	:members:
+	:undoc-members:
+	:exclude-members: Run, Sequence

docs/source/api/run.rst

@@ -0,0 +1,10 @@
+Run
+==========
+
+.. autoclass:: lyse.Run
+	:members:
+	:undoc-members:
+	:inherited-members:
+	:show-inheritance:
+
+	.. automethod:: lyse.Run.__init__

docs/source/api/sequence.rst

@@ -0,0 +1,10 @@
+Sequence
+==========
+
+.. autoclass:: lyse.Sequence
+	:members:
+	:undoc-members:
+	:inherited-members:
+	:show-inheritance:
+
+	.. automethod:: lyse.Sequence.__init__

docs/source/examples.rst

@@ -0,0 +1,94 @@
+Examples
+==========
+
+An analysis on a single shot
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: python
+
+	from lyse import *
+	from pylab import *
+
+	# Let's obtain our data for this shot -- globals, image attributes and
+	# the results of any previously run single-shot routines:
+	ser = data(path)
+
+	# Get a global called x:
+	x = ser['x']
+
+	# Get a result saved by another single-shot analysis routine which has
+	# already run. The result is called 'y', and the routine was called
+	# 'some_routine':
+	y = ser['some_routine','y']
+
+	# Image attributes are also stored in this series:
+	w_x2 = ser['side','absorption','OD','Gaussian_XW']
+
+	# If we want actual measurement data, we'll have to instantiate a Run object:
+	run = Run(path)
+
+	# Obtaining a trace:
+	t, mot_fluorecence = run.get_trace('mot fluorecence')
+
+	# Now we might do some analysis on this data. Say we've written a
+	# linear fit function (or we're calling some other libaries linear
+	# fit function):
+	m, c = linear_fit(t, mot_fluorecence)
+
+	# We might wish to plot the fit on the trace to show whether the fit is any good:
+
+	plot(t,mot_fluorecence,label='data')
+	plot(t,m*t + x,label='linear fit')
+	xlabel('time')
+	ylabel('MOT flourescence')
+	legend()
+
+	# Don't call show() ! lyse will introspect what figures have been made
+	# and display them once this script has finished running.  If you call
+	# show() it won't find anything. lyse keeps track of figures so that new
+	# figures replace old ones, rather than you getting new window popping
+	# up every time your script runs.
+
+	# We might wish to save this result so that we can compare it across
+	# shots in a multishot analysis:
+	run.save_result('mot loadrate', c)
+
+
+An analysis on multiple shots
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: python
+
+	from lyse import *
+	from pylab import *
+
+	# Let's obtain the dataframe for all of lyse's currently loaded shots:
+	df = data()
+
+	# Now let's see how the MOT load rate varies with, say a global called
+	# 'detuning', which might be the detuning of the MOT beams:
+
+	detunings = df['detuning']
+
+	# mot load rate was saved by a routine called calculate_load_rate:
+
+	load_rates = df['calculate_load_rate', 'mot loadrate']
+
+	# Let's plot them against each other:
+
+	plot(detunings, load_rates,'bo',label='data')
+
+	# Maybe we expect a linear relationship over the range we've got:
+	m, c = linear_fit(detunings, load_rates)
+	# (note, not a function provided by lyse, though I'm sure we'll have
+	# lots of stock functions like this available for import!)
+
+	plot(detunings, m*detunings + c, 'ro', label='linear fit')
+	legend()
+
+	#To save this result to the output hdf5 file, we have to instantiate a
+	#Sequence object:
+	seq = Sequence(path, df)
+	seq.save_result('detuning_loadrate_slope',c)
+
+.. sectionauthor:: Chris Billington

docs/source/img/gui.svg

@@ -6,12 +6,16 @@
 lyse
 ====
 
+**lyse** is a component of the labscript suite. It is a combination API and GUI interface that leverages the API to run user provided analysis scripts of experiment shots. This documentation provides a brief outline of the use of lyse.
+
 .. toctree::
    :maxdepth: 2
    :hidden:
    :caption: DOCUMENTATION
 
-   
+   introduction
+   examples
+   api/index
 
 .. toctree::
    :maxdepth: 2

docs/source/index.rst

@@ -0,0 +1,49 @@
+Introduction
+==============
+
+**Lyse** is a data analysis system which gets *your code* running on experimental data as it is acquired. It is fundamenally based around the ideas of experimental *shots* and analysis *routines*. A shot is one trial of an experiment, and a routine is a ``Python`` script, written by you, that does something with the measurement data from one or more shots.
+
+Analysis routines can be either *single-shot* or *multi-shot*. This determines what data and functions are available to your code when it runs. A single-shot routine has access to the data from only one shot, and functions available for saving results only to the hdf5 file for that shot. A a multi-shot routine has access to the entire dataset from all the runs that are currently loaded into **lyse**, and has functions available for saving results to an hdf5 file which does not belong to any of the shots---it's a file that exists only to save the "meta results".
+
+Actually things are far less magical than that. The only enforced difference between a single shot routine and a multi-shot routine is a single variable provided to your code when **lyse** runs it. Your code runs in a perfectly clean ``Python`` environment with this one exception: a variable in the global namespace called ``path``, which is a path to an hdf5 file. If you have told **lyse** that your routine is a singleshot one, then this path will point to the hdf5 file for the current shot being analysed. On the other hand, if you've told **lyse** that your routine is a multishot one, then it will be the path to an h5 file that has been selected in **lyse** for saving results to.
+
+The other differences listed above are conventions only (though **lyse**'s design is based around the assumption that you'll follow these conventions most of the time), and pertain to how you use the API that **lyse** provides, which will be different depending on what sort of analysis you're doing.
+
+The **lyse** API
+~~~~~~~~~~~~~~~~~
+
+So grea, you've got a single filepath. What data analysis could you possibly do with that? It might seem like you have to still do the same amount of work that you would without an analysis system! Whilst that's not quite true, it's intentionally been designed that way so that you can run your code outside **lyse** with very little modification. Another motivating factor is to minimise the amount of magic black box behaviour, such that an analysis routine is actually just an ordinary ``Python`` script which makes use of an API designed for our purposes. **lyse** is both a program which executes your code, and an API that your code can call on.
+
+To use the API in an analysis routine, begine your code with:
+
+.. code-block:: python
+
+	from lyse import *
+
+The details of the API are found in the :doc:`API reference<api/index>`.
+
+**lyse** GUI
+~~~~~~~~~~~~~~~
+
+The **lyse** GUI uses the API to apply single and multi-shot routines to collections of shot files, added either manually by the user or automatically by BLACS after shot completion.
+
+Here's a screenshot of **lyse**:
+
+.. image:: /img/gui.svg
+	:alt: Lyse Screenshot
+
+1. Here's where single shot routines can be added and removed, with the plus and minus buttons. They will be executed in order on each shot (more on how that works shortly). They can be reordered, or enabled/disabled with the checkboxes on the left. The checkboxes to the right, underneath the plot icons don't currently do anything, but they are intended to provide control over how plots generated by the analysis routines are displayed and updated.
+
+2. Here is where multi-shot routines can be added or removed. The file selection button at the top allows you to select what hdf5 file multi-shot routines will get given (to which they will save their results).
+
+3. Allows pausing of analysis. **lyse** by default will run all single-shot routines on a shot when it arrives (either via the HTTP server or having been manually added). After all the shots have been processed, only then will the multi-shot routines be executed. So if you load ten shots in quickly, the multi-shot routines won't run until they've all been processed by the single-shot routines. However most of the time there will be sufficient delay in between shots arriving that multi-shot routines will be executed pretty much every time a new shot arrives.
+
+4. If you want to re-run single-shot analyses on some shots, select them and click this button. They'll then be processed in order.
+
+5. This will rerun all the multi-shot analyses.
+
+6. Here is where shots appear, either having arrived over HTTP of having been added manually via the file browser (by clicking the plus button). Many columns will populate this part of the screen, one for each global and each of the results (as saved by single-shot routines) present in the shots. A high-priority planned feature is to be able to choose exactly which globals and results are displayed. Otherwise this display is overwhelming to the point of uselessness. The data displayed here represents the entirety of what is available to multi-shot routines via the API provided by **lyse**.
+
+7. This is where the output of routines is displayed, errors in red. If you're putting ``print`` statements in your analysis code, here is where to look to see them. Likewise if there's an exception and analysis stops, look here to see why.
+
+.. sectionauthor:: Chris Billington