Merge pull request #127 from dihm/destar_imports

Remove star imports from documentation

Author: dihm

docs/listing_1.py

@@ -1 +1,46 @@
-from lyse import *
+from lyse import Run, data, path
+import matplotlib.pyplot as plt
+
+# 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:
+
+plt.plot(t,mot_fluorecence,label='data')
+plt.plot(t,m*t + x,label='linear fit')
+plt.xlabel('time')
+plt.ylabel('MOT flourescence')
+plt.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)

docs/listing_2.py

@@ -1,5 +1,5 @@
-from lyse import *
-from pylab import *
+from lyse import data, Run, path
+import matplotlib.pyplot as plt
 
 # Let's obtain our data for this shot -- globals, image attributes and
 # the results of any previously run single-shot routines:
@@ -29,11 +29,11 @@
 
 # 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()
+plt.plot(t,mot_fluorecence,label='data')
+plt.plot(t,m*t + x,label='linear fit')
+plt.xlabel('time')
+plt.ylabel('MOT flourescence')
+plt.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

docs/listing_3.py

@@ -1,8 +1,8 @@
-from lyse import *
-from pylab import *
+import lyse
+import matplotlib.pyplot as plt
 
 # Let's obtain the dataframe for all of lyse's currently loaded shots:
-df = data()
+df = lyse.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:
@@ -15,17 +15,16 @@
 
 # Let's plot them against each other:
 
-plot(detunings, load_rates,'bo',label='data')
+plt.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!)
+# (note, not a function provided by lyse)
 
-plot(detunings, m*detunings + c, 'ro', label='linear fit')
-legend()
+plt.plot(detunings, m*detunings + c, 'ro', label='linear fit')
+plt.legend()
 
 #To save this result to the output hdf5 file, we have to instantiate a
 #Sequence object:
-seq = Sequence(path, df)
+seq = lyse.Sequence(lyse.path, df)
 seq.save_result('detuning_loadrate_slope',c)

docs/source/examples.rst

@@ -6,8 +6,8 @@ An analysis on a single shot
 
 .. code-block:: python
 
-	from lyse import *
-	from pylab import *
+	from lyse import Run, data, path
+	import matplotlib.pyplot as plt
 
 	# Let's obtain our data for this shot -- globals, image attributes and
 	# the results of any previously run single-shot routines:
@@ -37,11 +37,11 @@ An analysis on a single shot
 
 	# 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()
+	plt.plot(t,mot_fluorecence,label='data')
+	plt.plot(t,m*t + x,label='linear fit')
+	plt.xlabel('time')
+	plt.ylabel('MOT flourescence')
+	plt.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
@@ -58,7 +58,7 @@ Single shot analysis with global file opening
 
 .. code-block:: python
 
-	from lyse import *
+	from lyse import Run, path
 
 	# Instantiate Run object and open
 	# Globally opening the shot keeps the h5 file open
@@ -91,11 +91,11 @@ An analysis on multiple shots
 
 .. code-block:: python
 
-	from lyse import *
-	from pylab import *
+	import lyse
+	import matplotlib.pyplot as plt
 
 	# Let's obtain the dataframe for all of lyse's currently loaded shots:
-	df = data()
+	df = lyse.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:
@@ -108,19 +108,18 @@ An analysis on multiple shots
 
 	# Let's plot them against each other:
 
-	plot(detunings, load_rates,'bo',label='data')
+	plt.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!)
+	# (note, not a function provided by lyse)
 
-	plot(detunings, m*detunings + c, 'ro', label='linear fit')
-	legend()
+	plt.plot(detunings, m*detunings + c, 'ro', label='linear fit')
+	plt.legend()
 
 	#To save this result to the output hdf5 file, we have to instantiate a
 	#Sequence object:
-	seq = Sequence(path, df)
+	seq = lyse.Sequence(lyse.path, df)
 	seq.save_result('detuning_loadrate_slope',c)
 
 .. sectionauthor:: Chris Billington

docs/source/introduction.rst

@@ -1,24 +1,24 @@
 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.
+**Lyse** is a data analysis system which gets *your code* running on experimental data as it is acquired. It is fundamentally 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".
+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 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.
+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 lyse 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.
+So great, 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:
+To use the API in an analysis routine, begin your code with:
 
 .. code-block:: python
 
-	from lyse import *
+	import lyse
 
 The details of the API are found in the :doc:`API reference<api/_autosummary/lyse>`.
 

lyse/__init__.py

@@ -334,7 +334,7 @@ def open(self, mode):
             For better performance, it would be better to combine
             these two openings into one.
 
-            >>> from lyse import *
+            >>> from lyse import Run, path
             >>> shot = Run(path)
             >>> with shot.open('r'):
             >>>     # shot processing that requires reads/writes
@@ -351,7 +351,7 @@ def open(self, mode):
             Open and create the shot handle for the whole analysis
             in a single line.
 
-            >>> from lyse import *
+            >>> from lyse import Run, path
             >>> with Run(path).open('r+') as shot:
             >>>     # shot processing that requires reads/writes
             >>>     t, vals = shot.get_trace('my_trace')