Commit f8d7a002 authored by Chris Smith's avatar Chris Smith
Browse files

Many docstring updates

parent dc204aae
......@@ -83,9 +83,9 @@ author = u'Numan Laanait, Suhas Somnath, Chris Smith'
# built documents.
#
# The short X.Y version.
version = u'0.0a27'
version = u'0.0a34'
# The full version, including alpha/beta/rc tags.
release = u'0.0a27'
release = u'0.0a34'
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
......
......@@ -97,6 +97,22 @@ pycroscopy.io.translators.image module
:undoc-members:
:show-inheritance:
pycroscopy.io.translators.ndata_translator module
-------------------------------------------------
.. automodule:: pycroscopy.io.translators.ndata_translator
:members:
:undoc-members:
:show-inheritance:
pycroscopy.io.translators.numpy_translator module
-------------------------------------------------
.. automodule:: pycroscopy.io.translators.numpy_translator
:members:
:undoc-members:
:show-inheritance:
pycroscopy.io.translators.oneview module
----------------------------------------
......
......@@ -88,6 +88,14 @@ pycroscopy.processing.image_processing module
:undoc-members:
:show-inheritance:
pycroscopy.processing.image_transformation module
-------------------------------------------------
.. automodule:: pycroscopy.processing.image_transformation
:members:
:undoc-members:
:show-inheritance:
pycroscopy.processing.proc_utils module
---------------------------------------
......
......@@ -16,6 +16,14 @@ Subpackages
Submodules
----------
pycroscopy.viz.be_viz_utils module
----------------------------------
.. automodule:: pycroscopy.viz.be_viz_utils
:members:
:undoc-members:
:show-inheritance:
pycroscopy.viz.plot_utils module
--------------------------------
......
......@@ -77,18 +77,19 @@ class BELoopModel(Model):
"""
Checks whether or not the provided object can be analyzed by this class.
Parameters:
----
Parameters
----------
h5_main : h5py.Dataset instance
The dataset containing the SHO Fit (not necessarily the dataset directly resulting from SHO fit)
over which the loop projection, guess, and fit will be performed.
variables : list(string)
The dimensions needed to be present in the attributes of h5_main to analyze the data with Model.
Returns:
Returns
-------
legal : Boolean
Whether or not this dataset satisfies the necessary conditions for analysis
"""
if h5_main.file.attrs['data_type'] != 'BEPSData':
warn('Provided dataset does not appear to be a BEPS dataset')
......
......@@ -157,12 +157,12 @@ class BESHOmodel(Model):
"""
Returns a chunk of data for the guess or the fit
Parameters:
Parameters
-----
None
Returns:
--------
Returns
-------
None
"""
if self._start_pos < self.h5_main.shape[0]:
......@@ -185,12 +185,12 @@ class BESHOmodel(Model):
"""
Returns a chunk of guess dataset corresponding to the main dataset
Parameters:
-----
Parameters
----------
None
Returns:
--------
Returns
-------
None
"""
if self.data is None:
......
......@@ -31,7 +31,7 @@ class GuessMethods(object):
Parameters
----------
args: dictionary
List of optional parmeters for this function - not used.
List of optional parameters for this function - not used.
kwargs: dictionary
Passed to find_peaks_cwt().
......
......@@ -26,7 +26,7 @@ class Model(object):
For now, we assume that the guess dataset has not been generated for this dataset but we will relax this requirement
after testing the basic components.
Parameters:
Parameters
----
h5_main : h5py.Dataset instance
The dataset over which the analysis will be performed. This dataset should be linked to the spectroscopic
......@@ -34,7 +34,7 @@ class Model(object):
variables : list(string), Default ['Frequency']
Lists of attributes that h5_main should possess so that it may be analyzed by Model.
Returns:
Returns
-------
None
......@@ -92,7 +92,7 @@ class Model(object):
Checks whether or not the provided object can be analyzed by this Model class.
Classes that extend this class will do additional checks to ensure that the supplied dataset is legal.
Parameters:
Parameters
----
h5_main : h5py.Dataset instance
The dataset over which the analysis will be performed. This dataset should be linked to the spectroscopic
......@@ -101,7 +101,7 @@ class Model(object):
variables : list(string)
The dimensions needed to be present in the attributes of h5_main to analyze the data with Model.
Returns:
Returns
-------
legal : Boolean
Whether or not this dataset satisfies the necessary conditions for analysis
......@@ -127,11 +127,11 @@ class Model(object):
"""
Returns a chunk of data for the guess or the fit
Parameters:
Parameters
-----
None
Returns:
Returns
--------
"""
......@@ -153,11 +153,11 @@ class Model(object):
Should be called BEFORE _getDataChunk since it relies upon current values of
self.__start_pos, self._end_pos
Parameters:
Parameters
-----
None
Returns:
Returns
--------
"""
......@@ -375,7 +375,7 @@ class Model(object):
# def _optimize(self, func, data, guess, solver, parallel='multiprocess',
# processors=max(1, abs(mp.cpu_count()-2)), **kwargs):
# """
# Parameters:
# Parameters
# -----
# func : callable
# Function of the parameters.
......@@ -393,7 +393,7 @@ class Model(object):
# **kwargs:
# Additional keyword arguments that are passed on to the solver.
#
# Returns:
# Returns
# -------
# Results of the optimization.
#
......
......@@ -455,30 +455,31 @@ def reshape_to_Ndims(h5_main, h5_pos=None, h5_spec=None):
Parameters
----------
h5_main : HDF5 Dataset
2D data to be reshaped
h5_pos : HDF5 Dataset, optional
Position indices corresponding to rows in `h5_main`
h5_spec : HDF5 Dataset, optional
Spectroscopic indices corresponding to columns in `h5_main`
h5_main : HDF5 Dataset
2D data to be reshaped
h5_pos : HDF5 Dataset, optional
Position indices corresponding to rows in `h5_main`
h5_spec : HDF5 Dataset, optional
Spectroscopic indices corresponding to columns in `h5_main`
Returns
-------
ds_Nd : N-D numpy array
N dimensional numpy array arranged as [positions slowest to fastest, spectroscopic slowest to fastest]
success : boolean or string
True if full reshape was successful
ds_Nd : N-D numpy array
N dimensional numpy array arranged as [positions slowest to fastest, spectroscopic slowest to fastest]
success : boolean or string
True if full reshape was successful
"Positions" if it was only possible to reshape by
the position dimensions
"Positions" if it was only possible to reshape by
the position dimensions
False if no reshape was possible
False if no reshape was possible
Notes
-----
If either `h5_pos` or `h5_spec` are not provided, the function will first
attempt to find them as attributes of `h5_main`. If that fails, it will
generate dummy values for them.
"""
if h5_pos is None:
......@@ -591,30 +592,31 @@ def reshape_from_Ndims(ds_Nd, h5_pos=None, h5_spec=None):
Parameters
----------
ds_Nd : numpy.array
N dimensional numpy array arranged as [positions slowest to fastest, spectroscopic slowest to fastest]
h5_pos : HDF5 Dataset
Position indices corresponding to rows in the final 2d array
h5_spec : HDF5 Dataset
Spectroscopic indices corresponding to columns in the final 2d array
ds_Nd : numpy.array
N dimensional numpy array arranged as [positions slowest to fastest, spectroscopic slowest to fastest]
h5_pos : HDF5 Dataset
Position indices corresponding to rows in the final 2d array
h5_spec : HDF5 Dataset
Spectroscopic indices corresponding to columns in the final 2d array
Returns
-------
ds_2d : numpy.array
2 dimensional numpy array arranged as [positions, spectroscopic]
success : boolean or string
True if full reshape was successful
ds_2d : numpy.array
2 dimensional numpy array arranged as [positions, spectroscopic]
success : boolean or string
True if full reshape was successful
"Positions" if it was only possible to reshape by
the position dimensions
"Positions" if it was only possible to reshape by
the position dimensions
False if no reshape was possible
False if no reshape was possible
Notes
-----
If either `h5_pos` or `h5_spec` are not provided, the function will
assume the first dimension is position and the remaining are spectroscopic already
in order from fastest to slowest.
"""
if h5_pos is None:
......
......@@ -26,6 +26,7 @@ def read_image(image_path, *args, **kwargs):
image_parms : dict
Dictionary containing image parameters. If image type does not have
parameters then an empty dictionary is returned.
"""
ext = os.path.splitext(image_path)[1]
if ext == '.dm3':
......@@ -54,6 +55,7 @@ def read_dm3(image_path, get_parms=True):
-------
image : numpy.ndarray
Array containing the image from the file `image_path`
"""
image_file = open(image_path, 'rb')
dmtag = parse_dm_header(image_file)
......@@ -100,8 +102,18 @@ def read_dm4(file_path, *args, **kwargs):
"""
Read dm4 file
:param file_path:
:return:
Parameters
----------
file_path : str
Path to the file to be read
Returns
-------
image_array : numpy.ndarray
Image data from the file located at `file_path`
file_parms : dict
Dictionary of parameters read from the dm4 file
"""
get_parms = kwargs.pop('get_parms', True)
header = kwargs.pop('header', None)
......@@ -146,6 +158,7 @@ def parse_dm4_parms(dm4_file, tag_dir, base_name=''):
tag_dir.name : str
Name of the directory
tag_dir.dm4_tag : str
base_name : str
Base name of parameters. Tag and subdirectory names will be appended
for named tags and subdirectories. Unnamed ones will recieve a number.
......@@ -155,6 +168,7 @@ def parse_dm4_parms(dm4_file, tag_dir, base_name=''):
-------
parm_dict : dict()
Dictionary containing the name:value pairs of all parameters `dm4_file`
"""
parm_dict = dict()
......@@ -227,6 +241,11 @@ def try_tag_to_string(tag_data):
tag_data : array.array
Array of 16-bit integers
Returns
-------
tag_data : str
Decoded string from the integer tag
"""
if not isinstance(tag_data, array.array):
return tag_data
......@@ -244,20 +263,28 @@ def try_tag_to_string(tag_data):
return tag_data
def read_txt(image_path, *args, **kwargs):
def read_txt(image_path, header_lines=0, delimiter=None, *args, **kwargs):
"""
:param image_path:
:param args:
:param kwargs:
:return:
"""
Parameters
----------
image_path : str
Path to the image file
header_lines : int
Number of lines to skip as the header
delimiter : str
Separator between the columns of data
args
kwargs
header_lines = kwargs.pop('header_lines', 0)
delimiter = kwargs.pop('delimiter', None)
Returns
-------
image : numpy.ndarray
Image array read from the plaintext file
image = np.loadtxt(image_path,
"""
image = np.loadtxt(image_path, *args,
skiprows=header_lines,
delimiter=delimiter)
delimiter=delimiter, **kwargs)
return image
\ No newline at end of file
......@@ -1505,11 +1505,11 @@ class BEHistogram():
"""
Create the histogram for a single dataset
Parmeters
---------
Parameters
----------
h5_main : HDF5 Dataset
Main_Dataset to be histogramed
activ_udvs_steps : numpy array
active_udvs_steps : numpy array
the active udvs steps in the current plot group
x_hist : 1d numpy array
the spectroscopic indices matrix, used to find the
......@@ -1519,7 +1519,8 @@ class BEHistogram():
-------
ds_hist : numpy array
the 4 histogram matrices
"""
"""
"""
......
......@@ -1100,7 +1100,7 @@ class BEPSndfPixel(object):
b. Amplitude, Phase Variation, Band Edge Smoothing, Band Edge Trim - Harder to find out what happened
exactly - FFT should show changes
c. BE repeats, desired duration - changes in the spectrogram length?
2. VS Parameters:
2. VS Parameters
a. Amplitude, Phase shift - Changes in the AC_amp_vec / DC offset
b. Offset, Read voltage - Shows up in the DC offset
c. Steps per full Cycle - Changes in DC offset / AC amplitude ....
......
......@@ -66,8 +66,8 @@ class Translator(object):
"""
Writes the provided datasets and parameters to an h5 file
Parmeters
---------
Parameters
----------
h5_path : String / Unicode
Absolute path of the h5 file to be written
data_name : String / Unicode
......@@ -83,6 +83,7 @@ class Translator(object):
-------
h5_path : String / unicode
Absolute path of the written h5 file
"""
if parm_dict is None:
parm_dict = {}
......
......@@ -179,14 +179,14 @@ class FeatureExtractorSerial(object):
Parameters
----------
detector_name : (string)
name of detector.
lib : (string)
computer vision library to use (opencv or skimage)
The following can be used for:
lib = opencv: SIFT, ORB, SURF
lib = skimage: ORB, BRIEF, CENSURE
detector_name : (string)
name of detector.
lib : (string)
computer vision library to use (opencv or skimage)
The following can be used for:
lib = opencv: SIFT, ORB, SURF
lib = skimage: ORB, BRIEF, CENSURE
"""
......
......@@ -14,8 +14,10 @@ from warnings import warn
def getNoiseFloor(fft_data, tolerance):
"""
Paramters
---------
Calculate the noise floor from the `fft_data`
Parameters
----------
fft_data : 1D or 2D complex numpy array
Signal in frequency space (ie - after FFT shifting) arranged as (channel or repetition, signal)
tolerance : unsigned float
......@@ -25,6 +27,7 @@ def getNoiseFloor(fft_data, tolerance):
-------
noise_floor : 1D real numpy array
One value per channel / repetition
"""
fft_data = np.atleast_2d(fft_data)
......@@ -61,14 +64,14 @@ def downSample(fft_vec, freq_ratio):
"""
Downsamples the provided data vector
Parameters:
Parameters
-----------
fft_vec : 1D complex numpy array
Waveform that is already FFT shifted
freq_ratio : float
new sampling rate / old sampling rate (less than 1)
Returns:
Returns
--------
fft_vec : 1D numpy array
downsampled waveform
......@@ -91,7 +94,7 @@ def noiseBandFilter(num_pts, samp_rate, freqs, freq_widths, show_plots=False):
"""
Builds a filter that removes specified noise frequencies
Parameters:
Parameters
---------------------
num_pts : unsigned int
Number of points in the FFT signal
......@@ -104,7 +107,7 @@ def noiseBandFilter(num_pts, samp_rate, freqs, freq_widths, show_plots=False):
Note: sampRate, freqs, freq_widths have same units - eg MHz
Returns:
Returns
----------
noise_filter : 1D numpy array
Array of ones set to 0 at noise bands
......@@ -161,8 +164,8 @@ def makeLPF(num_pts, samp_rate, f_cutoff, roll_off=0.05):
"""
Builds a low pass filter
Paramters:
-----------
Parameters
----------
num_pts : unsigned int
Points in the FFT. Assuming Signal in frequency space (ie - after FFT shifting)
samp_rate : unsigned integer
......@@ -173,9 +176,10 @@ def makeLPF(num_pts, samp_rate, f_cutoff, roll_off=0.05):
Frequency band over which the filter rolls off. rol off = 0.05 on a
100 kHz low pass filter -> roll off from 95 kHz (1) to 100 kHz (0)
Returns:
-----------
Returns
-------
LPF : 1D numpy array describing the low pass filter
"""
num_pts = abs(int(num_pts))
......@@ -207,12 +211,12 @@ def makeLPF(num_pts, samp_rate, f_cutoff, roll_off=0.05):
###############################################################################
def harmonicsPassFilter(num_pts, samp_rate, first_freq, band_width, num_harm, doPlots=False):
def harmonicsPassFilter(num_pts, samp_rate, first_freq, band_width, num_harm, do_plots=False):
"""
Builds a filter that only keeps N harmonics
Parameters:
-------------
Parameters
----------
num_pts : unsigned int
Number of points in the FFt signal
samp_rate : unsigned int
......@@ -228,8 +232,8 @@ def harmonicsPassFilter(num_pts, samp_rate, first_freq, band_width, num_harm, do
Note that the frequency values must all have the same units
Returns:
---------
Returns
-------
harm_filter : 1D numpy array
0s where the signal is to be rejected and 1s at harmonics
......@@ -243,7 +247,7 @@ def harmonicsPassFilter(num_pts, samp_rate, first_freq, band_width, num_harm, do
w_vec = 1
if doPlots:
if do_plots:
print('OnlyKeepHarmonics: samp_rate = %2.1e Hz, first harmonic = %3.2f Hz, %d harmonics w/- %3.2f Hz bands\n' %(samp_rate,first_freq,num_harm,band_width))
w_vec = np.arange(-samp_rate/2.0, samp_rate/2.0, samp_rate/num_pts)
fig, ax = plt.subplots(figsize=(5, 5))
......@@ -259,7 +263,7 @@ def harmonicsPassFilter(num_pts, samp_rate, first_freq, band_width, num_harm, do
harm_filter[max(cent-ind+sz+1, 0):min(num_pts, cent+ind-sz)] = 0
if doPlots:
if do_plots:
fig2, ax2 = plt.subplots(figsize=(5, 5))
ax2.plot(w_vec, harm_filter)
ax2.set_title('Step 1')
......@@ -269,7 +273,7 @@ def harmonicsPassFilter(num_pts, samp_rate, first_freq, band_width, num_harm, do
harm_filter[:cent-ind-sz] = 0
harm_filter[cent+ind+sz+1:] = 0
if doPlots:
if do_plots:
fig3, ax3 = plt.subplots(figsize=(5, 5))
ax3.plot(w_vec, harm_filter)
ax3.set_title('Step 2')
......@@ -282,7 +286,7 @@ def harmonicsPassFilter(num_pts, samp_rate, first_freq, band_width, num_harm, do
ind2 = int(round(num_pts*((harm_ind+1)*first_freq/samp_rate)))
harm_filter[cent-ind2+sz+1:cent-ind-sz] = 0
harm_filter[cent+ind+sz+1:cent+ind2-sz] = 0
if doPlots:
if do_plots:
fig4, ax4 = plt.subplots(figsize=(5, 5))
ax4.plot(w_vec, harm_filter)
ax4.set_title('Step %d' % (harm_ind + 2))
......@@ -296,7 +300,7 @@ def harmonicsPassFilter(num_pts, samp_rate, first_freq, band_width, num_harm, do
# """
# Removes specified noise frequencies from the signal
#
# Parameters:
# Parameters
# ---------------------
# * F_AI_vec -- matrix (chan x pts) already FFT + FFT shifted
#
......
......@@ -36,7 +36,7 @@ def test_filter(resp_wfm, filter_parms, samp_rate, show_plots=True, use_rainbow_
resp_wfm : 1D numpy float array
Raw response waveform in the time domain
filter_parms : dictionary
Dictionary that contains all the filtering parameters
Dictionary that contains all the filtering parameters, see Notes for details.
samp_rate : unsigned int