update docs for v3.2

docs/source/users/calc_tutorial.rst

@@ -240,6 +240,28 @@ Customizing Scattering Calculations
 While the examples above will be sufficient for most purposes, there are a few
 additional options that are useful in certain scenarios.
 
+Multi-channel Holograms
+-----------------------
+
+Sometimes a hologram may include data from multiple illumination sources,
+such as two separate wavelengths of incident light. In this case, the extra
+arguments can be passed in as a dictionary object, with keys corresponding to 
+dimension names in the image. You can also use a multi-channel experimental image
+in place of calling :func:`.detector_grid`.
+
+..  testcode::
+
+    illum_dim = {'illumination':['red', 'green']}
+    n_dict = {'red':1.58,'green':1.60}
+    wl_dict = {'red':0.690,'green':0.520}
+    det_c = hp.detector_grid(shape=200, spacing=0.1, extra_dims = illum_dim)
+    s_c = Sphere(r=0.6, n=n_dict, center=[6,6,6])
+    holo = calc_holo(det_c, s_c, illum_wavelen=wl_dict, illum_polarization=(0,1), medium_index=1.33)
+
+..  image:: ../images/calc_multi.png
+    :scale: 300 %
+    :alt: Calculated hologram of a sphere at 2 wavelengths
+
 Scattering Theories in HoloPy
 -----------------------------
 

docs/source/users/infer_tutorial.rst

@@ -25,7 +25,7 @@ Here is the full example.  We'll go through it step-by-step afterward::
     from holopy.core.io import get_example_data_path, load_average
     from holopy.core.process import bg_correct, subimage, normalize
     from holopy.scattering import Sphere, calc_holo
-    from holopy.inference import prior, AlphaModel, tempered_sample
+    from holopy.inference import prior, AlphaModel, TemperedStrategy
 
     # load an image
     imagepath = get_example_data_path('image01.jpg')
@@ -45,9 +45,11 @@ Here is the full example.  We'll go through it step-by-step afterward::
     # Set up the noise model
     model = AlphaModel(s, noise_sd=data_holo.noise_sd, alpha=1)
 
-    result = tempered_sample(model, data_holo)
+    strat = TemperedStrategy()
+    result = strat.sample(model, data_holo)
 
-    result.values()
+    fit_vals = result.values()
+    fit_holo = result.best_fit()
     hp.save('example-sampling.h5', result)
 
 The first few lines import the code needed to compute holograms and do parameter estimation.
@@ -59,7 +61,7 @@ The first few lines import the code needed to compute holograms and do parameter
     from holopy.core.io import get_example_data_path, load_average
     from holopy.core.process import bg_correct, subimage, normalize
     from holopy.scattering import Sphere, calc_holo
-    from holopy.inference import prior, AlphaModel, tempered_sample
+    from holopy.inference import prior, AlphaModel, TemperedStrategy
 
 Preparing Data
 ~~~~~~~~~~~~~~
@@ -187,18 +189,22 @@ iteratively produces and tests sets of scatterers to find the scatterer
 parameters that best reproduce the target hologram. We end up with a
 distribution of values for each parameter (the posterior) that represents our
 updated knowledge about the scatterer when accounting for the expected
-experimental hologram. To do the actual sampling, we use
-:func:`.tempered_sample` (ignoring any RuntimeWarnings about invalid values)::
+experimental hologram. We need to define a :class:`.TemperedStrategy` object that
+sets up the inference calculation, here using default settings. Then, we combine
+the model and data with the strategy to perform the actual sampling (ignoring
+any RuntimeWarnings about invalid values)::
 
-    result = tempered_sample(model, data_holo)
+    strat = TemperedStrategy()
+    result = strat.sample(model, data_holo)
 
 The above line of code may take a long time to run (it takes 10-15 mins on our
 8-core machines). If you just want to quickly see what the results look like,
 try:
 
 ..  testcode::
 
-    result = tempered_sample(model, data_holo, nwalkers=10, samples=100, max_pixels=100)
+    strat = TemperedStrategy(nwalkers=10, max_pixels=100)
+    result = strat.sample(model, data_holo, nsamples=100) 
 
 This code should run very quickly, but its results cannot be trusted for any
 actual data. Nevertheless, it can give you an idea of what format the results
@@ -214,11 +220,12 @@ holograms contain a lot of redundant information owing to their symmetry, so a
 subset of pixels can be analyzed without loss of accuracy. However, 100 pixels
 is probably too few to capture all of the relevant information in the hologram.
 
-You can get a quick look at our obtained values with:
+You can get a quick look at our obtained best fit values and the resulting hologram with:
 
 ..  testcode::
 
-    result.values()
+    fit_vals = result.values()
+    fit_holo = result.best_fit()
 
 ``result.values()`` gives you the maximum a posteriori probability (MAP) value as
 well as one-sigma credibility intervals (or you can request any other sigma with

holopy/inference/__init__.py

@@ -16,5 +16,5 @@
 # You should have received a copy of the GNU General Public License
 # along with HoloPy.  If not, see <http://www.gnu.org/licenses/>.
 
-from .sample import SamplingResult, TemperedSamplingResult, tempered_sample, EmceeStrategy
+from .sample import SamplingResult, TemperedSamplingResult, tempered_sample, EmceeStrategy, TemperedStrategy
 from .noise_model import AlphaModel

holopy/inference/sample.py

@@ -64,7 +64,7 @@ def __init__(self, nwalkers=100, pixels=2000, threads='auto', cleanup_threads=Tr
     def make_guess(self, parameters):
         return np.vstack([p.sample(size=(self.nwalkers)) for p in parameters]).T
 
-    def sample(self, model, data, nsamples, walker_initial_pos=None):
+    def sample(self, model, data, nsamples=1000, walker_initial_pos=None):
         if self.pixels is not None:
             data = make_subset_data(data, pixels=self.pixels)
         if walker_initial_pos is None:
@@ -100,7 +100,7 @@ def __init__(self, next_initial_dist=sample_one_sigma_gaussian, nwalkers=100, mi
         self.nwalkers=nwalkers
         self.next_initial_dist = next_initial_dist
 
-    def sample(self, model, data, nsamples):
+    def sample(self, model, data, nsamples=1000):
         stage_results = []
         guess = self.make_guess(model.parameters)
         for stage in self.stage_strategies[:-1]: