Updated documentation

docs/acknowledgments.md

@@ -17,7 +17,7 @@ Maximilian Fabricius for suggesting improvements to the documentation.
 Additional bug reports and suggestions from André Luiz de Amorim,
 Giulia Savorgnan, David Streich, Guillermo Barro, Sergio Pascual, Lee
 Kelvin, Colleen Gilhuly, Semyeong Oh, Benne Holwerde, David Wilman, 
-Iskren Georgiev, and Corentin Schreiber are gratefully appreciated.
+Iskren Georgiev, Corentin Schreiber, and Dan Prole are gratefully appreciated.
 
 
 ### Data Sources

docs/acknowledgments.rst

@@ -18,7 +18,7 @@ Maximilian Fabricius for suggesting improvements to the documentation.
 Additional bug reports and suggestions from André Luiz de Amorim, Giulia
 Savorgnan, David Streich, Guillermo Barro, Sergio Pascual, Lee Kelvin,
 Colleen Gilhuly, Semyeong Oh, Benne Holwerde, David Wilman, Iskren
-Georgiev, and Corentin Schreiber are gratefully appreciated.
+Georgiev, Corentin Schreiber, and Dan Prole are gratefully appreciated.
 
 Data Sources
 ~~~~~~~~~~~~

docs/bootstrap.md

@@ -64,7 +64,7 @@ fits to an SDSS *r*-band image of the galaxy IC 3478 (single-Sérsic model
 Note the clear correlations between the Sérsic model parameters (*n*, *r\_e*,
 *I\_e*).
 
-See [here](./pyimfit_bootstrap_BtoT.html for an example of using bootstrap output to estimate 
+See [here](./pyimfit_bootstrap_BtoT.html) for an example of using bootstrap output to estimate 
 uncertainties on derived quantities, such as bulge/total values.
 
 <p>

docs/bootstrap.rst

@@ -75,7 +75,7 @@ bootstrap resampling fits to an SDSS *r*-band image of the galaxy IC
 3478 (single-Sérsic model, no PSF convolution). Note the clear
 correlations between the Sérsic model parameters (*n*, *r_e*, *I_e*).
 
-See [here](./pyimfit_bootstrap_BtoT.html for an example of using
+See `here <./pyimfit_bootstrap_BtoT.html>`__ for an example of using
 bootstrap output to estimate uncertainties on derived quantities, such
 as bulge/total values.
 

docs/defining_models.md

@@ -69,7 +69,9 @@ details.
       Geometric parameters: PA, c0 (boxy/disk isophote-shape parameter)
       
       - **FlatBar** -- An elongated structure with a broken-exponential profile along its major
-      axis, suitable for the outer parts of (some) bars in massive disk galaxies.
+      axis, suitable for the outer parts of (some) bars in massive disk galaxies; see 
+      [Erwin et al. (2021)](https://ui.adsabs.harvard.edu/abs/2021MNRAS.502.2446E/abstract)
+      for more details and examples of use. Geometric parameters: PA, ell, deltaPA_max
      
       - **FlatSky** -- Produces a constant background for the entire image.
       

docs/defining_models.rst

@@ -91,7 +91,10 @@ Imfit manual for more details.
 
    -  **FlatBar** – An elongated structure with a broken-exponential
       profile along its major axis, suitable for the outer parts of
-      (some) bars in massive disk galaxies.
+      (some) bars in massive disk galaxies; see `Erwin et
+      al. (2021) <https://ui.adsabs.harvard.edu/abs/2021MNRAS.502.2446E/abstract>`__
+      for more details and examples of use. Geometric parameters: PA,
+      ell, deltaPA_max
 
    -  **FlatSky** – Produces a constant background for the entire image.
 

docs/fit_statistics_and_solvers.md

@@ -42,8 +42,6 @@ To supply your own error/uncertainty map
     imfit_fitter.loadData(imageData, error=errorImageData, ...)
     imfit_fitter.loadData(imageData, error=errorImageData, error_type="variance", ...)
 
-**TBD:** Gain; sky background; read noise
-
 
 2. Pure Poisson Statistics
 
@@ -53,6 +51,36 @@ To specify Poisson-MLR as the fit statistic
     imfit_fitter.loadData(imageData, ..., use_poisson_mlr=True)
 
 
+3. Possible specification of image A/D gain, exposure time, etc.
+
+For any case *except* using a pre-existing error map, you may need to supply information about
+how the values in the data image can be converted to *detected* counts (e.g., detected photoelectrons),
+since the underlying statistical models assume the latter. For example, if the per-pixel values
+were converted to ADUs via an A/D gain, you should supply the gain value (in electrons/ADU);
+if the values are counts/second, you should also supply the total intgration time. If there was a 
+significant read noise term, this should also be described. The relevant
+keywords for the `loadData` and `fit` methods are: `gain` (A/D gain in electrons/ADU), `read_noise`
+(Gaussian read noise in electrons), `exp_time` (seconds, *if* the data values are ADU/sec), and 
+`n_combined` (number of combined exposures). An example:
+
+    imfit_fitter.loadData(imageData, ..., gain=3.1, exp_time=800, read_noise=7.5)
+
+**Note:** If you are using Poisson-MLR as the fit statistic, then `read_noise` should not be used
+(the Poisson MLR statistical model cannot handle a Gaussian read-noise term).
+
+
+4. Possible pre-subtracted background level
+
+In some cases, it may be convenient to work with data images where the sky background has been
+removed. The fitting process needs to know about this, since otherwise there will be problems
+with data pixels having values near or below zero. You can specify a *constant* background level
+that has already been subtracted from the image, using the `original_sky` keyword for the `loadData` 
+and `fit` methods; the value should be in the same units as the data pixels (e.g., ADU, ADU/sec, etc.).
+An example:
+
+    imfit_fitter.loadData(imageData, ..., original_sky=244.9)
+
+
 
 ## Minimizers/Solvers
 

docs/fit_statistics_and_solvers.rst

@@ -50,8 +50,6 @@ To supply your own error/uncertainty map
    imfit_fitter.loadData(imageData, error=errorImageData, ...)
    imfit_fitter.loadData(imageData, error=errorImageData, error_type="variance", ...)
 
-**TBD:** Gain; sky background; read noise
-
 2. Pure Poisson Statistics
 
 To specify Poisson-MLR as the fit statistic
@@ -60,6 +58,44 @@ To specify Poisson-MLR as the fit statistic
 
    imfit_fitter.loadData(imageData, ..., use_poisson_mlr=True)
 
+3. Possible specification of image A/D gain, exposure time, etc.
+
+For any case *except* using a pre-existing error map, you may need to
+supply information about how the values in the data image can be
+converted to *detected* counts (e.g., detected photoelectrons), since
+the underlying statistical models assume the latter. For example, if the
+per-pixel values were converted to ADUs via an A/D gain, you should
+supply the gain value (in electrons/ADU); if the values are
+counts/second, you should also supply the total intgration time. If
+there was a significant read noise term, this should also be described.
+The relevant keywords for the ``loadData`` and ``fit`` methods are:
+``gain`` (A/D gain in electrons/ADU), ``read_noise`` (Gaussian read
+noise in electrons), ``exp_time`` (seconds, *if* the data values are
+ADU/sec), and ``n_combined`` (number of combined exposures). An example:
+
+::
+
+   imfit_fitter.loadData(imageData, ..., gain=3.1, exp_time=800, read_noise=7.5)
+
+**Note:** If you are using Poisson-MLR as the fit statistic, then
+``read_noise`` should not be used (the Poisson MLR statistical model
+cannot handle a Gaussian read-noise term).
+
+4. Possible pre-subtracted background level
+
+In some cases, it may be convenient to work with data images where the
+sky background has been removed. The fitting process needs to know about
+this, since otherwise there will be problems with data pixels having
+values near or below zero. You can specify a *constant* background level
+that has already been subtracted from the image, using the
+``original_sky`` keyword for the ``loadData`` and ``fit`` methods; the
+value should be in the same units as the data pixels (e.g., ADU,
+ADU/sec, etc.). An example:
+
+::
+
+   imfit_fitter.loadData(imageData, ..., original_sky=244.9)
+
 Minimizers/Solvers
 ------------------
 

docs/overview.md

@@ -99,7 +99,7 @@ with a PSF, you can also supply the PSF image (in the form of a 2D NumPy array):
 
 Each image-function parameter within a model can have a "current" value (e.g., the initial guess for 
 the fitting process, the result from the fit, etc.) and either: a set of lower and upper limits for 
-possible values **or** the keyword "fixed", which means the parameter value should be kept constant during fits.
+possible values **or** the string "fixed", which means the parameter value should be kept constant during fits.
 
 **Note**: Unless otherwise specified, all size values are in pixels, and all intensity/surface-brightness
 values are in counts/pixel. (Photometric zero points are not needed except for the optional case of
@@ -204,7 +204,7 @@ the fitting process.
    size as the data array and holds per-pixel sigma or variance values precomputed in some fashion (e.g., from
    an image-reduction pipeline).
 
-   * Poisson-based ("Poisson Maximum-Likelihood-Ratio"): Finally, you can specify that individual pixel 
+   * Poisson-based ("Poisson Maximum-Likelihood-Ratio" = "PMLR"): Finally, you can specify that individual pixel 
    errors come from the model assuming a true Poisson process (rather than the Gaussian approximation to Poisson 
    statistics that's used in the &chi;<sup>2</sup> approaches). This is particularly appropriate when individual 
    pixel values of the data are low.
@@ -273,11 +273,11 @@ the minimization algorithm and verbosity, and start the fit all in one go
 
 #### Inspecting the results of a fit
 
-The Imfit object returns an instance of the FitResult class, which is closely based on the `OptimizeResult`
+The Imfit object returns an instance of the `FitResult` class, which is closely based on the `OptimizeResult`
 class of `scipy.optimize` and is basically a Python dict with attribute access
 
-There are three or four basic things you might want to look at in the FitResult object
-when the fit finishes. You can get these things from the FitResult object that's returned
+There are three or four basic things you might want to look at in the `FitResult` object
+when the fit finishes. You can get these things from the `FitResult` object that's returned
 from the `doFit()` method, or by querying the Imfit object; the examples below show each
 possibility.
 

docs/overview.rst

@@ -125,8 +125,8 @@ Creating a model; setting parameter values and limits
 Each image-function parameter within a model can have a “current” value
 (e.g., the initial guess for the fitting process, the result from the
 fit, etc.) and either: a set of lower and upper limits for possible
-values **or** the keyword “fixed”, which means the parameter value
-should be kept constant during fits.
+values **or** the string “fixed”, which means the parameter value should
+be kept constant during fits.
 
 **Note**: Unless otherwise specified, all size values are in pixels, and
 all intensity/surface-brightness values are in counts/pixel.
@@ -244,12 +244,12 @@ minimized during the fitting process.
    variance values precomputed in some fashion (e.g., from an
    image-reduction pipeline).
 
--  Poisson-based (“Poisson Maximum-Likelihood-Ratio”): Finally, you can
-   specify that individual pixel errors come from the model assuming a
-   true Poisson process (rather than the Gaussian approximation to
-   Poisson statistics that’s used in the χ2 approaches). This is
-   particularly appropriate when individual pixel values of the data are
-   low.
+-  Poisson-based (“Poisson Maximum-Likelihood-Ratio” = “PMLR”): Finally,
+   you can specify that individual pixel errors come from the model
+   assuming a true Poisson process (rather than the Gaussian
+   approximation to Poisson statistics that’s used in the χ2
+   approaches). This is particularly appropriate when individual pixel
+   values of the data are low.
 
 You can also tell the ``Imfit`` object useful things about the data
 values: what A/D gain conversion was applied, any Gaussian read noise,
@@ -329,14 +329,15 @@ algorithm and verbosity, and start the fit all in one go
 Inspecting the results of a fit
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-The Imfit object returns an instance of the FitResult class, which is
-closely based on the ``OptimizeResult`` class of ``scipy.optimize`` and
-is basically a Python dict with attribute access
+The Imfit object returns an instance of the ``FitResult`` class, which
+is closely based on the ``OptimizeResult`` class of ``scipy.optimize``
+and is basically a Python dict with attribute access
 
 There are three or four basic things you might want to look at in the
-FitResult object when the fit finishes. You can get these things from
-the FitResult object that’s returned from the ``doFit()`` method, or by
-querying the Imfit object; the examples below show each possibility.
+``FitResult`` object when the fit finishes. You can get these things
+from the ``FitResult`` object that’s returned from the ``doFit()``
+method, or by querying the Imfit object; the examples below show each
+possibility.
 
 1. See if the fit actually converged (either ``True`` or ``False``):
 

docs/sample_usage.md

@@ -18,7 +18,7 @@ and then fit the model to the data:
     # read in image data
     image_data = fits.getdata(imageFile)
 
-    # construct model from config file
+    # construct model (ModelDescription object) from config file
     model_desc = pyimfit.ModelDescription.load(configFile)
 
     # create an Imfit object, using the previously loaded model configuration
@@ -91,8 +91,8 @@ to read it from a text file):
 
     # etc.
 
-You can do the same thing by defining the model using a set of nested Python dicts, 
-and passing the parent dict to the ModelObject.xxx function: 
+Another way to construct the model is by defining it using a set of nested Python dicts, 
+and passing the parent dict to the `ModelObject.dict_to_ModelDescription` function: 
 
     # define a function for making a simple bulge+disk model, where both components 
     # share the same central coordinate; this version uses dicts internally

docs/sample_usage.rst

@@ -21,7 +21,7 @@ Imfit-format text file, and then fit the model to the data:
    # read in image data
    image_data = fits.getdata(imageFile)
 
-   # construct model from config file
+   # construct model (ModelDescription object) from config file
    model_desc = pyimfit.ModelDescription.load(configFile)
 
    # create an Imfit object, using the previously loaded model configuration
@@ -95,9 +95,9 @@ than having to read it from a text file):
 
    # etc.
 
-You can do the same thing by defining the model using a set of nested
-Python dicts, and passing the parent dict to the ModelObject.xxx
-function:
+Another way to construct the model is by defining it using a set of
+nested Python dicts, and passing the parent dict to the
+``ModelObject.dict_to_ModelDescription`` function:
 
 ::