From 6ee2267a16a4199788978574e0e7616866d6142c Mon Sep 17 00:00:00 2001
From: lim <lim@stsci.edu>
Date: Wed, 4 Nov 2015 19:10:07 +0000
Subject: [PATCH] Added a new tutorial as requested by Misty Cracraft.

git-svn-id: https://aeon.stsci.edu/ssb/svn/astrolib/trunk/pysynphot@5214 90a0a646-be8a-0410-bb88-9290da87bc01
---
 doc/source/bandpass.rst  |  3 +++
 doc/source/spectrum.rst  |  3 +++
 doc/source/tutorials.rst | 37 +++++++++++++++++++++++++++++++++++++
 3 files changed, 43 insertions(+)

diff --git a/doc/source/bandpass.rst b/doc/source/bandpass.rst
index acd4068a..98cd5dfa 100644
--- a/doc/source/bandpass.rst
+++ b/doc/source/bandpass.rst
@@ -216,6 +216,9 @@ array([  0.00000000e+00,   0.00000000e+00,   1.87380003e-27, ...,
 >>> bp.sample(2100)
 0.0
 
+:ref:`pysynphot_tutorial_10` offers hints on how to load a bandpass from an ASCII table
+of any format.
+
 
 .. _pysynphot-bandpass-arrays:
 
diff --git a/doc/source/spectrum.rst b/doc/source/spectrum.rst
index 2ec9c72b..db73b252 100644
--- a/doc/source/spectrum.rst
+++ b/doc/source/spectrum.rst
@@ -318,6 +318,9 @@ be one of the :ref:`pysynphot-appendixa-calspec`:
 array([  6.83127903e-12,   6.83185409e-12,   6.83168973e-12, ...,
          3.47564168e-21,   3.47547205e-21,   3.47530241e-21])
 
+See :ref:`Tutorial 10 <pysynphot_tutorial_10>` for example on how to load a
+source spectrum from an ASCII table of any format.
+
 
 .. _pysynphot-empirical-source:
 
diff --git a/doc/source/tutorials.rst b/doc/source/tutorials.rst
index 84934843..aad35440 100644
--- a/doc/source/tutorials.rst
+++ b/doc/source/tutorials.rst
@@ -508,6 +508,43 @@ the F555W filter in HST/ACS WFC1 detector:
 STmag zeropoint for acs,wfc1,f555w is 25.65880
 
 
+.. _pysynphot_tutorial_10:
+
+Tutorial 10: Spectrum from Custom Text File
+===========================================
+
+In this tutorial, you will learn how to load a source spectrum from an ASCII
+table that does not conform to the expected format stated in
+:ref:`pysynphot-io`. Since `~pysynphot.spectrum.FileSourceSpectrum` does not
+allow explicit setting of units, if your table data have non-default wavelength
+or flux units, you have to first load them into Numpy arrays and then use
+`~pysynphot.spectrum.ArraySourceSpectrum` to obtain the spectrum object
+correctly. Similar workflow applies to bandpass for non-default
+wavelength units, using `~pysynphot.spectrum.ArraySpectralElement` (not shown).
+
+Let's say your ASCII table looks like this::
+
+    # My source spectrum
+    # ROW    WAVELENGTH(NM)    FLUX(PHOTLAM)
+    1        400.0             0.1
+    2        401.0             0.1234
+    3        405.0             0.4556
+    ...      ...               ...
+
+There are many ways you can read the ASCII table into Numpy arrays. The example
+below uses Astropy:
+
+>>> from astropy.io import ascii
+>>> tab = ascii.read('myfile.txt', names=['row', 'wave', 'flux'])
+>>> wave = tab['wave']  # Second column
+>>> flux = tab['flux']  # Third column
+
+Construct the source spectrum from the arrays above:
+
+>>> sp = S.ArraySpectrum(
+...     wave=wave, flux=flux, waveunits='nm', fluxunits='photlam')
+
+
 .. _pysynphot_tutorial_exercises:
 
 Exercises