pyspecdata package

Subpackages

• pyspecdata.axis_manipulation package
  • Submodules
  • pyspecdata.axis_manipulation.inhomog_coords module
  • pyspecdata.axis_manipulation.register_axis module
  • pyspecdata.axis_manipulation.secsy module
  • pyspecdata.axis_manipulation.shear module
  • Module contents
• pyspecdata.fourier package
  • Submodules
  • pyspecdata.fourier.convolve module
  • pyspecdata.fourier.ft module
  • pyspecdata.fourier.ft_shift module
  • pyspecdata.fourier.ftshift module
  • pyspecdata.fourier.ift module
  • pyspecdata.fourier.shear module
  • Module contents
• pyspecdata.load_files package
  • Submodules
  • pyspecdata.load_files.acert module
  • pyspecdata.load_files.bruker_esr module
  • pyspecdata.load_files.bruker_nmr module
  • pyspecdata.load_files.open_subpath module
  • pyspecdata.load_files.prospa module
  • Module contents
• pyspecdata.plot_funcs package
  • Submodules
  • pyspecdata.plot_funcs.image module
  • Module contents

Submodules

pyspecdata.core module

Provides the core components of pyspecdata. Currently, this is a very large file that we will slowly break down into separate modules or packages.

The classes nddata, nddata_hdf, ndshape, the function plot(), and the class fitdata are the core components of the N-Dimensional processing routines. Start by familiarizing yourself with those.

The figlist is the base class for “Figure lists.” Figure lists allows you to organize plots and text and to refer to plots by name, rather than number. They are designed so that same code can be used seamlessly from within ipython, jupyter, a python script, or a python environment within latex (JMF can also distribute latex code for this – nice python based installer is planned). The user does not initialize the figlist class directly, but rather initializes figlist_var. At the end of this file, there is a snippet of code that sets figlist_var to choice that’s appropriate for the working environment (i.e., python, latex environment, *etc.)

There are many helper and utility functions that need to be sorted an documented by JMF, and can be ignored. These are somewhat wide-ranging in nature. For example, box_muller() is a helper function (based on numerical recipes) used by nddata.add_noise(), while h5 functions are helper functions for using pytables in a fashion that will hopefull be intuitive to those familiar with SQL, etc.

exception pyspecdata.core.CustomError(*value, **kwargs)

Bases: Exception

pyspecdata.core.addlabels(labelstring, x, y, labels)

obsolete – use plot_label_points

pyspecdata.core.apply_oom(average_oom, numbers, prev_label='')

scale numbers by the order of magnitude average_oom and change the name of the units by adding the appropriate SI prefix

Parameters:

• average_oom (int or float) – the average order of magnitude to use
• numbers (ndarray) – The numbers to be scaled by average_oom. The array is modified in-place.
• prev_label (str) – a string representing the units

Returns:

new_label – prev_label is prefixed by the appropriate SI prefix

Return type:

str

pyspecdata.core.applyto_rec(myfunc, myarray, mylist)

apply myfunc to myarray with the intention of collapsing it to a smaller number of values

pyspecdata.core.autolegend(*args, **kwargs)

pyspecdata.core.autopad_figure(pad=0.2, centered=False, figname='unknown')

pyspecdata.core.box_muller(length, return_complex=True)

algorithm to generate normally distributed noise

pyspecdata.core.colormap(points, colors, n=256)

pyspecdata.core.concat(datalist, dimname, chop=False)

pyspecdata.core.contour_plot(xvals, yvals, zvals, color='k', alpha=1.0, npts=300, **kwargs)

pyspecdata.core.copy_maybe_none(input)

pyspecdata.core.decorate_rec(xxx_todo_changeme2, xxx_todo_changeme3, drop_rows=False)

Decorate the rows in A with information in B –> if names overlap, keep the ones in A b_ind and a_ind can be either a single key, or a list of keys; if more than one element in B matches that in A, include both options!!

pyspecdata.core.dp(number, decimalplaces=2, scientific=False, max_front=3)

format out to a certain decimal places, potentially in scientific notation

Parameters:

• decimalplaces (int (optional, default 3)) – number of decimal places
• scientific (boolean (optional, default False)) – use scientific notation
• max_front (int (optional, default 3)) – at most this many places in front of the decimal before switching automatically to scientific notation.

pyspecdata.core.emptyfunction()

pyspecdata.core.emptytest(x)

pyspecdata.core.expand_x(*args)

expand the axes. If an argument is passed, then it refers to the position relative to the current coordinates. Values can be: :0: set this side of the axis to 0 :None: leave this side of the axis alone :a double: rescale the distance from the center of the axis to this side by this number

pyspecdata.core.expand_y(*args)

expand the axes. If an argument is passed, then it refers to the position relative to the current coordinates. Values can be: :0: set this side of the axis to 0 :None: leave this side of the axis alone :a double: rescale the distance from the center of the axis to this side by this number

pyspecdata.core.explain_error(e)

Allows you to wrap existing errors with more explanation

For example:

> except BaseException as e: > raise IndexError(“I can’t find the node “+pathstring+explain_error(e)) > + ‘

‘.join([‘> ‘+j for j in str(e).split(‘ ‘)]))# this indents

pyspecdata.core.fa(input, dtype='complex128')

class pyspecdata.core.figlist(*arg, **kwargs)

Bases: object

basename

A basename that can be changed to generate different sets of figures with different basenames. For example, this is useful if you are looping over different sets of data, and generating the same set of figures for each set of data (which would correspond to a basename).

Type:str

figurelist

A list of the figure names

Type:list

figdict

A dictionary containing the figurelist and the figure numbers or objects that they correspond to. Keys of this dictionary must be elements of figurelist.

Type:dict

propdict

Maintains various properties for each element in figurelist. Keys of this dictionary must be elements of figurelist.

Type:dict

adjust_spines(spines)

check_units(testdata, x_index, y_index)

generate_ticks(plotdata, axes, rescale, z_norm=None, y_rescale=1, text_scale=0.05, follow_surface=False, lensoffset=0.005, line_width=0.001, tube_radius=0.001, fine_grid=False)

generate 3d ticks and grid for mayavi

get_fig_number(name)

get_num_figures()

grid()

header(number_above, input_string)

image(A, **kwargs)

Called as fl.image() where fl is the figlist_var object

Note that this code just wraps the figlist properties, and the heavy lifting is done by the image( function. Together, the effect is as follows:

• check_units converts to human-readable units, and makes sure they match the units already used in the plot.

• if A has more than two dimensions, the final dimension in A.dimlabels is used as the column dimension, and a direct-product of all non-column dimensions (a Kronecker product, such that the innermost index comes the latest in the list A.dimlabels) is used as the row dimension. A white/black line is drawn after the innermost index used to create the direct product is finished iterating.

• If A consists of complex data, then an HSV plot (misnomer, actually an HV plot) is used: - convert to polar form: \(z=\rho \exp(i \phi)\) - \(\phi\) determines the color (Hue)

  • Color wheel is cyclical, like \(\exp(i \phi)\)
  • red is taken as \(\phi=0\), purely real and positive
  • green-blue is \(pi\) radians out of phase with red and therefore negative real

  • \(\rho\) determines the intensity (value) - Depending on whether or not black is set (either as a

    keyword argument, or fl.black, the background will be black with high \(\rho\) values “lit up” (intended for screen plotting) or the background will be white with the high \(\rho\) values “colored in” (intended for printing)

• If the data type (dtype) of the data in A is real (typically achieved by calling abs(A) or A.runcopy(real)), then A is plotted with a colormap and corresponding colorbar.

• If no title has been given, it’s set to the name of the current plot in the figurelist

A

Type:nddata or numpy array

x

If A is a numpy array, then this gives the values along the x axis (columns). Defaults to the size of the array. Not used if A is nddata.

Type:Optional[double] or Optional[scalar]

y

If A is a numpy array, then this gives the values along the y axis (columns). Defaults to the size of the array. Not used if A is nddata.

Type:Optional[double] or Optional[scalar]

x_first

Since it’s designed to represent matrices, an image plot by defaults is “transposed” relative to all other plots. If you want the first dimension on the x-axis (e.g., if you are plotting a contour plot on top of an image), then set x_first to True.

Type:boolean

spacing

Determines the size of the white/black line drawn Defaults to 1

Type:integer

ax

the Axis object where the plot should go.

Type:matplotlib Axes

all remaning

are passed through to matplotlib imshow

origin

upper and lower are passed to matplotlib. Flip is for 2D nmr, and flips the data manually.

Type:{‘upper’, ‘lower’, ‘flip’}

.. code-block:: python

from pyspecdata import * fl = figlist_var()

t = r_[-1:1:300j] x = nddata(t,[-1],[‘x’]).labels(‘x’,t) y = nddata(t,[-1],[‘y’]).labels(‘y’,t)

z = x**2 + 2*y**2 print “dimlabels of z:”,z.dimlabels

fl.next(‘image with contours’) fl.image(z,x_first = True) # x_first is needed to align # with the contour plot z.contour(colors = ‘w’,alpha = 0.75)

fl.next(‘simple plot’) # just to show that x is the same # here as well fl.plot(z[‘y’:(0,0.01)])

fl.show(‘compare_image_contour_150911.pdf’)

label_point(data, axis, value, thislabel, show_point=True, xscale=1, **new_kwargs)

only works for 1D data: assume you’ve passed a single-point nddata, and label it

xscale gives the unit scaling

..todo:

Improve the unit scaling, so that this would also work.

Allow it to include a format string that would use the value.

Parameters:show_point (bool) – Defaults to True. Actually generate a point (circle), vs. just the label.

marked_text(marker, input_text='', sep='\n')

Creates a named marker where we can place text. If marker has been used, goes back and places text there.

mesh(plotdata, Z_normalization=None, equal_scale=True, lensoffset=0.001, show_contours=False, grey_surf=False, **kwargs)

next(input_name, legend=False, boundaries=None, twinx=None, fig=None, **kwargs)

Switch to the figure given by input_name, which is used not only as a string-based name for the figure, but also as a default title and as a base name for resulting figure files.

In the future, we actually want this to track the appropriate axis object!

Parameters:

• legend (bool) – If this is set, a legend is created outside the figure.
• twinx ({0,1}) –
  1:plots on an overlayed axis (the matplotlib twinx) whose y axis is labeled on the right when you set this for the first time, you can also set a color kwarg that controls the coloring of the right axis. 0:used to switch back to the left (default) axis
• boundaries – need to add description
• kwargs (dict) – Any other keyword arguments are passed to the matplotlib (mayavi) figure() function that’s used to switch (create) figures.

phaseplot_finalize()

Performs plot decorations that are typically desired for a manual phasing plot. This assumes that the y-axis is given in units of half-cycles ($pi$ radians).

plot(*args, **kwargs)

Parameters:

• linestyle ({':','--','.','etc.'}) – the style of the line
• plottype ({'semilogy','semilogx','loglog'}) – Select a logarithmic plotting style.
• nosemilog (True) – Typically, if you supply a log-spaced axis, a semilogx plot will be automatically selected. This overrides that behavior. Defaults to False.

pop_marker()

use the plot on the top of the “stack” (see push_marker) as the current plot

push_marker()

save the current plot to a “stack” so we can return to it with “pop_marker”

setprops(**kwargs)

show(*args, **kwargs)

show_prep()

text(mytext)

twinx(autopad=False, orig=False, color=None)

use_autolegend(value=None)

No argument sets to true if it’s not already set

pyspecdata.core.figlist_var

alias of pyspecdata.core.figlist

pyspecdata.core.figlistini(first_figure)

processes a figure list argument: typically, you want to have a figure_list keyword argument for every function, which is by default set to None, then call this on the argument – it always returns a figure list, creating a new one if required similarly, somewhere I have another guy that processes the output, so that if it’s set to None, it will by default dump and show the figure list, and not return a figure list in the output

pyspecdata.core.figlistini_old(first_figure)

pyspecdata.core.figlistret(first_figure, figure_list, *args, **kwargs)

class pyspecdata.core.fitdata(*args, **kwargs)

Bases: pyspecdata.core.nddata

Inherits from an nddata and enables curve fitting through use of a sympy expression.

The user creates a fitdata class object from an existing nddata class object, and on this fitdata object can define the functional_form() of the curve it would like to fit to the data of the original nddata. This functional form must be provided as a sympy expression, with one of its variables matching the name of the dimension that the user would like to fit to. The user provides fit coefficients using fit_coeff() and obtains output using fit() and eval().

If you haven’t done this before, create a jupyter notebook (not checked in, just for your own playing around) with: ` import sympy as s s.init_printing() ` you can then use s.symbols( to create symbols/variables that allow you to build the mathematical expression for your fitting function

add_inactive_p(p)

analytical_covariance()

Not up to date

bootstrap(points, swap_out=None, seedval=10347, minbounds={}, maxbounds={})

copy()

Return a full copy of this instance.

Because methods typically change the data in place, you might want to use this frequently.

Parameters:data (boolean) –

Default to True. False doesn’t copy the data – this is for internal use, e.g. when you want to copy all the metadata and perform a calculation on the data.

The code for this also provides the definitive list of the nddata metadata.

covar(*names)

give the covariance for the different symbols

covarmat(*names)

eval(taxis, set_what=None, set_to=None)

after we have fit, evaluate the fit function along the axis taxis set_what and set_to allow you to forcibly set_what a specific symbol to a specific value –> however, this does not affect the class, but only the return value

fit(set_what=None, set_to=None, force_analytical=False)

actually run the fit

fitfunc(p, x)

this wraps fitfunc_raw (which gives the actual form of the fit function) to take care of forced variables

function_string

A property of the fitdata class which stores a string output of the functional form of the desired fit expression provided in func:functional_form in LaTeX format

functional_form

A property of the fitdata class which is set by the user, takes as input a sympy expression of the desired fit expression

gen_indices(this_set, set_to)

pass this this_set and this_set_to parameters, and it will return: indices,values,mask indices –> gives the indices that are forced values –> the values they are forced to mask –> p[mask] are actually active in the fit

guess(use_pseudoinverse=False)

old code that I am preserving here – provide the guess for our parameters; by default, based on pseudoinverse

latex()

show the latex string for the function, with all the symbols substituted by their values

linear(*args, **kwargs)

return the linear-form function, either smoothly along the fit function, or on the raw data, depending on whether or not the taxis argument is given can take optional arguments and pass them on to eval

makereal()

output(*name)

give the fit value of a particular symbol, or a dictionary of all values.

Parameters:name (str (optional)) – name of the symbol. If no name is passed, then output returns a dictionary of the resulting values. Returns:retval – Either a dictionary of all the values, or the value itself. Return type:dict or float

parameter_derivatives(xvals, set=None, set_to=None)

return a matrix containing derivatives of the parameters, can set dict set, or keys set, vals set_to

pinv(*args, **kwargs)

remove_inactive_p(p)

rename(previous, new)

residual(p, x, y, sigma)

just the error function

settoguess()

a debugging function, to easily plot the initial guess

pyspecdata.core.gensearch(labelname, format='%0.3f', value=None, precision=None)

obsolete – use h5gensearch

pyspecdata.core.gridandtick(ax, rotation=(0, 0), precision=(2, 2), labelstring=('', ''), gridcolor=None, formatonly=False, fixed_y_locator=None, use_grid=True, spines=None, y=True)

pyspecdata.core.gridon(gridcolor=None)

pyspecdata.core.h5addrow(bottomnode, tablename, *args, **kwargs)

add a row to a table, creating it if necessary, but don’t add if the data matches the search condition indicated by match_row match_row can be either text or a dictionary – in the latter case it’s passed to h5searchstring

pyspecdata.core.h5attachattributes(node, listofattributes, myvalues)

pyspecdata.core.h5child(thisnode, childname, clear=False, create=None)

grab the child, optionally clearing it and/or (by default) creating it

pyspecdata.core.h5inlist(columnname, mylist)

returns rows where the column named columnname is in the value of mylist

pyspecdata.core.h5join(firsttuple, secondtuple, additional_search='', select_fields=None, pop_fields=None)

pyspecdata.core.h5loaddict(thisnode)

pyspecdata.core.h5nodebypath(h5path, force=False, only_lowest=False, check_only=False, directory='.')

return the node based on an absolute path, including the filename

pyspecdata.core.h5remrows(bottomnode, tablename, searchstring)

pyspecdata.core.h5searchstring(*args, **kwargs)

generate robust search strings :parameter fieldname,value: search AROUND a certain value (overcomes some type conversion issues) optional arguments are the format specifier and the fractional precision: OR :parameter field_and_value_dictionary: generate a search string that matches one or more criteria

pyspecdata.core.h5table(bottomnode, tablename, tabledata)

create the table, or if tabledata is None, just check if it exists

pyspecdata.core.issympy(x)

tests if something is sympy (based on the module name)

pyspecdata.core.join_rec(xxx_todo_changeme, xxx_todo_changeme1)

pyspecdata.core.lambda_rec(myarray, myname, myfunction, *varargs)

make a new field “myname” which consists of “myfunction” evaluated with the fields given by “myargs” as arguments the new field is always placed after the last argument name if myname is in myargs, the original row is popped

pyspecdata.core.lookup_rec(A, B, indexpair)

look up information about A in table B (i.e. chemical by index, etc) indexpair is either the name of the index or – if it’s differently named – the pair of indices given in (A,B) respectively

This will just drop any fields in B that are also in A, and the output uses the first indexname

note that it it seems like the join_rec function above may be more efficient!!

pyspecdata.core.lrecordarray(*x, **kwargs)

pyspecdata.core.lsafe(*string, **kwargs)

replacement for normal lsafe – no escaping

pyspecdata.core.lsafen(*string, **kwargs)

see lsafe, but with an added double newline

pyspecdata.core.make_bar_graph_indices(mystructarray, list_of_text_fields, recursion_depth=0, spacing=0.1)

This is a recursive function that is used as part of textlabel_bargraph; it does NOT work without the sorting given at the beginning of that function

pyspecdata.core.make_ndarray(array_to_conv, name_forprint='unknown')

pyspecdata.core.make_rec(*args, **kwargs)

input,names or a single argument, which is a dictionarynstrlen = 100 gives length of the strings (which need to be specified in record arrays)nyou can also specify (especially useful with the dictionary format) the list order = [str1,str2,…] which orders the output records with the field containing str1 first, then the field containing str2, then any remaining fields

pyspecdata.core.maprep(*mylist)

pyspecdata.core.meanstd_rec(myarray, mylist, standard_error=False)

this is something like applyto_rec, except that it applies the mean and creates new rows for the “error,” where it puts the standard deviation

pyspecdata.core.mybasicfunction(first_figure=None)

this gives the format for doing the image thing note also nextfigure(fl,’name’) and nextfigure({‘lplotproperty’:value})

pyspecdata.core.mydiff(data, axis=-1)

this will replace diff with a version that has the same number of indices, with the last being the copy of the first

pyspecdata.core.myfilter(x, center=250000.0, sigma=100000.0)

class pyspecdata.core.nddata(*args, **kwargs)

Bases: object

This is the detailed API reference. For an introduction on how to use ND-Data, see the Main ND-Data Documentation.

C

shortcut for copy

btw, what we are doing is analogous to a ruby function with functioname!() modify result, and we can use the “out” keyword in numpy.

..todo::

(new idea) This should just set a flag that says “Do not allow this data to be substituted in place,” so that if something goes to edit the data in place, it instead first makes a copy.

also here, see Definition of shallow and deep copy

(older idea) We should offer “N”, which generates something like a copy, but which is sets the equivalent of “nopop”. For example, currently, you need to do something like d.C.argmax('t2'), which is very inefficient, since it copies the whole array. So, instead, we should do d.N.argmax('t2'), which tells argmax and all other functions not to overwrite “self” but to return a new object. This would cause things like “run_nopop” to become obsolete.

add_noise(intensity)

Add Gaussian (box-muller) noise to the data.

Parameters:intensity (double OR function) – If a double, gives the standard deviation of the noise. If a function, used to calculate the standard deviation of the noise from the data: e.g. lambda x: max(abs(x))/10.

aligndata(arg)

This is a fundamental method used by all of the arithmetic operations. It uses the dimension labels of self (the current instance) and arg (an nddata passed to this method) to generate two corresponding output nddatas that I refer to here, respectively, as A and B. A and B have dimensions that are “aligned” – that is, they are identical except for singleton dimensions (note that numpy automatically tiles singleton dimensions). Regardless of how the dimensions of self.data and arg.data (the underlying numpy data) were ordered, A.data and B.data are now ordered identically, where dimensions with the same label (.dimlabel) correspond to the same numpy index. This allows you do do math.

Note that, currently, both A and B are given a full set of axis labels, even for singleton dimensions. This is because we’re assuming you’re going to do math with them, and that the singleton dimensions will be expanded.

Parameters:arg (nddata or ndarray) – The nddata that you want to align to self. If arg is an ndarray, it will try to match dimensions to self based on the length of the dimension. Note: currently there is an issue where this will only really work for 1D data, since it first makes an nddata instance based on arg, which apparently collapses multi-D data to 1D data. Returns:

• A (nddata) – realigned version of self
• B (nddata) – realigned version of arg (the argument)

along(dimname)

Specifies the dimension for the next matrix multiplication (represents the rows/columns).

angle

Return the angle component of the data

argmax(*args, **kwargs)

find the max along a particular axis, and get rid of that axis, replacing it with the index number of the max value

Parameters:raw_index (bool) – return the raw (ndarray) numerical index, rather than the corresponding axis value Note that the result returned is still, however, an nddata (rather than numpy ndarray) object.

argmin(*axes, **kwargs)

If argmin(‘axisname’) find the min along a particular axis, and get rid of that axis, replacing it with the index number of the max value. If argmin(): return a dictionary giving the coordinates of the overall minimum point.

Parameters:raw_index (bool) – Return the raw (ndarray) numerical index, rather than the corresponding axis value. Note that the result returned is still, however, an nddata (rather than numpy ndarray) object.

axis(axisname)

returns a 1-D axis for further manipulation

axlen(axis)

return the size (length) of an axis, by name

Parameters:axis (str) – name of the axis whos length you are interested in

axn(axis)

Return the index number for the axis with the name “axis”

This is used by many other methods. As a simple example, self.:func:axlen`(axis) (the axis length) returns ``shape(self.data)[self.axn(axis)]`

Parameters:axis (str) – name of the axis

cdf(normalized=True, max_bins=500)

calculate the Cumulative Distribution Function for the data along axis_name

only for 1D data right now

Returns: Return type:A new nddata object with an axis labeled values, and data corresponding to the CDF.

check_axis_coords_errors()

chunk(axisin, *otherargs)

“Chunking” is defined here to be the opposite of taking a direct product, increasing the number of dimensions by the inverse of the process by which taking a direct product decreases the number of dimensions. This function chunks axisin into multiple new axes arguments.:

axesout – gives the names of the output axes shapesout – optional – if not given, it assumes equal length – if given, one of the values can be -1, which is assumed length

When there are axes, it assumes that the axes of the new dimensions are nested – e.g., it will chunk a dimension with axis: [1,2,3,4,5,6,7,8,9,10] into dimensions with axes: [0,1,2,3,4], [1,6]

..todo::

Deal with this efficiently when we move to new-style axes

chunk_auto(axis_name, which_field, dimname=None)

assuming that axis “axis_name” is currently labeled with a structured array, choose one field (“which_field”) of that structured array to generate a new dimension Note that for now, by definition, no error is allowed on the axes. However, once I upgrade to using structured arrays to handle axis and data errors, I will want to deal with that appropriately here.

circshift(axis, amount)

contiguous(lambdafunc, axis=None)

Return contiguous blocks that satisfy the condition given by lambdafunc

this function returns the start and stop positions along the axis for the contiguous blocks for which lambdafunc returns true Currently only supported for 1D data

Note

adapted from stackexchange post http://stackoverflow.com/questions/4494404/find-large-number-of-consecutive-values-fulfilling-condition-in-a-numpy-array

Parameters:

• lambdafunc (types.FunctionType) – If only one argument (lambdafunc) is given, then lambdafunc is a function that accepts a copy of the current nddata object (self) as the argument. If two arguments are given, the second is axis, and lambdafunc has two arguments, self and the value of axis.
• axis ({None,str}) – the name of the axis along which you want to find contiguous blocks

Returns:

retval – An \(N\times 2\) matrix, where the \(N\) rows correspond to pairs of axis label that give ranges over which lambdafunc evaluates to True. These are ordered according to descending range width.

Return type:

ndarray

Examples

sum_for_contiguous = abs(forplot).mean('t1')
fl.next("test contiguous")
forplot = sum_for_contiguous.copy().set_error(None)
fl.plot(forplot,alpha = 0.25,linewidth = 3)
print("this is what the max looks like",0.5*sum_for_contiguous.set_error(None).runcopy(max,'t2'))
print(sum_for_contiguous > 0.5*sum_for_contiguous.runcopy(max,'t2'))
retval = sum_for_contiguous.contiguous(quarter_of_max,'t2')
print("contiguous range / 1e6:",retval/1e6)
for j in range(retval.shape[0]):
    a,b = retval[j,:]
    fl.plot(forplot['t2':(a,b)])

contour(labels=True, **kwargs)

Contour plot – kwargs are passed to the matplotlib contour function.

See docstring of figlist_var.image() for an example

labels

Whether or not the levels should be labeled. Defaults to True

Type:boolean

convolve(axisname, filterwidth, convfunc=<function <lambda>>)

Perform a convolution.

Parameters:

• axisname (str) – apply the convolution along axisname
• filterwidth (double) – width of the convolution function.
• convfunc (function) – A function that takes two arguments – the first are the axis coordinates and the second is filterwidth. Default is a normalized Gaussian of width (\(\sigma\)) filterwidth \(\frac{1}{2 \sigma^2}\exp\left( - \frac{x^2}{2 \sigma^2} \right)\) For example if you want a complex Lorentzian with filterwidth controlled by the rate \(R\), i.e. \(\frac{-1}{-i 2 \pi f - R}\) then convfunc = lambda f,R: -1./(-1j*2*pi*f-R)

copy(data=True)

Return a full copy of this instance.

Because methods typically change the data in place, you might want to use this frequently.

Parameters:data (boolean) –

Default to True. False doesn’t copy the data – this is for internal use, e.g. when you want to copy all the metadata and perform a calculation on the data.

The code for this also provides the definitive list of the nddata metadata.

copy_axes(other)

copy_props(other)

Copy all properties (see get_prop()) from another nddata object – note that these include properties pertaining the the FT status of various dimensions.

copyaxes(other)

cropped_log(subplot_axes=None, magnitude=4)

For the purposes of plotting, this generates a copy where I take the log, spanning “magnitude” orders of magnitude This is designed to be called as abs(instance).cropped_log(), so it doesn’t make a copy

diff(thisaxis, backwards=False)

dot(arg)

Tensor dot of self with arg – dot all matching dimension labels. This can be used to do matrix multiplication, but note that the order of doesn’t matter, since the dimensions that are contracted are determined by matching the dimension names, not the order of the dimension.

>>> a = nddata(r_[0:9],[3,3],['a','b'])
>>> b = nddata(r_[0:3],'b')
>>> print a.C.dot(b)
>>> print a.data.dot(b.data)
>>> a = nddata(r_[0:27],[3,3,3],['a','b','c'])
>>> b = nddata(r_[0:9],[3,3],['a','b'])
>>> print a.C.dot(b)
>>> print tensordot(a.data,b.data,axes=((0,1),(0,1)))

>>> a = nddata(r_[0:27],[3,3,3],['a','b','c'])
>>> b = nddata(r_[0:9],[3,3],['a','d'])
>>> print a.C.dot(b)
>>> print tensordot(a.data,b.data,axes=((0),(0)))

extend(axis, extent, fill_with=0, tolerance=1e-05)

If axis is uniformly ascending with spacing \(dx\), then extend by adding a point every \(dx\) until the axis includes the point extent. Fill the newly created datapoints with fill_with.

Parameters:

• axis (str) – name of the axis to extend
• extent (double) – extend the axis axis out to this point
• fill_with (double) – fill the new data points with this value (defaults to 0)
• tolerance (double) – when checking for ascending axis labels, etc., values/differences must match to within tolerance (assumed to represent the actual precision, given various errors, etc.)

extend_for_shear(altered_axis, propto_axis, skew_amount, verbose=False)

this is propto_axis helper function for .fourier.shear

fld(dict_in, noscalar=False)

flatten dictionary – return list

fourier_shear(altered_axis, propto_axis, by_amount, zero_fill=False, start_in_conj=False)

the fourier shear method – see .shear() documentation

fromaxis(*args, **kwargs)

Generate an nddata object from one of the axis labels.

Can be used in one of several ways:

• self.fromaxis('axisname'): Returns an nddata where retval.data consists of the given axis values.
• self.fromaxis('axisname',inputfunc): use axisname as the input for inputfunc, and load the result into retval.data
• self.fromaxis(inputsymbolic): Evaluate inputsymbolic and load the result into retval.data

Parameters:

• axisname (str | list) – The axis (or list of axes) to that is used as the argument of inputfunc or the function represented by inputsymbolic. If this is the only argument, it cannot be a list.
• inputsymbolic (sympy.Expr) – A sympy expression whose only symbols are the names of axes. It is preferred, though not required, that this is passed without an axisname argument – the axis names are then inferred from the symbolic expression.
• inputfunc (function) – A function (typically a lambda function) that taxes the values of the axis given by axisname as input.
• overwrite (bool) – Defaults to False. If set to True, it overwrites self with retval.
• as_array (bool) – Defaults to False. If set to True, retval is a properly dimensioned numpy ndarray rather than an nddata.

Returns:

retval – An expression calculated from the axis(es) given by axisname or inferred from inputsymbolic.

Return type:

nddata | ndarray

ft(axes, tolerance=1e-05, cosine=False, verbose=False, **kwargs)

This performs a Fourier transform along the axes identified by the string or list of strings axes.

It adjusts normalization and units so that the result conforms to

\(\tilde{s}(f)=\int_{x_{min}}^{x_{max}} s(t) e^{-i 2 \pi f t} dt\)

Note that, as noted in the ift() documentation, the inverse transform doesn’t correspond to the equivalent expression for the IFT.

pre-FT, we use the axis to cyclically permute \(t=0\) to the first index

post-FT, we assume that the data has previously been IFT’d If this is the case, passing shift=True will cause an error If this is not the case, passing shift=True generates a standard fftshift shift=None will choose True, if and only if this is not the case

Parameters:

• pad (int or boolean) – pad specifies a zero-filling. If it’s a number, then it gives the length of the zero-filled dimension. If it is just True, then the size of the dimension is determined by rounding the dimension size up to the nearest integral power of 2.
• automix (double) – automix can be set to the approximate frequency value. This is useful for the specific case where the data has been captured on a sampling scope, and it’s severely aliased over.
• cosine (boolean) – yields a sum of the fft and ifft, for a cosine transform

ft_clear_startpoints(axis, t=None, f=None, nearest=None)

Clears memory of where the origins in the time and frequency domain are. This is useful, e.g. when you want to ift and center about time=0. By setting shift=True you can also manually set the points.

Parameters:

• t (float, 'current', 'reset', or None) – keyword arguments t and f can be set by (1) manually setting the start point (2) using the string ‘current’ to leave the current setting a lone (3) ‘reset’, which clears the startpoint and (4) None, which will be changed to ‘current’ when the other is set to a number or ‘rest’ if both are set to None.
• t – see t
• nearest (bool) –

  Shifting the startpoint can only be done by an integral number of datapoints (i.e. an integral number of dwell times, dt, in the time domain or integral number of df in the frequency domain). While it is possible to shift by a non-integral number of datapoints, this is done by applying a phase-dependent shift in the inverse domain. Applying such a axis-dependent shift can have vary unexpected effects if the data in the inverse domain is aliased, and is therefore heavily discouraged. (For example, consider what happens if we attempt to apply a frequency-dependent phase shift to data where a peak at 110 Hz is aliased and appears at the 10 Hz position.)

  Setting nearest to True will choose a startpoint at the closest integral datapoint to what you have specified.

  Setting nearest to False will explicitly override the safeties – essentially telling the code that you know the data is not aliased in the inverse domain and/or are willing to deal with the consequences.

ft_state_to_str(*axes)

Return a string that lists the FT domain for the given axes.

\(u\) refers to the original domain (typically time) and \(v\) refers to the FT’d domain (typically frequency) If no axes are passed as arguments, it does this for all axes.

ftshift(axis, value)

FT-based shift. Currently only works in time domain.

This was previously made obsolete, but is now a demo of how to use the ft properties. It is not the most efficient way to do this.

get_covariance()

this returns the covariance matrix of the data

get_error(*args)

get a copy of the errors either set_error(‘axisname’,error_for_axis) or set_error(error_for_data)

get_ft_prop(axis, propname=None)

Gets the FT property given by propname. For both setting and getting, None is equivalent to an unset value if no propname is given, this just sets the FT property, which tells if a dimension is frequency or time domain

get_plot_color()

get_prop(propname=None)

return arbitrary ND-data properties (typically acquisition parameters etc.) by name (propname)

In order to allow ND-data to store acquisition parameters and other info that accompanies the data, but might not be structured in a gridded format, nddata instances always have a other_info dictionary attribute, which stores these properties by name.

If the property doesn’t exist, this returns None.

Parameters:propname (str) –

Name of the property that you’re want returned. If this is left out or set to “None” (not given), the names of the available properties are returned. If no exact match is found, and propname contains a . or * or [, it’s assumed to be a regular expression. If several such matches are found, the error message is informative.

Todo

have it recursively search dictionaries (e.g. bruker acq)

Returns: Return type:The value of the property (can by any type) or None if the property doesn’t exist.

get_units(*args)

getaxis(axisname)

getaxisshape(axisname)

gnuplot_save(filename)

hdf5_write(h5path, directory='.')

Write the nddata to an HDF5 file.

h5path is the name of the file followed by the node path where you want to put it – it does not include the directory where the file lives. The directory can be passed to the directory argument.

You can use either find_file() or nddata_hdf5() to read the data, as shown below. When reading this, please note that HDF5 files store multiple datasets, and each is named (here, the name is test_data).

from pyspecdata import *
init_logging('debug')
a = nddata(r_[0:5:10j], 'x')
a.name('test_data')
try:
    a.hdf5_write('example.h5',getDATADIR(exp_type='Sam'))
except:
    print("file already exists, not creating again -- delete the file or node if wanted")
# read the file by the "raw method"
b = nddata_hdf5('example.h5/test_data',
        getDATADIR(exp_type='Sam'))
print("found data:",b)
# or use the find file method
c = find_file('example.h5', exp_type='Sam',
        expno='test_data')
print("found data:",c)

Parameters:

• h5path (str) – The name of the file followed by the node path where you want to put it – it does not include the directory where the file lives. (Because HDF5 files contain an internal directory-like group structure.)
• directory (str) – the directory where the HDF5 file lives.

histogram(**kwargs)

human_units()

ift(axes, n=False, tolerance=1e-05, verbose=False, **kwargs)

This performs an inverse Fourier transform along the axes identified by the string or list of strings axes.

It adjusts normalization and units so that the result conforms to

\(s(t)=t_{dw} \int_{x_{min}}^{x_{max}} \tilde{s}(f) e^{i 2 \pi f t} df\)

Where \(t_{dw}=\frac{1}{\Delta f}\), is the dwell time (with \(\Delta f\) the spectral width).

Why do we do this? Note that while the analytical integral this corresponds to is normalized, performing ft() followed by ift() on a discrete sequence is NOT completely invertible (due to integration of the implied comb function??), and would require division by a factor of \(\Delta f\) (the spectral width) in order to retrieve the original function

pre-IFT, we use the axis to cyclically permute \(f=0\) to the first index

post-IFT, we assume that the data has previously been FT’d If this is the case, passing shift=True will cause an error If this is not the case, passing shift=True generates a standard ifftshift shift=None will choose True, if and only if this is not the case

Parameters:pad (int or boolean) –

pad specifies a zero-filling. If it’s a number, then it gives the length of the zero-filled dimension. If it is just True, then the size of the dimension is determined by rounding the dimension size up to the nearest integral power of 2. It uses the start_time ft property to determine the start of the axis. To do this, it assumes that it is a stationary signal (convolved with infinite comb function). The value of start_time can differ from by a non-integral multiple of \(\Delta t\), though the routine will check whether or not it is safe to do this.

..note ::

In the code, this is controlled by p2_post (the integral \(\Delta t\) and p2_post_discrepancy – the non-integral.

imag

Return the imag component of the data

indices(axis_name, values)

Return a string of indeces that most closely match the axis labels corresponding to values. Filter them to make sure they are unique.

inhomog_coords(direct_dim, indirect_dim, tolerance=1e-05, method='linear', plot_name=None, fl=None, debug_kwargs={})

Apply the “inhomogeneity transform,” which rotates the data by \(45^{\circ}\), and then mirrors the portion with \(t_2<0\) in order to transform from a \((t_1,t_2)\) coordinate system to a \((t_{inh},t_{homog})\) coordinate system.

Parameters:

• direct_dim (str) – Label of the direct dimension (typically \(t_2\))
• indirect_dim (str) – Label of the indirect dimension (typically \(t_1\))
• method ('linear', 'fourier') – The interpolation method used to rotate the data and to mirror the data. Note currently, both use a fourier-based mirroring method.
• plot_name (str) – the base name for the plots that are generated
• fl (figlist_var) –
• debug_kwargs (dict) –

  with keys:

  correct_overlap:  if False, doesn’t correct for the overlap error that occurs during mirroring

integrate(thisaxis, backwards=False, cumulative=False)

Performs an integration – which is similar to a sum, except that it takes the axis into account, i.e., it performs: \(\int f(x) dx\) rather than \(\sum_i f(x_i)\)

Gaussian quadrature, etc, is planned for a future version.

Parameters:

• thisaxis – The dimension that you want to integrate along
• cumulative (boolean (default False)) – Perform a cumulative integral (analogous to a cumulative sum) – e.g. for ESR.
• backwards (boolean (default False)) – for cumulative integration – perform the integration backwards

interp(axis, axisvalues, past_bounds=None, return_func=False, **kwargs)

interpolate data values given axis values

Parameters:return_func (boolean) – defaults to False. If True, it returns a function that accepts axis values and returns a data value.

invinterp(axis, values, **kwargs)

interpolate axis values given data values

item()

like numpy item – returns a number when zero-dimensional

labels(*args)

label the dimensions, given in listofstrings with the axis labels given in listofaxes – listofaxes must be a numpy array; you can pass either a dictionary or a axis name (string)/axis label (numpy array) pair

like(value)

provide “zeros_like” and “ones_like” functionality

Parameters:value (float) – 1 is “ones_like” 0 is “zeros_like”, etc.

linear_shear(along_axis, propto_axis, shear_amnt, zero_fill=True)

the linear shear – see self.shear for documentation

matchdims(other)

add any dimensions to self that are not present in other

matrices_3d(also1d=False, invert=False, max_dimsize=1024, downsample_self=False)

returns X,Y,Z,x_axis,y_axis matrices X,Y,Z, are suitable for a variety of mesh plotting, etc, routines x_axis and y_axis are the x and y axes

max()

mayavi_surf()

use the mayavi surf function, assuming that we’ve already loaded mlab during initialization

mean(*args, **kwargs)

Take the mean and (optionally) set the error to the standard deviation

Parameters:std (bool) – whether or not to return the standard deviation as an error

mean_all_but(listofdims)

take the mean over all dimensions not in the list

mean_nopop(axis)

mean_weighted(axisname)

perform the weighted mean along axisname (use $sigma$ from $sigma = $self.get_error() do generate $1/sigma$ weights) for now, it clears the error of self, though it would be easy to calculate the new error, since everything is linear

unlike other functions, this creates working objects that are themselves nddata objects this strategy is easier than coding out the raw numpy math, but probably less efficient

meshplot(stride=None, alpha=1.0, onlycolor=False, light=None, rotation=None, cmap=<matplotlib.colors.LinearSegmentedColormap object>, ax=None, invert=False, **kwargs)

takes both rotation and light as elevation, azimuth only use the light kwarg to generate a black and white shading display

min()

mkd(*arg, **kwargs)

make dictionary format

multimin(minfunc, axisname, filterwidth, numberofmins)

name(*arg)

args: .name(newname) –> Name the object (for storage, etc) .name() –> Return the name

nnls(dimname, newaxis_dict, kernel_func, l=0)

Perform regularized non-negative least-squares “fit” on self.

Capable of solving for solution in 1 or 2 dimensions.

We seek to minimize \(Q = \| Ax - b \|_2 + \|\lambda x\|_2\) in order to obtain solution vector \(x\) subject to non-negativity constraint given input matrix \(A\), the kernel, and input vector \(b\), the data.

The first term assesses agreement between the fit \(Ax\) and the data \(b\), and the second term accounts for noise with the regularization parameter \(\lambda\) according to Tikhonov regularization.

To perform regularized minimization in 2 dimensions, set l to :str:`BRD` and provide a tuple of parameters :str:`dimname`, :nddata:`newaxis_dict`, and :function:`kernel_func`. Algorithm described in Venkataramanan et al. 2002 is performed which determines optimal \(\lambda\) for the data (DOI:10.1109/78.995059).

See: Wikipedia page on NNLS, Wikipedia page on Tikhonov regularization

Parameters:

• dimname (str) – Name of the “data” dimension that is to be replaced by a distribution (the “fit” dimension); e.g. if you are regularizing a set of functions \(\exp(-\tau*R_1)\), then this is \(\tau\)
• newaxis_dict (dict or nddata) – a dictionary whose key is the name of the “fit” dimension (\(R_1\) in the example above) and whose value is an array with the new axis labels. OR this can be a 1D nddata – if it has an axis, the axis will be used to create the fit axis; if it has no axis, the data will be used
• kernel_func (function) – a function giving the kernel for the regularization. The first argument is the “data” variable and the second argument is the “fit” variable (in the example above, this would be something like lambda x,y: exp(-x*y))
• l (double (default 0) or str) – the regularization parameter \(lambda\) – if this is set to 0, the algorithm reverts to standard nnls. If this is set to :str:`BRD`, then algorithm expects tuple of each parameter described above in order to perform a 2-dimensional fit.

Returns:

The regularized result. For future use, both the kernel (as an nddata, in a property called “nnls_kernel”) and the residual (as an nddata, in a property called “nnls_residual”) are stored as properties of the nddata. The regularized dimension is always last (innermost). If :str:`BRD` is specified, then the individual, uncompressed kernels \(K_{1}\) and \(K_{2}\) are returned as properties of the nddata “K1” and “K2” respectively. The number of singular values used to compressed each kernel is returned in properties of the nddata called, respectively, “s1” and “s2”.

Return type:

self

normalize(axis, first_figure=None)

oldtimey(alpha=0.5, ax=None, linewidth=None, sclinewidth=20.0, light=True, rotation=None, invert=False, **kwargs)

plot_labels(labels, fmt=None, **kwargs_passed)

this only works for one axis now

polyfit(axis, order=1, force_y_intercept=None)

polynomial fitting routine – return the coefficients and the fit ..note:

later, should probably branch this off as a new type of fit class

..warning:

for some reason, this version doesn’t use orthogonal polynomials, as the numpy routine does – we had diagnosed and determined that that creates noticeably different results, so fix that here.

Parameters:

• axis (str) – name of the axis that you want to fit along (not sure if this is currently tested for multi-dimensional data, but the idea should be that multiple fits would be returned.)
• order (int) – the order of the polynomial to be fit
• force_y_intercept (double or None) – force the y intercept to a particular value (e.g. 0)

Returns:

• c (ndarray) – a standard numpy array containing the coefficients (in ascending polynomial order)
• formult (nddata) – an nddata containing the result of the fit

popdim(dimname)

random_mask(axisname, threshold=None, inversion=False)

generate a random mask with about ‘threshold’ of the points thrown out

real

Return the real component of the data

register_axis(arg, nearest=None)

Interpolate the data so that the given axes are in register with a set of specified values. Does not change the spacing of the axis labels.

It finds the axis label position that is closest to the values given in arg, then interpolates (Fourier/sinc method) the data onto a new, slightly shifted, axis that passes exactly through the value given. To do this, it uses .ft_clear_startpoints() and uses .set_ft_prop() to override the “not aliased” flag.

Parameters:

• arg (dict (key,value = str,double)) – A list of the dimensions that you want to place in register, and the values you want them registered to.
• nearest (bool, optional) – Passed through to ft_clear_startpoints

rename(previous, new)

reorder(*axes, **kwargs)

Reorder the dimensions the first arguments are a list of dimensions

Parameters:

• *axes (str) – Accept any number of arguments that gives the dimensions, in the order that you want thee.
• first (bool) – (default True) Put this list of dimensions first, while False puts them last (where they then come in the order given).

replicate_units(other)

repwlabels(axis)

retaxis(axisname)

run(*args)

run a standard numpy function on the nddata:

d.run(func,'axisname') will run function func (e.g. a lambda function) along axis named ‘axisname’

d.run(func) will run function func on the data

in general: if the result of func reduces a dimension size to 1, the ‘axisname’ dimension will be “popped” (it will not exist in the result) – if this is not what you want, use run_nopop

run_avg(thisaxisname, decimation=20, centered=False)

a simple running average

run_nopop(func, axis)

runcopy(*args)

secsy_transform(direct_dim, indirect_dim, has_indirect=True, method='fourier', truncate=True)

Shift the time-domain data backwards by the echo time.

As opposed to secsy_transform_manual, this calls on on skew, rather than directly manipulating the phase of the function, which can lead to aliasing.

Parameters:

• has_indirect (bool) –

  (This option is largely specific to data loaded by acert_hdf5)

  Does the data actually have an indirect dimension? If not, assume that there is a constant echo time, that can be retrieved with .get_prop('te').

• truncate (bool) – If this is set, register_axis <pyspecdata.axis_manipulation.register_axis> to \(t_{direct}=0\), and then throw out the data for which \(t_{direct}<0\).
• method (str) – The shear method (linear or fourier).

secsy_transform_manual(direct_dim, indirect_dim, has_indirect=True, truncate=False)

Shift the time-domain data backwards by the echo time. As opposed to secsy_transform, this directlly manipulates the phase of the function, rather than calling on skew.

Parameters:

• has_indirect (bool) –

  (This option is largely specific to data loaded by acert_hdf5)

  Does the data actually have an indirect dimension? If not, assume that there is a constant echo time, that can be retrieved with .get_prop('te').

• truncate (bool) – If this is set, register_axis <pyspecdata.axis_manipulation.register_axis> to \(t_{direct}=0\), and then throw out the data for which \(t_{direct}<0\).

set_error(*args)

set the errors: either

set_error(‘axisname’,error_for_axis) or set_error(error_for_data)

error_for_data can be a scalar, in which case, all the data errors are set to error_for_data

Todo

several options below – enumerate them in the documentation

set_ft_prop(axis, propname=None, value=True)

Sets the FT property given by propname. For both setting and getting, None is equivalent to an unset value if propname is a boolean, and value is True (the default), it’s assumed that propname is actually None, and that value is set to the propname argument (this allows us to set the FT property more easily)

set_plot_color(thiscolor)

set_prop(*args)

set a ‘property’ of the nddata This is where you can put all unstructured information (e.g. experimental parameters, etc)

set_to(otherinst)

Set data inside the current instance to that of the other instance.

Goes through the list of attributes specified in copy, and assigns them to the element of the current instance.

This is to be used:

• for constructing classes that inherit nddata with additional methods.
• for overwriting the current data with the result of a slicing operation

set_units(*args)

setaxis(*args)

set or alter the value of the coordinate axis

Can be used in one of several ways:

• self.setaxis('axisname', values): just sets the values

• self.setaxis('axisname', '#'): just

  number the axis in numerically increasing order (e.g. if you have smooshed it from a couple other dimensions.)

• self.fromaxis('axisname',inputfunc): take the existing function, apply inputfunc, and replace
• self.fromaxis(inputsymbolic): Evaluate inputsymbolic and load the result into the axes, appropriately

shear(along_axis, propto_axis, shear_amnt, zero_fill=True, start_in_conj=False, method='linear')

Shear the data \(s\):

\(s(x',y,z) = s(x+ay,y,z)\)

where \(x\) is the altered_axis and \(y\) is the propto_axis. (Actually typically 2D, but \(z\) included just to illustrate other dimensions that aren’t involved)

Parameters:

• method ({'fourier','linear'}) –

  fourier

  Use the Fourier shift theorem (i.e., sinc interpolation). A shear is equivalent to the following in the conjugate domain:

  ..math: tilde{s}(f_x,f’_y,z) = tilde{s}(f_x,f_y-af_x,f_z)

  Because of this, the algorithm also automatically extend`s the data in `f_y axis. Equivalently, it increases the resolution (decreases the interval between points) in the propto_axis dimension. This prevents aliasing in the conjugate domain, which will corrupt the data w.r.t. successive transformations. It does this whether or not zero_fill is set (zero_fill only controls filling in the “current” dimension)

  linear

  Use simple linear interpolation.

• altered_axis (str) – The coordinate for which data is altered, i.e. ..math: x such that ..math: f(x+ay,y).
• by_amount (double) – The amount of the shear (..math: a in the previous)
• propto_axis (str) – The shift along the altered_axis dimension is proportional to the shift along propto_axis. The position of data relative to the propto_axis is not changed. Note that by the shift theorem, in the frequency domain, an equivalent magnitude, opposite sign, shear is applied with the propto_axis and altered_axis dimensions flipped.
• start_in_conj ({False, True}, optional) –

  Defaults to False

  For efficiency, one can replace a double (I)FT call followed by a shear call with a single shear call where start_in_conj is set.

  self before the call is given in the conjugate domain (i.e., \(f\) vs. \(t\)) along both dimensions from the one that’s desired. This means: (1) self after the function call transformed into the conjugate domain from that before the call and (2) by_amount, altered_axis, and propto_axis all refer to the shear in the conjugate domain that the data is in at the end of the function call.

smoosh(dimstocollapse, dimname=0, noaxis=False)

Collapse (smoosh) multiple dimensions into one dimension.

Parameters:

• dimstocollapse (list of strings) – the dimensions you want to collapse to one result dimension
• dimname (None, string, integer (default 0)) –

  if dimname is:

  • None: create a new (direct product) name,
  • a number: an index to the dimstocollapse list. The resulting smooshed dimension will be named dimstocollapse[dimname]. Because the default is the number 0, the new dimname will be the first dimname given in the list.
  • a string: the name of the resulting smooshed dimension (can be part of the dimstocollapse list or not)
• noaxis (bool) – if set, then just skip calculating the axis for the new dimension, which otherwise is typically a complicated record array

Returns:

• self (nddata) – the dimensions dimstocollapse are smooshed into a single dimension, whose name is determined by dimname. The axis for the resulting, smooshed dimension is a structured array consisting of two fields that give the labels along the original axes.
• ..todo:: – when we transition to axes that are stored using a slice/linspace-like format, allow for smooshing to determine a new axes that is standard (not a structured array) and that increases linearly.

sort(axisname, reverse=False)

sort_and_xy()

squeeze(return_dropped=False)

squeeze singleton dimensions

Parameters:return_dropped (bool (default False)) – return a list of the dimensions that were dropped as a second argument Returns:

• self
• return_dropped (list) – (optional, only if return_dropped is True)

sum(axes)

sum_nopop(axes)

to_ppm()

Function that converts from Hz to ppm using Bruker parameters

Todo

Figure out what the units of PHC1 in Topspin are (degrees per what??), and apply those as well.

make this part of an inherited bruker class

unitify_axis(axis_name, is_axis=True)

this just generates an axis label with appropriate units

units_texsafe(*args)

unset_prop(arg)

remove a ‘property’

want_to_prospa_decim_correct = False

waterfall(alpha=0.3, ax=None, rotation=None, color='b', edgecolor='k')

class pyspecdata.core.nddata_hdf5(pathstring, directory='.')

Bases: pyspecdata.core.nddata

pyspecdata.core.ndgrid(*input)

class pyspecdata.core.ndshape(*args)

Bases: pyspecdata.ndshape.ndshape_base

The ndshape class, including the allocation method

alloc(dtype='complex128', labels=False, format=0)

Use the shape object to allocate an empty nddata object.

Parameters:

• labels – Needs documentation
• format (0, 1, or None) – What goes in the allocated array. None uses numpy empty.

pyspecdata.core.newcol_rec(A, new_dtypes)

add new, empty (i.e. random numbers) fields to A, as given by new_dtypes –> note that there are deeply nested numpy functions to do this, but the options are confusing, and I think the way these work is efficient

pyspecdata.core.nextfigure(figurelist, name)

obsolete – now use class

pyspecdata.core.normal_attrs(obj)

pyspecdata.core.obs(*x)

pyspecdata.core.obsn(*x)

pyspecdata.core.othergridandtick(ax, rotation=(0, 0), precision=(2, 2), labelstring=('', ''), gridcolor=None, y=True, x=True, spines=None)

pyspecdata.core.pinvr(C, alpha)

pyspecdata.core.plot(*args, **kwargs)

The base plotting function that wraps around matplotlib to do a couple convenient things.

Parameters:

• label_format_string (str) – If supplied, it formats the values of the other dimension to turn them into a label string.
• human_units (bool) –

pyspecdata.core.plot_color_counter(*args, **kwargs)

Try not to use this function any more – the version-to-version support for capturing and setting color cycles in matplotlib is very very bad. (And, the cycler object in newer versions of matplolib is confusing.) So, just import cycle from itertools, and use it to build a cycle that you directly call to set your properties.

Note

previous description:

if passed an argument: make it so that the next line will have the properties given by the argument

if not passed an argument: just return the current plot properties,so that I can cycle back to it

pyspecdata.core.plot_label_points(x, y, labels, **kwargs_passed)

pyspecdata.core.plot_updown(data, axis, color1, color2, symbol='', **kwargs)

pyspecdata.core.reorder_rec(myarray, listofnames, first=True)

pyspecdata.core.sech(x)

pyspecdata.core.showtype(x)

pyspecdata.core.spectrogram(waveform, f_start, f_stop, npoints_fdom=40, tdom_div=2)

pyspecdata.core.sqrt(arg)

class pyspecdata.core.subplot_dim(firstdim, seconddim)

Bases: object

set(args, x='', g=True, y='', t='', a='')

class pyspecdata.core.testclass

Bases: object

pyspecdata.core.text_on_plot(x, y, thistext, coord='axes', **kwargs)

pyspecdata.core.textlabel_bargraph(mystructarray, othersort=None, spacing=0.1, ax=None, tickfontsize=8)

pyspecdata.core.unmake_ndarray(array_to_conv, name_forprint='unknown')

Convert this item to an ndarray

pyspecdata.core.whereblocks(a)

returns contiguous chunks where the condition is true but, see the “contiguous” method, which is more OO

pyspecdata.datadir module

Allows the user to run the same code on different machines, even though the location of the raw spectral data might change.

This is controlled by the ~/.pyspecdata or ~/_pyspecdata config file.

class pyspecdata.datadir.MyConfig

Bases: object

Provides an easy interface to the pyspecdata configuration file. Only one instance _my_config should be created – this instance is used by the other functions in this module.

config_vars = None

The dictionary that stores the current settings – keep these in a dictionary, which should be faster than reading from environ, or from a file.

get_setting(this_key, environ=None, default=None, section='General')

Get a settings from the “General” group. If the file does not exist, or the option is not set, then set the option, creating the file as needed. The option is determined in the following order:

• The value in the config_vars dictionary.
• The value of the environment variable named environ.
• The value stored in the configuration file at ~/.pyspecdata (~/_pyspecdata on Windows).
• The value given by the default argument. If default is None, then return None.

Parameters:

• this_key (str) – The name of the settings that we want to retrieve.
• environ (str) – If the value corresponding to this_key is not present in the self.config_vars dictionary, look for an environment variable called environ that stores the value of this_key. If this is not set, it’s set from the config file or the default argument.
• default (str) –

  If the value for this_key is not in self.config_vars, not in the environment variable called environ, and not in the config file, set it to this value, and ask for user response to confirm. Then, set the config file value, the environment, and the self.config_vars value to the result.

  For platform compatibility, leading period characters are converted to self.hide_start, and ‘/’ are converted to os.path.sep.

• section (str) – Look in this section of the config file.

Returns:

Return type:

The value corresponding to this_key.

hide_start = None

This filename prefix denotes a configuration file on the OS.

set_setting(this_section, this_key, this_value)

set this_key to this_value inside section this_section, creating it if necessary

pyspecdata.datadir.dirformat(file)

pyspecdata.datadir.getDATADIR(*args, **kwargs)

Used to find a directory containing data in a way that works seamlessly across different computers (and operating systems). Supports the case where data is processed both on a laboratory computer and (e.g. after transferring via ssh or a syncing client) on a user’s laptop. While it will return a default directory without any arguments, it is typically used with the keyword argument exp_type, described below.

Note that the most common way to use this mechanism is to set up your directories using the pyspecdata_register_dir shell command – see register_directory().

It returns the directory ending in a trailing (back)slash.

It is determined by a call to MyConfig.get_setting with the setting name data_directory and the environment variable set to PYTHON_DATA_DIR.

Parameters:exp_type (str) –

A string identifying the name of a subdirectory where the data is stored. It can contain slashes. Typically, this gives the path relative to a google drive, rclone, dropbox, etc, repository. To make code portable, exp_type should not contain a full path or or portions of the path that are specific to the computer/user.

If the directory has note been used before, all the directories listed in the user’s _pyspecdata or .pyspecdata config file will be searched recursively up to 2 levels deep.

It searches for exp_type in this order:

• Look in the ExpTypes section of the config file.

  • Note that by using this, you can store data in locations other

    than your main data directory. For example, consider the following section of the ~/.pyspecdata config file: ` [ExpTypes] alternate_base = /opt/other_data alternate_type_one = %(alternate_base)s/type_one ` which would find data with exp_type alternate_type_one in /opt/other_data/type_one.

• use os.walk to search for a directory with this name

  inside the directory identified by experimental_data. excluding things that start with ‘.’, ‘_’ or containing ‘.hfssresults’, always choosing the thing that’s highest up in the tree. If it doesn’t find a directory inside experimental_data, it will search inside all the directories already listed in ExpTypes. Currently, in both attempts, it will only walk 2 levels deep (since NMR directories can be rather complex, and otherwise it would take forever).

pyspecdata.datadir.get_notebook_dir(*args)

Returns the notebook directory. If arguments are passed, it returns the directory underneath the notebook directory, ending in a trailing (back)slash

It is determined by a call to MyConfig.get_setting with the environment variable set to PYTHON_NOTEBOOK_DIR and default ~/notebook.

pyspecdata.datadir.grab_data_directory()

pyspecdata.datadir.log_fname(logname, fname, dirname, err=False)

logs the file name either used or missing.

Also, by setting the err flag to True, you can generate an error message that will guide you on how to selectively copy down this data from a remote source (google drive, etc.), e.g.:

``Traceback (most recent call last):

File “proc_square_refl.py”, line 21, in <module>

directory=getDATADIR(exp_type=’test_equip’))

File “c:usersjohnfnotebookpyspecdatapyspecdatacore.py”, line 6630, in __init__

check_only=True, directory=directory)

File “c:usersjohnfnotebookpyspecdatapyspecdatacore.py”, line 1041, in h5nodebypath

+errmsg)

AttributeError: You’re checking for a node in a file (200110_pulse_2.h5) that does not exist I can’t find 200110_pulse_2.h5 in C:Usersjohnfexp_datatest_equip, so I’m going to search for t in your rclone remotes checking remote g_syr: You should be able to retrieve this file with: rclone copy -v –include ‘200110_pulse_2.h5’ g_syr:exp_data/test_equip C:\Users\johnf\exp_data\test_equip``

pyspecdata.datadir.rclone_search(fname, dirname)

pyspecdata.datadir.register_directory()

The shell command pyspecdata_register_dir WHICHDIR will register the directory WHICHDIR (substitute with the name of a directory on your computer) so that it can be automatically discovered by find_file() or search_filename() after executing this shell command you can use the exp_type argument of those commands where you only give the lowest level subdirectory (or the final couple subdirectories) that contains your data.

Key to the way this mechanism works

Note

this feature was installed on 9/24/20: you need to re-run setup.py in order to get this command to work for the first time if you installed pyspecdata before that date.

pyspecdata.figlist module

Contains the figure list class

The figure list gives us three things:

• Automatically handle the display and scaling of nddata units.

• Refer to plots by name, rather than number (matplotlib has a mechanism for this, which we ignore)

• A “basename” allowing us to generate multiple sets of plots for different datasets – e.g. 5 plots with 5 names plotted for 3 different datasets and labeled by 3 different basenames to give 15 plots total

• Ability to run the same code from the command line or from within a python environment inside latex. * this is achieved by choosing figlist (default gui) and figlistl (inherits

  from figlist – renders to latex – the figlist.show() method is changed)

  • potential planned future ability to handle html

• Ability to handle mayavi plots and matplotlib plots (switch to glumpy, etc.?) * potential planned future ability to handle gnuplot

Todo

Currently the “items” that the list tracks correspond to either plot formatting directives (see figlist.setprops()), text, or figures.

We should scrap most elements of the current implementation of figlist and rebuild it

• currently the figlist is set up to use a context block. We will not only keep this, but also make it so the individual axes. Syntax (following a fl = figlist_var() should look like this: with fl['my plot name'] as p: and contents of the block would then be p.plot(...), etc.

• define an “organization” function of the figlist block. This allows us to use standard matplotlib commands to set up and organize the axes, using standard matplotlib commands (twinx, subplot, etc.)

• figlist will still have a “next” function, but its purpose will be to simply: * grab the current axis using matplotlib gca() (assuming the id of the axis isn’t yet assigned to an existing figlist_axis – see below) * otherwise, if the name argument to “next” has not yet been called,

  call matplotlib’s figure(), followed by subplot(111), then do the previous bullet point

  • the next function is only intended to be called explicitly from within the organization function

• figlist will consist simply of a list of figlist_axis objects (a new object type), which have the following attributes: * type – indicating the type of object:

  • axis (default)
  • text (raw latex (or html))
  • H1 (first level header – translates to latex section)
  • H2 (second level…)

  • the name of the plot

  • a matplotlib or mayavi axes object

  • the units associated with the axes

  • a collection.OrderedDict giving the nddata that are associated with the plot, by name. * If these do not have a name, they will be automatically assigned a name. * The name should be used by the new “plot” method to generate

    the “label” for the legend, and can be subsequently used to quickly replace data – e.g. in a Qt application.

  • a dictionary giving any arguments to the pyspecdata.core.plot (or countour, waterfall, etc) function

  • the title – by default the name of the plot – can be a setter

  • the result of the id(…) function, called on the axes object –> this can be used to determine if the axes has been used yet

  • do not use check_units – the plot method (or contour, waterfall, etc.) will only add the nddata objects to the OrderedDict, add the arguments to the argument dictionary, then exit * In the event that more than one plot method is called, the name of the underlying nddaata should be changed

  • a boolean legend_suppress attribute

  • a boolean legend_internal attribute (to place the legend internally, rather than outside the axis)

  • a show method that is called by the figlistl show method. This will determine the appropriate units and use them to determine the units and scale of the axes, and then go through and call pyspecdata.core.plot on each dataset (in matplotlib, this should be done with a formatting statement rather than by manipulating the axes themselves) and finally call autolegend, unless the legend is supressed

• The “plottype” (currently an argument to the plot function) should be an attribute of the axis object

class pyspecdata.figlist.figlist(*arg, **kwargs)

Bases: object

basename

A basename that can be changed to generate different sets of figures with different basenames. For example, this is useful if you are looping over different sets of data, and generating the same set of figures for each set of data (which would correspond to a basename).

Type:str

figurelist

A list of the figure names

Type:list

figdict

A dictionary containing the figurelist and the figure numbers or objects that they correspond to. Keys of this dictionary must be elements of figurelist.

Type:dict

propdict

Maintains various properties for each element in figurelist. Keys of this dictionary must be elements of figurelist.

Type:dict

adjust_spines(spines)

check_units(testdata, x_index, y_index, verbose=False)

generate_ticks(plotdata, axes, rescale, z_norm=None, y_rescale=1, text_scale=0.05, verbose=False, follow_surface=False, lensoffset=0.005, line_width=0.001, tube_radius=0.001, fine_grid=False)

generate 3d ticks and grid for mayavi

get_fig_number(name)

grid()

header(number_above, input_string)

image(A, **kwargs)

Called as fl.image() where fl is the figlist_var object

Note that this code just wraps the figlist properties, and the heavy lifting is done by the image( function. Together, the effect is as follows:

• check_units converts to human-readable units, and makes sure they match the units already used in the plot.

• if A has more than two dimensions, the final dimension in A.dimlabels is used as the column dimension, and a direct-product of all non-column dimensions (a Kronecker product, such that the innermost index comes the latest in the list A.dimlabels) is used as the row dimension. A white/black line is drawn after the innermost index used to create the direct product is finished iterating.

• If A consists of complex data, then an HSV plot (misnomer, actually an HV plot) is used: - convert to polar form: \(z=\rho \exp(i \phi)\) - \(\phi\) determines the color (Hue)

  • Color wheel is cyclical, like \(\exp(i \phi)\)
  • red is taken as \(\phi=0\), purely real and positive
  • green-blue is \(pi\) radians out of phase with red and therefore negative real

  • \(\rho\) determines the intensity (value) - Depending on whether or not black is set (either as a

    keyword argument, or fl.black, the background will be black with high \(\rho\) values “lit up” (intended for screen plotting) or the background will be white with the high \(\rho\) values “colored in” (intended for printing)

• If the data type (dtype) of the data in A is real (typically achieved by calling abs(A) or A.runcopy(real)), then A is plotted with a colormap and corresponding colorbar.

• If no title has been given, it’s set to the name of the current plot in the figurelist

A

Type:nddata or numpy array

x

If A is a numpy array, then this gives the values along the x axis (columns). Defaults to the size of the array. Not used if A is nddata.

Type:Optional[double] or Optional[scalar]

y

If A is a numpy array, then this gives the values along the y axis (columns). Defaults to the size of the array. Not used if A is nddata.

Type:Optional[double] or Optional[scalar]

x_first

Since it’s designed to represent matrices, an image plot by defaults is “transposed” relative to all other plots. If you want the first dimension on the x-axis (e.g., if you are plotting a contour plot on top of an image), then set x_first to True.

Type:boolean

spacing

Determines the size of the white/black line drawn Defaults to 1

Type:integer

ax

the Axis object where the plot should go.

Type:matplotlib Axes

all remaning

are passed through to matplotlib imshow

origin

upper and lower are passed to matplotlib. Flip is for 2D nmr, and flips the data manually.

Type:{‘upper’, ‘lower’, ‘flip’}

.. code-block:: python

from pyspecdata import * fl = figlist_var()

t = r_[-1:1:300j] x = nddata(t,[-1],[‘x’]).labels(‘x’,t) y = nddata(t,[-1],[‘y’]).labels(‘y’,t)

z = x**2 + 2*y**2 print “dimlabels of z:”,z.dimlabels

fl.next(‘image with contours’) fl.image(z,x_first = True) # x_first is needed to align # with the contour plot z.contour(colors = ‘w’,alpha = 0.75)

fl.next(‘simple plot’) # just to show that x is the same # here as well fl.plot(z[‘y’:(0,0.01)])

fl.show(‘compare_image_contour_150911.pdf’)

label_point(data, axis, value, thislabel, show_point=True, xscale=1, **new_kwargs)

only works for 1D data: assume you’ve passed a single-point nddata, and label it

xscale gives the unit scaling

..todo:

Improve the unit scaling, so that this would also work.

Allow it to include a format string that would use the value.

Parameters:show_point (bool) – Defaults to True. Actually generate a point (circle), vs. just the label.

marked_text(marker, input_text='', sep='\n')

Creates a named marker where we can place text. If marker has been used, goes back and places text there.

mesh(plotdata, Z_normalization=None, equal_scale=True, lensoffset=0.001, show_contours=False, grey_surf=False, **kwargs)

next(input_name, legend=False, boundaries=None, twinx=None, **kwargs)

Switch to the figure given by input_name, which is used not only as a string-based name for the figure, but also as a default title and as a base name for resulting figure files.

In the future, we actually want this to track the appropriate axis object!

Parameters:

• legend (bool) – If this is set, a legend is created outside the figure.
• twinx ({0,1}) –
  1:plots on an overlayed axis (the matplotlib twinx) whose y axis is labeled on the right when you set this for the first time, you can also set a color kwarg that controls the coloring of the right axis. 0:used to switch back to the left (default) axis
• boundaries – need to add description
• kwargs (dict) – Any other keyword arguments are passed to the matplotlib (mayavi) figure() function that’s used to switch (create) figures.

phaseplot_finalize()

Performs plot decorations that are typically desired for a manual phasing plot. This assumes that the y-axis is given in units of half-cycles ($pi$ radians).

plot(*args, **kwargs)

Parameters:

• linestyle ({':','--','.','etc.'}) – the style of the line
• plottype ({'semilogy','semilogx','loglog'}) – Select a logarithmic plotting style.
• nosemilog (True) – Typically, if you supply a log-spaced axis, a semilogx plot will be automatically selected. This overrides that behavior. Defaults to False.

pop_marker()

push_marker()

setprops(**kwargs)

show(*args, **kwargs)

show_prep()

text(mytext)

twinx(autopad=False, orig=False, color=None)

use_autolegend(value=None)

No argument sets to true if it’s not already set

pyspecdata.fornotebook module

This provides figlistl, the Latex figure list. Any other functions here are helper functions for the class. figlist is generally not chosen manually, but figlist_var will be assigned to figlistl when python code is embedded in a python environment inside latex.

pyspecdata.fornotebook.calcdistance(freq, optdistance)

pyspecdata.fornotebook.calcfield(elfreq, elratio=28.113, nmrelratio=1.5167)

pyspecdata.fornotebook.calcfielddata(freq, substance, spec='')

pyspecdata.fornotebook.clear_local(inputdata=[])

pyspecdata.fornotebook.cpmgs(exp, number, tau=None, alpha=None, alphaselect=None, first=False)

pyspecdata.fornotebook.cpmgseries(filename, plotlabel, tau=None, alpha=None, alphaselect=None)

pyspecdata.fornotebook.dict_to_txt(mydict, file='data.txt')

pyspecdata.fornotebook.dprint(*stuff)

pyspecdata.fornotebook.ernstangle(pulsetime=None, pulsetip=None, Tr=None, T1=None)

pyspecdata.fornotebook.esr_saturation(file, powerseries, smoothing=0.2, threshold=0.8, figname=None, hn23adjustment=1.0, show_avg=False)

pyspecdata.fornotebook.figlist

alias of pyspecdata.fornotebook.figlistl

pyspecdata.fornotebook.figlisterr(figurelist, *args, **kwargs)

class pyspecdata.fornotebook.figlistl(*args, **kwargs)

Bases: pyspecdata.core.figlist

obs(*args)

obsn(*args)

show(string, line_spacing=True, **kwargs)

latexify the series of figures, where “string” gives the base file name

Parameters:line_spacing (bool) – if false, suppress empty lines between output

pyspecdata.fornotebook.lplot(fname, width=0.33, figure=False, dpi=72, grid=False, alsosave=None, gensvg=False, print_string=None, centered=False, equal_aspect=False, autopad=True, bytextwidth=None, showbox=True, boundaries=True, genpng=False, mlab=False, fig=None, verbose=False)

used with python.sty instead of savefig

by default, if width is less than 1, it’s interpreted as bytextwidth = True (i.e. width given as a fraction of the linewidth) if it’s greater than, the width is interpreted in inches.

pyspecdata.fornotebook.lplotfigures(figurelist, string, **kwargs)

obsolete, use the class!

pyspecdata.fornotebook.lrecordarray(recordlist, columnformat=True, smoosh=True, multi=True, resizebox=False, showpipe=True, return_only=False, format='%0.3f', std_sf=2, scientific_notation=True)

generate latex representation of a structured array if set to True, resizebox will automatically scale down the table so it fits on the page (but it will also scale up a small table to fit the width of the page) resizebox can also be a fractional number, so that it is resized to a fraction of the page

pyspecdata.fornotebook.lrecordarray_broken(recordlist, rows=30, numwide=5)

pyspecdata.fornotebook.obs(*arg)

pyspecdata.fornotebook.obs_repr(*arg)

pyspecdata.fornotebook.obsn(*arg)

pyspecdata.fornotebook.ordplot(x, y, labels, formatstring)

pyspecdata.fornotebook.qcalc(freq1, freq2)

pyspecdata.fornotebook.save_data(inputdata={}, file='data.txt')

pyspecdata.fornotebook.save_local(inputdata={})

pyspecdata.fornotebook.save_variable(variable, content, disp=True, file='data.txt')

pyspecdata.fornotebook.see_if_math(recnames)

return latex formatted strings –> ultimately, have this actually check to see if the individual strings are math or not, rather than just assuming that they are. Do this simply by seeing whether or not the thing starts with a full word (more than two characters) or not.

pyspecdata.fornotebook.show_matrix(B, plot_name, first_figure=None)

pyspecdata.fornotebook.standard_noise_comparison(name, path='franck_cnsi/nmr/', data_subdir='reference_data', expnos=[3])

pyspecdata.fornotebook.thisjobname()

pyspecdata.fornotebook.txt_to_dict(file='data.txt')

pyspecdata.general_functions module

These are general functions that need to be accessible to everything inside pyspecdata.core. I can’t just put these inside pyspecdata.core, because that would lead to cyclic imports, and e.g. submodules of pyspecdata can’t find them.

pyspecdata.general_functions.autostringconvert(arg)

pyspecdata.general_functions.balance_clims()

works with matplotlib to generate a plot appropriate for positive and negative from here:

https://stackoverflow.com/questions/13060450/how-to-get-current-plots-clim-in-matplotlib

pyspecdata.general_functions.check_ascending_axis(u, tolerance=1e-07, additional_message=[], allow_descending=False)

Check that the array u is ascending and equally spaced, and return the spacing, du. This is a common check needed for FT functions, shears, etc.

Parameters:

• tolerance (double) – The relative variation in du that is allowed. Defaults to 1e-7.
• additional_message (str) – So that the user can easily figure out where the assertion error is coming from, supply some extra text for the respective message.

Returns:

du – the spacing between the elements of u

Return type:

double

pyspecdata.general_functions.complex_str(arg, fancy_format=False, format_code='%.4g')

render a complex string – leaving out imaginary if it’s real

pyspecdata.general_functions.exp(*args, **kwargs)

pyspecdata.general_functions.init_logging(level=10, stdout_level=20, filename='pyspecdata.log')

A decent logging setup to log to ~/pyspecdata.log (and ~/pyspecdata.XX.log if that’s taken).

By default, everything above “debug” is logged to a file, while everything above “info” is printed to stdout.

pyspecdata.general_functions.inside_sphinx()

pyspecdata.general_functions.level_str_to_int(level)

pyspecdata.general_functions.plot(*args, **kwargs)

pyspecdata.general_functions.process_kwargs(listoftuples, kwargs, pass_through=False, as_attr=False)

This function allows dynamically processed (i.e. function definitions with **kwargs) kwargs (keyword arguments) to be dealt with in a fashion more like standard kwargs. The defaults set in listoftuples are used to process kwargs, which are then returned as a set of values (that are set to defaults as needed).

Note that having kwargs as an explicit argument avoids errors where the user forgets to pass the kwargs.

Parameters:

• kwargs (**dictionary) – The keyword arguments that you want to process.
• listoftuples (list of tuple pairs) – Tuple pairs, consisting of ('param_name',param_value), that give the default values for the various parameters.
• pass_through (bool) – Defaults to False. If it’s true, then it’s OK not to process all the kwargs here. In that case, the used kwargs are popped out of the dictionary, and you are expected to pass the unprocessed values (in the dictionary after the call) on to subsequent processing. Importantly, you should always end with a pass_through`=`False call of this function, or by passing **kwargs to a standard function in the standard way. Otherwise it’s possible for the user to pass kwargs that are never processed!
• as_attr (bool, object) – Defaults to False. If not False, it must be an object whose attributes are set to the value of the respective kwargs.
• return (tuple) – It’s expected that the output is assigned to variables with the exact same names as the string in the first half of the tuples, in the exact same order. These parameters will then be set to the appropriate values.

pyspecdata.general_functions.rc(*args, **kwargs)

class pyspecdata.general_functions.rclass

Bases: object

pyspecdata.general_functions.redim_C_to_F(a)

see redim_F_to_C

pyspecdata.general_functions.redim_F_to_C(a)

the following creates a C array, reversing the apparent order of dimensions, while preserving the order in memory

pyspecdata.general_functions.reformat_exp(arg)

reformat scientific notation in a nice latex format – used in both pdf and jupyter notebooks

pyspecdata.general_functions.render_matrix(arg, format_code='%.4g')

return latex string representing 2D matrix

pyspecdata.general_functions.strm(*args)

pyspecdata.ipy module

pyspecdata.latexscripts module

Provides the pdflatex_notebook_wrapper shell/dos command, which you run instead of your normal Latex command to build a lab notebook. The results of python environments are cached and only re-run if the code changes, even if the python environments are moved around. This makes the compilation of a Latex lab notebook extremely efficient.

pyspecdata.latexscripts.cache_output_if_needed(scriptnum_as_str, hashstring, showcode=False, show_error=True)

if needed, run the python script numbered by scriptnum_as_str that hashes to hashstring, and output the result to the cache ONLY

pyspecdata.latexscripts.cached_filename(hashstring, returndir=False)

this sets the format for where the cached file is stored we use the first two characters as directory names (so there are just 16 of them

pyspecdata.latexscripts.check_image_path()

pyspecdata.latexscripts.det_new_pdf_name(thisargv)

based on an original tex or pdf name, determine the original basename (i.e., no extension), as well as one with the final word after the underscore removed

pyspecdata.latexscripts.flush_script(number)

pyspecdata.latexscripts.genconfig()

creates a template configuration directory

pyspecdata.latexscripts.get_scripts_dir()

pyspecdata.latexscripts.grab_script_string(scriptnum_as_str)

pyspecdata.latexscripts.main()

This looks for scripts/scriptsUsed.csv inside the notebook directory, and checks whether or not it should be run if a command line argument of “flush” is passed, it flushes that script number from the cache

pyspecdata.latexscripts.script_filename(scriptnum_as_str)

pyspecdata.latexscripts.sha_string(script)

convert the sha hash to a string

pyspecdata.latexscripts.wraplatex()

runs the python scripts after running latex also creates a copy of latex without the final portion under the underscore This prevents the viewer from hanging while it’s waiting for a refresh. This can be used in combination with wrapviewer() and latexmk by using a ~/.latexmkrc file that looks like this:

If you pass the --xelatex argument, xelatex is used instead of pdflatex (note that if you’re using latexmk, you need to add this in the latexmkrc file).

$pdflatex=q/pdflatex_notebook_wrapper %O -synctex=1 %S/;# calls this function
$pdf_previewer=q/pdflatex_notebook_view_wrapper/;# calls the wrapviewer function

pyspecdata.latexscripts.wrapviewer()

see wraplatex

pyspecdata.ndshape module

The ndshape class allows you to allocate arrays and determine the shape of existing arrays.

class pyspecdata.ndshape.ndshape_base(*args)

Bases: object

The base ndshape class, which doesn’t include an allocation method.

axn(axis)

return the number for the axis with the name “axis”

copy()

matchdims(arg)

returns shape with [not in self, len 1] + [overlapping dims between arg + self] + [not in arg] –> this is better accomplished by using sets as I do in the matchdims below

pop(label)

remove a dimension

rename(before, after)

rename a dimension

pyspecdata.nnls module

pyspecdata.nnls.nnls_regularized(A, b, l=0, maxiter=None)

Solve math:argmin_x || Ax - b ||_2^2 + lambda^2 ||x||_2^2 for x>=0. This is a wrapper for a FORTRAN non-negative least squares solver, with regularization (added by stacking $A$ on top an identity matrix times $lambda$ and $b$ on top of a matching array of zero.

Parameters:

• A (ndarray) – Matrix A as shown above.
• b (ndarray) – Right-hand side vector.
• l (double (default 0)) – \(lambda\) – if this is set to 0, the algorithm reverts to standard nnls (rather than stacking on top of two zero matrices for no reason)
• maxiter (int, optional) – Maximum number of iterations, optional. Default is 3 * A.shape[1].

Returns:

• x (ndarray) – Solution vector.
• rnorm (float) – The residual, || Ax-b ||_2.

Notes

The FORTRAN code was published in the book below. The algorithm is an active set method. It solves the KKT (Karush-Kuhn-Tucker) conditions for the non-negative least squares problem.

This was adapted from the source distributed with scipy – see scipy for relevant licensing.

References

Lawson C., Hanson R.J., (1987) Solving Least Squares Problems, SIAM

pyspecdata.units module

Not yet implemented – a preliminary idea for how to handle actual unit conversion. (Currently, we only do s to Hz during FT and order of magnitude prefixes when plotting.)

class pyspecdata.units.units(*args)

Bases: object

Each instance of this object stores a numerical representation of a single set of units, and there are routines to set units by (i.e. parsing) strings to units and routines to convert units to an str representation.

At its core, the units are represented by three numpy structured arrays per instance: one for the coefficients in terms of base units, one for the order of magnitude used to determine any prefixes added to the base units, and one for any scaling factors needed to convert to base units.

An array of these structured arrays can be converted into a row vector with .view((float16,len(base_dtype.names))). “Base Units” here are the same as SI base units except that it uses g instead of kg (so we can do the prefixes correctly), and we have added rad.

load_derived()

Parses and loads a series of definitions for derived units.

It uses definition list to determine a derived dtype vector, which is larger than the base dtype vector.

Then, (not yet done), based on the dictionary that this generates, it will generate a matrix that converts from the derived dtype vector to the base dtype vector.

parse(in_str, verbose=True)

Take in_str and parse it as a unit or series of units, and set the units associated with the current instance to the result.

Addition, subtraction, and parentheses are not allowed, and we define a non-standard order of operations, as follows:

1. \\mu (including a trailing space) and u are converted to the utf-8 equivalent (μ)
2. ...^-0.125 any number is assumed to be part of the exponent, and only numbers are allowed.
3. * multiplication
4. a space also represents multiplication
5. .../... comes after all other operations, as is typical for single-line text
6. sqrt(...) comes “last” in the sense that we take care of everything both inside and outside the sqrt first, before applying the sqrt.

At this point, I use split to break up according to the order of operations, assign powers to each, and determine the prefix. However, I’m currently only using base units, and I will eventually want to use derived units as well.

str(number, using_unicode=False)

Give a string that prints number, which has the units given by the current instance of the class. Choose the simplest possible expression for the units.

When printing, we have a matrix that give all our “representation” units, and we use a pseudoinverse to give us the simplest possible expression of our units. (This is assuming that all derived units are defined in terms of powers greater than or equal to 1 of the base units, because powers of magnitude less than 1 would complicate things by allowing us to reduce the norm by spreading across several derived units – in that case, we might want to add a threshold before taking the pinv.)

Currently, I am only giving a method for printing in the base units.

Also, I will want to use number in order to adjust the prefix(es) of the units.

pyspecdata.version module

Module contents

exception pyspecdata.CustomError(*value, **kwargs)

Bases: Exception

class pyspecdata.LightSource(azdeg=315, altdeg=45, hsv_min_val=0, hsv_max_val=1, hsv_min_sat=1, hsv_max_sat=0)

Bases: object

Create a light source coming from the specified azimuth and elevation. Angles are in degrees, with the azimuth measured clockwise from north and elevation up from the zero plane of the surface.

shade is used to produce “shaded” rgb values for a data array. shade_rgb can be used to combine an rgb image with an elevation map. hillshade produces an illumination map of a surface.

blend_hsv(rgb, intensity, hsv_max_sat=None, hsv_max_val=None, hsv_min_val=None, hsv_min_sat=None)

Take the input data array, convert to HSV values in the given colormap, then adjust those color values to give the impression of a shaded relief map with a specified light source. RGBA values are returned, which can then be used to plot the shaded image with imshow.

The color of the resulting image will be darkened by moving the (s, v) values (in hsv colorspace) toward (hsv_min_sat, hsv_min_val) in the shaded regions, or lightened by sliding (s, v) toward (hsv_max_sat, hsv_max_val) in regions that are illuminated. The default extremes are chose so that completely shaded points are nearly black (s = 1, v = 0) and completely illuminated points are nearly white (s = 0, v = 1).

Parameters:

• rgb (ndarray) – An MxNx3 RGB array of floats ranging from 0 to 1 (color image).
• intensity (ndarray) – An MxNx1 array of floats ranging from 0 to 1 (grayscale image).
• hsv_max_sat (number, default: 1) – The maximum saturation value that the intensity map can shift the output image to.
• hsv_min_sat (number, optional) – The minimum saturation value that the intensity map can shift the output image to. Defaults to 0.
• hsv_max_val (number, optional) – The maximum value (“v” in “hsv”) that the intensity map can shift the output image to. Defaults to 1.
• hsv_min_val (number, optional) – The minimum value (“v” in “hsv”) that the intensity map can shift the output image to. Defaults to 0.

Returns:

An MxNx3 RGB array representing the combined images.

Return type:

ndarray

blend_overlay(rgb, intensity)

Combines an rgb image with an intensity map using “overlay” blending.

Parameters:

• rgb (ndarray) – An MxNx3 RGB array of floats ranging from 0 to 1 (color image).
• intensity (ndarray) – An MxNx1 array of floats ranging from 0 to 1 (grayscale image).

Returns:

An MxNx3 RGB array representing the combined images.

Return type:

ndarray

blend_soft_light(rgb, intensity)

Combine an rgb image with an intensity map using “soft light” blending, using the “pegtop” formula.

Parameters:

• rgb (ndarray) – An MxNx3 RGB array of floats ranging from 0 to 1 (color image).
• intensity (ndarray) – An MxNx1 array of floats ranging from 0 to 1 (grayscale image).

Returns:

An MxNx3 RGB array representing the combined images.

Return type:

ndarray

direction

The unit vector direction towards the light source.

hillshade(elevation, vert_exag=1, dx=1, dy=1, fraction=1.0)

Calculate the illumination intensity for a surface using the defined azimuth and elevation for the light source.

This computes the normal vectors for the surface, and then passes them on to shade_normals

Parameters:

• elevation (array-like) – A 2d array (or equivalent) of the height values used to generate an illumination map
• vert_exag (number, optional) – The amount to exaggerate the elevation values by when calculating illumination. This can be used either to correct for differences in units between the x-y coordinate system and the elevation coordinate system (e.g. decimal degrees vs. meters) or to exaggerate or de-emphasize topographic effects.
• dx (number, optional) – The x-spacing (columns) of the input elevation grid.
• dy (number, optional) – The y-spacing (rows) of the input elevation grid.
• fraction (number, optional) – Increases or decreases the contrast of the hillshade. Values greater than one will cause intermediate values to move closer to full illumination or shadow (and clipping any values that move beyond 0 or 1). Note that this is not visually or mathematically the same as vertical exaggeration.

Returns:

A 2d array of illumination values between 0-1, where 0 is completely in shadow and 1 is completely illuminated.

Return type:

ndarray

shade(data, cmap, norm=None, blend_mode='overlay', vmin=None, vmax=None, vert_exag=1, dx=1, dy=1, fraction=1, **kwargs)

Combine colormapped data values with an illumination intensity map (a.k.a. “hillshade”) of the values.

Parameters:

• data (array-like) – A 2d array (or equivalent) of the height values used to generate a shaded map.
• cmap (~matplotlib.colors.Colormap) – The colormap used to color the data array. Note that this must be a ~matplotlib.colors.Colormap instance. For example, rather than passing in cmap='gist_earth', use cmap=plt.get_cmap('gist_earth') instead.
• norm (~matplotlib.colors.Normalize instance, optional) – The normalization used to scale values before colormapping. If None, the input will be linearly scaled between its min and max.
• blend_mode ({'hsv', 'overlay', 'soft'} or callable, optional) – The type of blending used to combine the colormapped data values with the illumination intensity. Default is “overlay”. Note that for most topographic surfaces, “overlay” or “soft” appear more visually realistic. If a user-defined function is supplied, it is expected to combine an MxNx3 RGB array of floats (ranging 0 to 1) with an MxNx1 hillshade array (also 0 to 1). (Call signature func(rgb, illum, **kwargs)) Additional kwargs supplied to this function will be passed on to the blend_mode function.
• vmin (float or None, optional) – The minimum value used in colormapping data. If None the minimum value in data is used. If norm is specified, then this argument will be ignored.
• vmax (float or None, optional) – The maximum value used in colormapping data. If None the maximum value in data is used. If norm is specified, then this argument will be ignored.
• vert_exag (number, optional) – The amount to exaggerate the elevation values by when calculating illumination. This can be used either to correct for differences in units between the x-y coordinate system and the elevation coordinate system (e.g. decimal degrees vs. meters) or to exaggerate or de-emphasize topography.
• dx (number, optional) – The x-spacing (columns) of the input elevation grid.
• dy (number, optional) – The y-spacing (rows) of the input elevation grid.
• fraction (number, optional) – Increases or decreases the contrast of the hillshade. Values greater than one will cause intermediate values to move closer to full illumination or shadow (and clipping any values that move beyond 0 or 1). Note that this is not visually or mathematically the same as vertical exaggeration.
• kwargs are passed on to the blend_mode function. (Additional) –

Returns:

An MxNx4 array of floats ranging between 0-1.

Return type:

ndarray

shade_normals(normals, fraction=1.0)

Calculate the illumination intensity for the normal vectors of a surface using the defined azimuth and elevation for the light source.

Imagine an artificial sun placed at infinity in some azimuth and elevation position illuminating our surface. The parts of the surface that slope toward the sun should brighten while those sides facing away should become darker.

Parameters:fraction (number, optional) – Increases or decreases the contrast of the hillshade. Values greater than one will cause intermediate values to move closer to full illumination or shadow (and clipping any values that move beyond 0 or 1). Note that this is not visually or mathematically the same as vertical exaggeration. Returns:A 2d array of illumination values between 0-1, where 0 is completely in shadow and 1 is completely illuminated. Return type:ndarray

shade_rgb(rgb, elevation, fraction=1.0, blend_mode='hsv', vert_exag=1, dx=1, dy=1, **kwargs)

Use this light source to adjust the colors of the rgb input array to give the impression of a shaded relief map with the given elevation.

Parameters:

• rgb (array-like) – An (M, N, 3) RGB array, assumed to be in the range of 0 to 1.
• elevation (array-like) – An (M, N) array of the height values used to generate a shaded map.
• fraction (number) – Increases or decreases the contrast of the hillshade. Values greater than one will cause intermediate values to move closer to full illumination or shadow (and clipping any values that move beyond 0 or 1). Note that this is not visually or mathematically the same as vertical exaggeration.
• blend_mode ({'hsv', 'overlay', 'soft'} or callable, optional) – The type of blending used to combine the colormapped data values with the illumination intensity. For backwards compatibility, this defaults to “hsv”. Note that for most topographic surfaces, “overlay” or “soft” appear more visually realistic. If a user-defined function is supplied, it is expected to combine an MxNx3 RGB array of floats (ranging 0 to 1) with an MxNx1 hillshade array (also 0 to 1). (Call signature func(rgb, illum, **kwargs)) Additional kwargs supplied to this function will be passed on to the blend_mode function.
• vert_exag (number, optional) – The amount to exaggerate the elevation values by when calculating illumination. This can be used either to correct for differences in units between the x-y coordinate system and the elevation coordinate system (e.g. decimal degrees vs. meters) or to exaggerate or de-emphasize topography.
• dx (number, optional) – The x-spacing (columns) of the input elevation grid.
• dy (number, optional) – The y-spacing (rows) of the input elevation grid.
• kwargs are passed on to the blend_mode function. (Additional) –

Returns:

An (m, n, 3) array of floats ranging between 0-1.

Return type:

ndarray

class pyspecdata.Line2D(xdata, ydata, linewidth=None, linestyle=None, color=None, marker=None, markersize=None, markeredgewidth=None, markeredgecolor=None, markerfacecolor=None, markerfacecoloralt='none', fillstyle=None, antialiased=None, dash_capstyle=None, solid_capstyle=None, dash_joinstyle=None, solid_joinstyle=None, pickradius=5, drawstyle=None, markevery=None, **kwargs)

Bases: matplotlib.artist.Artist

A line - the line can have both a solid linestyle connecting all the vertices, and a marker at each vertex. Additionally, the drawing of the solid line is influenced by the drawstyle, e.g., one can create “stepped” lines in various styles.

axes

The ~.axes.Axes instance the artist resides in, or None.

contains(mouseevent)

Test whether mouseevent occurred on the line.

An event is deemed to have occurred “on” the line if it is less than self.pickradius (default: 5 points) away from it. Use ~.Line2D.get_pickradius or ~.Line2D.set_pickradius to get or set the pick radius.

Parameters:mouseevent (matplotlib.backend_bases.MouseEvent) – Returns:

• contains (bool) – Whether any values are within the radius.
• details (dict) – A dictionary {'ind': pointlist}, where pointlist is a list of points of the line that are within the pickradius around the event position.

  TODO: sort returned indices by distance

draw(renderer)

Draw the Artist (and its children) using the given renderer.

This has no effect if the artist is not visible (.Artist.get_visible returns False).

Parameters:renderer (.RendererBase subclass.) –

Notes

This method is overridden in the Artist subclasses.

drawStyleKeys = ['default', 'steps-mid', 'steps-pre', 'steps-post', 'steps']

drawStyles = {'default': '_draw_lines', 'steps': '_draw_steps_pre', 'steps-mid': '_draw_steps_mid', 'steps-post': '_draw_steps_post', 'steps-pre': '_draw_steps_pre'}

fillStyles = ('full', 'left', 'right', 'bottom', 'top', 'none')

filled_markers = ('o', 'v', '^', '<', '>', '8', 's', 'p', '*', 'h', 'H', 'D', 'd', 'P', 'X')

get_aa()

Alias for get_antialiased.

get_antialiased()

Return whether antialiased rendering is used.

get_c()

Alias for get_color.

get_color()

Return the line color.

See also ~.Line2D.set_color.

get_dash_capstyle()

Return the cap style for dashed lines.

See also ~.Line2D.set_dash_capstyle.

get_dash_joinstyle()

Return the join style for dashed lines.

See also ~.Line2D.set_dash_joinstyle.

get_data(orig=True)

Return the xdata, ydata.

If orig is True, return the original data.

get_drawstyle()

Return the drawstyle.

See also ~.Line2D.set_drawstyle.

get_ds()

Alias for get_drawstyle.

get_fillstyle()

Return the marker fill style.

See also ~.Line2D.set_fillstyle.

get_linestyle()

Return the linestyle.

See also ~.Line2D.set_linestyle.

get_linewidth()

Return the linewidth in points.

See also ~.Line2D.set_linewidth.

get_ls()

Alias for get_linestyle.

get_lw()

Alias for get_linewidth.

get_marker()

Return the line marker.

See also ~.Line2D.set_marker.

get_markeredgecolor()

Return the marker edge color.

See also ~.Line2D.set_markeredgecolor.

get_markeredgewidth()

Return the marker edge width in points.

See also ~.Line2D.set_markeredgewidth.

get_markerfacecolor()

Return the marker face color.

See also ~.Line2D.set_markerfacecolor.

get_markerfacecoloralt()

Return the alternate marker face color.

See also ~.Line2D.set_markerfacecoloralt.

get_markersize()

Return the marker size in points.

See also ~.Line2D.set_markersize.

get_markevery()

Return the markevery setting for marker subsampling.

See also ~.Line2D.set_markevery.

get_mec()

Alias for get_markeredgecolor.

get_mew()

Alias for get_markeredgewidth.

get_mfc()

Alias for get_markerfacecolor.

get_mfcalt()

Alias for get_markerfacecoloralt.

get_ms()

Alias for get_markersize.

get_path()

Return the Path object associated with this line.

get_pickradius()

Return the pick radius used for containment tests.

See .contains for more details.

get_solid_capstyle()

Return the cap style for solid lines.

See also ~.Line2D.set_solid_capstyle.

get_solid_joinstyle()

Return the join style for solid lines.

See also ~.Line2D.set_solid_joinstyle.

get_window_extent(renderer)

Get the axes bounding box in display space.

The bounding box’ width and height are nonnegative.

Subclasses should override for inclusion in the bounding box “tight” calculation. Default is to return an empty bounding box at 0, 0.

Be careful when using this function, the results will not update if the artist window extent of the artist changes. The extent can change due to any changes in the transform stack, such as changing the axes limits, the figure size, or the canvas used (as is done when saving a figure). This can lead to unexpected behavior where interactive figures will look fine on the screen, but will save incorrectly.

get_xdata(orig=True)

Return the xdata.

If orig is True, return the original data, else the processed data.

get_xydata()

Return the xy data as a Nx2 numpy array.

get_ydata(orig=True)

Return the ydata.

If orig is True, return the original data, else the processed data.

is_dashed()

Return whether line has a dashed linestyle.

See also ~.Line2D.set_linestyle.

lineStyles = {'': '_draw_nothing', ' ': '_draw_nothing', '-': '_draw_solid', '--': '_draw_dashed', '-.': '_draw_dash_dot', ':': '_draw_dotted', 'None': '_draw_nothing'}

markers = {'.': 'point', ',': 'pixel', 'o': 'circle', 'v': 'triangle_down', '^': 'triangle_up', '<': 'triangle_left', '>': 'triangle_right', '1': 'tri_down', '2': 'tri_up', '3': 'tri_left', '4': 'tri_right', '8': 'octagon', 's': 'square', 'p': 'pentagon', '*': 'star', 'h': 'hexagon1', 'H': 'hexagon2', '+': 'plus', 'x': 'x', 'D': 'diamond', 'd': 'thin_diamond', '|': 'vline', '_': 'hline', 'P': 'plus_filled', 'X': 'x_filled', 0: 'tickleft', 1: 'tickright', 2: 'tickup', 3: 'tickdown', 4: 'caretleft', 5: 'caretright', 6: 'caretup', 7: 'caretdown', 8: 'caretleftbase', 9: 'caretrightbase', 10: 'caretupbase', 11: 'caretdownbase', 'None': 'nothing', None: 'nothing', ' ': 'nothing', '': 'nothing'}

pickradius

Return the pick radius used for containment tests.

See .contains for more details.

recache(always=False)

recache_always()

set_aa(b)

Alias for set_antialiased.

set_antialiased(b)

Set whether to use antialiased rendering.

Parameters:b (bool) –

set_c(color)

Alias for set_color.

set_color(color)

Set the color of the line.

Parameters:color (color) –

set_dash_capstyle(s)

Set the cap style for dashed lines.

Parameters:s ({'butt', 'round', 'projecting'}) – For examples see /gallery/lines_bars_and_markers/joinstyle.

set_dash_joinstyle(s)

Set the join style for dashed lines.

Parameters:s ({'miter', 'round', 'bevel'}) – For examples see /gallery/lines_bars_and_markers/joinstyle.

set_dashes(seq)

Set the dash sequence.

The dash sequence is a sequence of floats of even length describing the length of dashes and spaces in points.

For example, (5, 2, 1, 2) describes a sequence of 5 point and 1 point dashes separated by 2 point spaces.

Parameters:seq (sequence of floats (on/off ink in points) or (None, None)) – If seq is empty or (None, None), the linestyle will be set to solid.

set_data(*args)

Set the x and y data.

Parameters:*args ((2, N) array or two 1D arrays) –

set_drawstyle(drawstyle)

Set the drawstyle of the plot.

The drawstyle determines how the points are connected.

Parameters:drawstyle ({'default', 'steps', 'steps-pre', 'steps-mid', 'steps-post'}, default: 'default') –

For ‘default’, the points are connected with straight lines.

The steps variants connect the points with step-like lines, i.e. horizontal lines with vertical steps. They differ in the location of the step:

• ’steps-pre’: The step is at the beginning of the line segment, i.e. the line will be at the y-value of point to the right.
• ’steps-mid’: The step is halfway between the points.
• ’steps-post: The step is at the end of the line segment, i.e. the line will be at the y-value of the point to the left.
• ’steps’ is equal to ‘steps-pre’ and is maintained for backward-compatibility.

For examples see /gallery/lines_bars_and_markers/step_demo.

set_ds(drawstyle)

Alias for set_drawstyle.

set_fillstyle(fs)

Set the marker fill style.

Parameters:fs ({'full', 'left', 'right', 'bottom', 'top', 'none'}) –

Possible values:

• ’full’: Fill the whole marker with the markerfacecolor.
• ’left’, ‘right’, ‘bottom’, ‘top’: Fill the marker half at the given side with the markerfacecolor. The other half of the marker is filled with markerfacecoloralt.
• ’none’: No filling.

For examples see marker_fill_styles.

set_linestyle(ls)

Set the linestyle of the line.

Parameters:ls ({'-', '--', '-.', ':', '', (offset, on-off-seq), ..}) –

Possible values:

• A string:

  Linestyle	Description
  '-' or 'solid'	solid line
  '--' or 'dashed'	dashed line
  '-.' or 'dashdot'	dash-dotted line
  ':' or 'dotted'	dotted line
  'None' or ' ' or ''	draw nothing

• Alternatively a dash tuple of the following form can be provided:

  (offset, onoffseq)
  

  where onoffseq is an even length tuple of on and off ink in points. See also set_dashes().

For examples see /gallery/lines_bars_and_markers/linestyles.

set_linewidth(w)

Set the line width in points.

Parameters:w (float) – Line width, in points.

set_ls(ls)

Alias for set_linestyle.

set_lw(w)

Alias for set_linewidth.

set_marker(marker)

Set the line marker.

Parameters:marker (marker style string, ~.path.Path or ~.markers.MarkerStyle) – See ~matplotlib.markers for full description of possible arguments.

set_markeredgecolor(ec)

Set the marker edge color.

Parameters:ec (color) –

set_markeredgewidth(ew)

Set the marker edge width in points.

Parameters:ew (float) – Marker edge width, in points.

set_markerfacecolor(fc)

Set the marker face color.

Parameters:fc (color) –

set_markerfacecoloralt(fc)

Set the alternate marker face color.

Parameters:fc (color) –

set_markersize(sz)

Set the marker size in points.

Parameters:sz (float) – Marker size, in points.

set_markevery(every)

Set the markevery property to subsample the plot when using markers.

e.g., if every=5, every 5-th marker will be plotted.

Parameters:every (None or int or (int, int) or slice or List[int] or float or (float, float) or List[bool]) –

Which markers to plot.

• every=None, every point will be plotted.
• every=N, every N-th marker will be plotted starting with marker 0.
• every=(start, N), every N-th marker, starting at point start, will be plotted.
• every=slice(start, end, N), every N-th marker, starting at point start, up to but not including point end, will be plotted.
• every=[i, j, m, n], only markers at points i, j, m, and n will be plotted.
• every=[True, False, True], positions that are True will be plotted.
• every=0.1, (i.e. a float) then markers will be spaced at approximately equal distances along the line; the distance along the line between markers is determined by multiplying the display-coordinate distance of the axes bounding-box diagonal by the value of every.
• every=(0.5, 0.1) (i.e. a length-2 tuple of float), the same functionality as every=0.1 is exhibited but the first marker will be 0.5 multiplied by the display-coordinate-diagonal-distance along the line.

For examples see /gallery/lines_bars_and_markers/markevery_demo.

Notes

Setting the markevery property will only show markers at actual data points. When using float arguments to set the markevery property on irregularly spaced data, the markers will likely not appear evenly spaced because the actual data points do not coincide with the theoretical spacing between markers.

When using a start offset to specify the first marker, the offset will be from the first data point which may be different from the first the visible data point if the plot is zoomed in.

If zooming in on a plot when using float arguments then the actual data points that have markers will change because the distance between markers is always determined from the display-coordinates axes-bounding-box-diagonal regardless of the actual axes data limits.

set_mec(ec)

Alias for set_markeredgecolor.

set_mew(ew)

Alias for set_markeredgewidth.

set_mfc(fc)

Alias for set_markerfacecolor.

set_mfcalt(fc)

Alias for set_markerfacecoloralt.

set_ms(sz)

Alias for set_markersize.

set_picker(p)

Define the picking behavior of the artist.

Parameters:picker (None or bool or callable) –

This can be one of the following:

• None: Picking is disabled for this artist (default).
• A boolean: If True then picking will be enabled and the artist will fire a pick event if the mouse event is over the artist.
• A function: If picker is callable, it is a user supplied function which determines whether the artist is hit by the mouse event:

  hit, props = picker(artist, mouseevent)
  

  to determine the hit test. if the mouse event is over the artist, return hit=True and props is a dictionary of properties you want added to the PickEvent attributes.

• deprecated: For .Line2D only, picker can also be a float that sets the tolerance for checking whether an event occurred “on” the line; this is deprecated. Use .Line2D.set_pickradius instead.

set_pickradius(d)

Set the pick radius used for containment tests.

See .contains for more details.

Parameters:d (float) – Pick radius, in points.

set_solid_capstyle(s)

Set the cap style for solid lines.

Parameters:s ({'butt', 'round', 'projecting'}) – For examples see /gallery/lines_bars_and_markers/joinstyle.

set_solid_joinstyle(s)

Set the join style for solid lines.

Parameters:s ({'miter', 'round', 'bevel'}) – For examples see /gallery/lines_bars_and_markers/joinstyle.

set_transform(t)

Set the Transformation instance used by this artist.

Parameters:t (matplotlib.transforms.Transform) –

set_xdata(x)

Set the data array for x.

Parameters:x (1D array) –

set_ydata(y)

Set the data array for y.

Parameters:y (1D array) –

update_from(other)

Copy properties from other to self.

validCap = ('butt', 'round', 'projecting')

validJoin = ('miter', 'round', 'bevel')

zorder = 2

class pyspecdata.LooseVersion(vstring=None)

Bases: distutils.version.Version

Version numbering for anarchists and software realists. Implements the standard interface for version number classes as described above. A version number consists of a series of numbers, separated by either periods or strings of letters. When comparing version numbers, the numeric components will be compared numerically, and the alphabetic components lexically. The following are all valid version numbers, in no particular order:

1.5.1 1.5.2b2 161 3.10a 8.02 3.4j 1996.07.12 3.2.pl0 3.1.1.6 2g6 11g 0.960923 2.2beta29 1.13++ 5.5.kw 2.0b1pl0

In fact, there is no such thing as an invalid version number under this scheme; the rules for comparison are simple and predictable, but may not always give the results you want (for some definition of “want”).

component_re = re.compile('(\\d+ | [a-z]+ | \\.)', re.VERBOSE)

parse(vstring)

pyspecdata.OLDplot(*args, **kwargs)

class pyspecdata.Parameter(name, kind, *, default, annotation)

Bases: object

Represents a parameter in a function signature.

Has the following public attributes:

• name : str

  The name of the parameter as a string.

• default : object

  The default value for the parameter if specified. If the parameter has no default value, this attribute is set to Parameter.empty.

• annotation

  The annotation for the parameter if specified. If the parameter has no annotation, this attribute is set to Parameter.empty.

• kind : str

  Describes how argument values are bound to the parameter. Possible values: Parameter.POSITIONAL_ONLY, Parameter.POSITIONAL_OR_KEYWORD, Parameter.VAR_POSITIONAL, Parameter.KEYWORD_ONLY, Parameter.VAR_KEYWORD.

KEYWORD_ONLY = 3

POSITIONAL_ONLY = 0

POSITIONAL_OR_KEYWORD = 1

VAR_KEYWORD = 4

VAR_POSITIONAL = 2

annotation

default

empty

alias of _empty

kind

name

replace(*, name=<class 'inspect._void'>, kind=<class 'inspect._void'>, annotation=<class 'inspect._void'>, default=<class 'inspect._void'>)

Creates a customized copy of the Parameter.

class pyspecdata.PolyCollection(verts, sizes=None, closed=True, **kwargs)

Bases: matplotlib.collections._CollectionWithSizes

set_paths(verts, closed=True)

Set the vertices of the polygons.

Parameters:

• verts (list of array-like) – The sequence of polygons [verts0, verts1, …] where each element verts_i defines the vertices of polygon i as a 2D array-like of shape (M, 2).
• closed (bool, default: True) – Whether the polygon should be closed by adding a CLOSEPOLY connection at the end.

set_verts(verts, closed=True)

Set the vertices of the polygons.

Parameters:

• verts (list of array-like) – The sequence of polygons [verts0, verts1, …] where each element verts_i defines the vertices of polygon i as a 2D array-like of shape (M, 2).
• closed (bool, default: True) – Whether the polygon should be closed by adding a CLOSEPOLY connection at the end.

set_verts_and_codes(verts, codes)

Initialize vertices with path codes.

class pyspecdata.UnivariateSpline(x, y, w=None, bbox=[None, None], k=3, s=None, ext=0, check_finite=False)

Bases: object

1-D smoothing spline fit to a given set of data points.

Fits a spline y = spl(x) of degree k to the provided x, y data. s specifies the number of knots by specifying a smoothing condition.

Parameters:

• x ((N,) array_like) – 1-D array of independent input data. Must be increasing; must be strictly increasing if s is 0.
• y ((N,) array_like) – 1-D array of dependent input data, of the same length as x.
• w ((N,) array_like, optional) – Weights for spline fitting. Must be positive. If None (default), weights are all equal.
• bbox ((2,) array_like, optional) – 2-sequence specifying the boundary of the approximation interval. If None (default), bbox=[x[0], x[-1]].
• k (int, optional) – Degree of the smoothing spline. Must be 1 <= k <= 5. Default is k = 3, a cubic spline.
• s (float or None, optional) –

  Positive smoothing factor used to choose the number of knots. Number of knots will be increased until the smoothing condition is satisfied:

  sum((w[i] * (y[i]-spl(x[i])))**2, axis=0) <= s
  

  If None (default), s = len(w) which should be a good value if 1/w[i] is an estimate of the standard deviation of y[i]. If 0, spline will interpolate through all data points.

• ext (int or str, optional) –

  Controls the extrapolation mode for elements not in the interval defined by the knot sequence.

  • if ext=0 or ‘extrapolate’, return the extrapolated value.
  • if ext=1 or ‘zeros’, return 0
  • if ext=2 or ‘raise’, raise a ValueError
  • if ext=3 of ‘const’, return the boundary value.

  The default value is 0.

• check_finite (bool, optional) – Whether to check that the input arrays contain only finite numbers. Disabling may give a performance gain, but may result in problems (crashes, non-termination or non-sensical results) if the inputs do contain infinities or NaNs. Default is False.

See also

InterpolatedUnivariateSpline

Subclass with smoothing forced to 0

LSQUnivariateSpline

Subclass in which knots are user-selected instead of being set by smoothing condition

splrep

An older, non object-oriented wrapping of FITPACK

splev, sproot, splint, spalde

BivariateSpline

A similar class for two-dimensional spline interpolation

Notes

The number of data points must be larger than the spline degree k.

NaN handling: If the input arrays contain nan values, the result is not useful, since the underlying spline fitting routines cannot deal with nan. A workaround is to use zero weights for not-a-number data points:

>>> from scipy.interpolate import UnivariateSpline
>>> x, y = np.array([1, 2, 3, 4]), np.array([1, np.nan, 3, 4])
>>> w = np.isnan(y)
>>> y[w] = 0.
>>> spl = UnivariateSpline(x, y, w=~w)

Notice the need to replace a nan by a numerical value (precise value does not matter as long as the corresponding weight is zero.)

Examples

>>> import matplotlib.pyplot as plt
>>> from scipy.interpolate import UnivariateSpline
>>> x = np.linspace(-3, 3, 50)
>>> y = np.exp(-x**2) + 0.1 * np.random.randn(50)
>>> plt.plot(x, y, 'ro', ms=5)

Use the default value for the smoothing parameter:

>>> spl = UnivariateSpline(x, y)
>>> xs = np.linspace(-3, 3, 1000)
>>> plt.plot(xs, spl(xs), 'g', lw=3)

Manually change the amount of smoothing:

>>> spl.set_smoothing_factor(0.5)
>>> plt.plot(xs, spl(xs), 'b', lw=3)
>>> plt.show()

antiderivative(n=1)

Construct a new spline representing the antiderivative of this spline.

Parameters:n (int, optional) – Order of antiderivative to evaluate. Default: 1 Returns:spline – Spline of order k2=k+n representing the antiderivative of this spline. Return type:UnivariateSpline

Notes

New in version 0.13.0.

See also

splantider(), derivative()

Examples

>>> from scipy.interpolate import UnivariateSpline
>>> x = np.linspace(0, np.pi/2, 70)
>>> y = 1 / np.sqrt(1 - 0.8*np.sin(x)**2)
>>> spl = UnivariateSpline(x, y, s=0)

The derivative is the inverse operation of the antiderivative, although some floating point error accumulates:

>>> spl(1.7), spl.antiderivative().derivative()(1.7)
(array(2.1565429877197317), array(2.1565429877201865))

Antiderivative can be used to evaluate definite integrals:

>>> ispl = spl.antiderivative()
>>> ispl(np.pi/2) - ispl(0)
2.2572053588768486

This is indeed an approximation to the complete elliptic integral \(K(m) = \int_0^{\pi/2} [1 - m\sin^2 x]^{-1/2} dx\):

>>> from scipy.special import ellipk
>>> ellipk(0.8)
2.2572053268208538

derivative(n=1)

Construct a new spline representing the derivative of this spline.

Parameters:n (int, optional) – Order of derivative to evaluate. Default: 1 Returns:spline – Spline of order k2=k-n representing the derivative of this spline. Return type:UnivariateSpline

See also

splder(), antiderivative()

Notes

New in version 0.13.0.

Examples

This can be used for finding maxima of a curve:

>>> from scipy.interpolate import UnivariateSpline
>>> x = np.linspace(0, 10, 70)
>>> y = np.sin(x)
>>> spl = UnivariateSpline(x, y, k=4, s=0)

Now, differentiate the spline and find the zeros of the derivative. (NB: sproot only works for order 3 splines, so we fit an order 4 spline):

>>> spl.derivative().roots() / np.pi
array([ 0.50000001,  1.5       ,  2.49999998])

This agrees well with roots \(\pi/2 + n\pi\) of \(\cos(x) = \sin'(x)\).

derivatives(x)

Return all derivatives of the spline at the point x.

Parameters:x (float) – The point to evaluate the derivatives at. Returns:der – Derivatives of the orders 0 to k. Return type:ndarray, shape(k+1,)

Examples

>>> from scipy.interpolate import UnivariateSpline
>>> x = np.linspace(0, 3, 11)
>>> y = x**2
>>> spl = UnivariateSpline(x, y)
>>> spl.derivatives(1.5)
array([2.25, 3.0, 2.0, 0])

get_coeffs()

Return spline coefficients.

get_knots()

Return positions of interior knots of the spline.

Internally, the knot vector contains 2*k additional boundary knots.

get_residual()

Return weighted sum of squared residuals of the spline approximation.

This is equivalent to:

sum((w[i] * (y[i]-spl(x[i])))**2, axis=0)

integral(a, b)

Return definite integral of the spline between two given points.

Parameters:

• a (float) – Lower limit of integration.
• b (float) – Upper limit of integration.

Returns:

integral – The value of the definite integral of the spline between limits.

Return type:

float

Examples

>>> from scipy.interpolate import UnivariateSpline
>>> x = np.linspace(0, 3, 11)
>>> y = x**2
>>> spl = UnivariateSpline(x, y)
>>> spl.integral(0, 3)
9.0

which agrees with \(\int x^2 dx = x^3 / 3\) between the limits of 0 and 3.

A caveat is that this routine assumes the spline to be zero outside of the data limits:

>>> spl.integral(-1, 4)
9.0
>>> spl.integral(-1, 0)
0.0

roots()

Return the zeros of the spline.

Restriction: only cubic splines are supported by fitpack.

set_smoothing_factor(s)

Continue spline computation with the given smoothing factor s and with the knots found at the last call.

This routine modifies the spline in place.

static validate_input(x, y, w, bbox, k, s, ext, check_finite)

pyspecdata.addlabels(labelstring, x, y, labels)

obsolete – use plot_label_points

pyspecdata.apply_oom(average_oom, numbers, prev_label='')

scale numbers by the order of magnitude average_oom and change the name of the units by adding the appropriate SI prefix

Parameters:

• average_oom (int or float) – the average order of magnitude to use
• numbers (ndarray) – The numbers to be scaled by average_oom. The array is modified in-place.
• prev_label (str) – a string representing the units

Returns:

new_label – prev_label is prefixed by the appropriate SI prefix

Return type:

str

pyspecdata.applyto_rec(myfunc, myarray, mylist)

apply myfunc to myarray with the intention of collapsing it to a smaller number of values

pyspecdata.autolegend(*args, **kwargs)

pyspecdata.autopad_figure(pad=0.2, centered=False, figname='unknown')

pyspecdata.autostringconvert(arg)

pyspecdata.balance_clims()

works with matplotlib to generate a plot appropriate for positive and negative from here:

https://stackoverflow.com/questions/13060450/how-to-get-current-plots-clim-in-matplotlib

pyspecdata.box_muller(length, return_complex=True)

algorithm to generate normally distributed noise

pyspecdata.bruker_dir(search_string, exp_type)

A generator that returns a 3-tuple of dirname, expno, and dataset for a directory

pyspecdata.bruker_load_t1_axis(file)

pyspecdata.bruker_load_title(file)

pyspecdata.check_ascending_axis(u, tolerance=1e-07, additional_message=[], allow_descending=False)

Check that the array u is ascending and equally spaced, and return the spacing, du. This is a common check needed for FT functions, shears, etc.

Parameters:

• tolerance (double) – The relative variation in du that is allowed. Defaults to 1e-7.
• additional_message (str) – So that the user can easily figure out where the assertion error is coming from, supply some extra text for the respective message.

Returns:

du – the spacing between the elements of u

Return type:

double

pyspecdata.colormap(points, colors, n=256)

pyspecdata.complex_str(arg, fancy_format=False, format_code='%.4g')

render a complex string – leaving out imaginary if it’s real

pyspecdata.concat(datalist, dimname, chop=False)

pyspecdata.contour_plot(xvals, yvals, zvals, color='k', alpha=1.0, npts=300, **kwargs)

pyspecdata.copy_maybe_none(input)

pyspecdata.cw(file, **kwargs)

pyspecdata.decorate_rec(xxx_todo_changeme2, xxx_todo_changeme3, drop_rows=False)

Decorate the rows in A with information in B –> if names overlap, keep the ones in A b_ind and a_ind can be either a single key, or a list of keys; if more than one element in B matches that in A, include both options!!

pyspecdata.deepcopy(x, memo=None, _nil=[])

Deep copy operation on arbitrary Python objects.

See the module’s __doc__ string for more info.

pyspecdata.dp(number, decimalplaces=2, scientific=False, max_front=3)

format out to a certain decimal places, potentially in scientific notation

Parameters:

• decimalplaces (int (optional, default 3)) – number of decimal places
• scientific (boolean (optional, default False)) – use scientific notation
• max_front (int (optional, default 3)) – at most this many places in front of the decimal before switching automatically to scientific notation.

pyspecdata.drop_fields(base, drop_names, usemask=True, asrecarray=False)

Return a new array with fields in drop_names dropped.

Nested fields are supported.

..versionchanged: 1.18.0

drop_fields returns an array with 0 fields if all fields are dropped, rather than returning None as it did previously.

Parameters:

• base (array) – Input array
• drop_names (string or sequence) – String or sequence of strings corresponding to the names of the fields to drop.
• usemask ({False, True}, optional) – Whether to return a masked array or not.
• asrecarray (string or sequence, optional) – Whether to return a recarray or a mrecarray (asrecarray=True) or a plain ndarray or masked array with flexible dtype. The default is False.

Examples

>>> from numpy.lib import recfunctions as rfn
>>> a = np.array([(1, (2, 3.0)), (4, (5, 6.0))],
...   dtype=[('a', np.int64), ('b', [('ba', np.double), ('bb', np.int64)])])
>>> rfn.drop_fields(a, 'a')
array([((2., 3),), ((5., 6),)],
      dtype=[('b', [('ba', '<f8'), ('bb', '<i8')])])
>>> rfn.drop_fields(a, 'ba')
array([(1, (3,)), (4, (6,))], dtype=[('a', '<i8'), ('b', [('bb', '<i8')])])
>>> rfn.drop_fields(a, ['ba', 'bb'])
array([(1,), (4,)], dtype=[('a', '<i8')])

pyspecdata.emptyfunction()

pyspecdata.emptytest(x)

pyspecdata.exc_info() -> (type, value, traceback)

Return information about the most recent exception caught by an except clause in the current stack frame or in an older stack frame.

pyspecdata.exp(*args, **kwargs)

pyspecdata.expand_x(*args)

expand the axes. If an argument is passed, then it refers to the position relative to the current coordinates. Values can be: :0: set this side of the axis to 0 :None: leave this side of the axis alone :a double: rescale the distance from the center of the axis to this side by this number

pyspecdata.expand_y(*args)

expand the axes. If an argument is passed, then it refers to the position relative to the current coordinates. Values can be: :0: set this side of the axis to 0 :None: leave this side of the axis alone :a double: rescale the distance from the center of the axis to this side by this number

pyspecdata.explain_error(e)

Allows you to wrap existing errors with more explanation

For example:

> except BaseException as e: > raise IndexError(“I can’t find the node “+pathstring+explain_error(e)) > + ‘

‘.join([‘> ‘+j for j in str(e).split(‘ ‘)]))# this indents

pyspecdata.fa(input, dtype='complex128')

pyspecdata.fftconvolve(in1, in2, mode='full', axes=None)

Convolve two N-dimensional arrays using FFT.

Convolve in1 and in2 using the fast Fourier transform method, with the output size determined by the mode argument.

This is generally much faster than convolve for large arrays (n > ~500), but can be slower when only a few output values are needed, and can only output float arrays (int or object array inputs will be cast to float).

As of v0.19, convolve automatically chooses this method or the direct method based on an estimation of which is faster.

Parameters:

• in1 (array_like) – First input.
• in2 (array_like) – Second input. Should have the same number of dimensions as in1.
• mode (str {'full', 'valid', 'same'}, optional) –

  A string indicating the size of the output:

  full

  The output is the full discrete linear convolution of the inputs. (Default)

  valid

  The output consists only of those elements that do not rely on the zero-padding. In ‘valid’ mode, either in1 or in2 must be at least as large as the other in every dimension.

  same

  The output is the same size as in1, centered with respect to the ‘full’ output.

• axes (int or array_like of ints or None, optional) – Axes over which to compute the convolution. The default is over all axes.

Returns:

out – An N-dimensional array containing a subset of the discrete linear convolution of in1 with in2.

Return type:

array

See also

convolve()

Uses the direct convolution or FFT convolution algorithm depending on which is faster.

oaconvolve()

Uses the overlap-add method to do convolution, which is generally faster when the input arrays are large and significantly different in size.

Examples

Autocorrelation of white noise is an impulse.

>>> from scipy import signal
>>> sig = np.random.randn(1000)
>>> autocorr = signal.fftconvolve(sig, sig[::-1], mode='full')

>>> import matplotlib.pyplot as plt
>>> fig, (ax_orig, ax_mag) = plt.subplots(2, 1)
>>> ax_orig.plot(sig)
>>> ax_orig.set_title('White noise')
>>> ax_mag.plot(np.arange(-len(sig)+1,len(sig)), autocorr)
>>> ax_mag.set_title('Autocorrelation')
>>> fig.tight_layout()
>>> fig.show()

Gaussian blur implemented using FFT convolution. Notice the dark borders around the image, due to the zero-padding beyond its boundaries. The convolve2d function allows for other types of image boundaries, but is far slower.

>>> from scipy import misc
>>> face = misc.face(gray=True)
>>> kernel = np.outer(signal.gaussian(70, 8), signal.gaussian(70, 8))
>>> blurred = signal.fftconvolve(face, kernel, mode='same')

>>> fig, (ax_orig, ax_kernel, ax_blurred) = plt.subplots(3, 1,
...                                                      figsize=(6, 15))
>>> ax_orig.imshow(face, cmap='gray')
>>> ax_orig.set_title('Original')
>>> ax_orig.set_axis_off()
>>> ax_kernel.imshow(kernel, cmap='gray')
>>> ax_kernel.set_title('Gaussian kernel')
>>> ax_kernel.set_axis_off()
>>> ax_blurred.imshow(blurred, cmap='gray')
>>> ax_blurred.set_title('Blurred')
>>> ax_blurred.set_axis_off()
>>> fig.show()

class pyspecdata.figlist(*arg, **kwargs)

Bases: object

basename

A basename that can be changed to generate different sets of figures with different basenames. For example, this is useful if you are looping over different sets of data, and generating the same set of figures for each set of data (which would correspond to a basename).

Type:str

figurelist

A list of the figure names

Type:list

figdict

A dictionary containing the figurelist and the figure numbers or objects that they correspond to. Keys of this dictionary must be elements of figurelist.

Type:dict

propdict

Maintains various properties for each element in figurelist. Keys of this dictionary must be elements of figurelist.

Type:dict

adjust_spines(spines)

check_units(testdata, x_index, y_index, verbose=False)

generate_ticks(plotdata, axes, rescale, z_norm=None, y_rescale=1, text_scale=0.05, verbose=False, follow_surface=False, lensoffset=0.005, line_width=0.001, tube_radius=0.001, fine_grid=False)

generate 3d ticks and grid for mayavi

get_fig_number(name)

grid()

header(number_above, input_string)

image(A, **kwargs)

Called as fl.image() where fl is the figlist_var object

Note that this code just wraps the figlist properties, and the heavy lifting is done by the image( function. Together, the effect is as follows:

• check_units converts to human-readable units, and makes sure they match the units already used in the plot.

• if A has more than two dimensions, the final dimension in A.dimlabels is used as the column dimension, and a direct-product of all non-column dimensions (a Kronecker product, such that the innermost index comes the latest in the list A.dimlabels) is used as the row dimension. A white/black line is drawn after the innermost index used to create the direct product is finished iterating.

• If A consists of complex data, then an HSV plot (misnomer, actually an HV plot) is used: - convert to polar form: \(z=\rho \exp(i \phi)\) - \(\phi\) determines the color (Hue)

  • Color wheel is cyclical, like \(\exp(i \phi)\)
  • red is taken as \(\phi=0\), purely real and positive
  • green-blue is \(pi\) radians out of phase with red and therefore negative real

  • \(\rho\) determines the intensity (value) - Depending on whether or not black is set (either as a

    keyword argument, or fl.black, the background will be black with high \(\rho\) values “lit up” (intended for screen plotting) or the background will be white with the high \(\rho\) values “colored in” (intended for printing)

• If the data type (dtype) of the data in A is real (typically achieved by calling abs(A) or A.runcopy(real)), then A is plotted with a colormap and corresponding colorbar.

• If no title has been given, it’s set to the name of the current plot in the figurelist

A

Type:nddata or numpy array

x

If A is a numpy array, then this gives the values along the x axis (columns). Defaults to the size of the array. Not used if A is nddata.

Type:Optional[double] or Optional[scalar]

y

If A is a numpy array, then this gives the values along the y axis (columns). Defaults to the size of the array. Not used if A is nddata.

Type:Optional[double] or Optional[scalar]

x_first

Since it’s designed to represent matrices, an image plot by defaults is “transposed” relative to all other plots. If you want the first dimension on the x-axis (e.g., if you are plotting a contour plot on top of an image), then set x_first to True.

Type:boolean

spacing

Determines the size of the white/black line drawn Defaults to 1

Type:integer

ax

the Axis object where the plot should go.

Type:matplotlib Axes

all remaning

are passed through to matplotlib imshow

origin

upper and lower are passed to matplotlib. Flip is for 2D nmr, and flips the data manually.

Type:{‘upper’, ‘lower’, ‘flip’}

.. code-block:: python

from pyspecdata import * fl = figlist_var()

t = r_[-1:1:300j] x = nddata(t,[-1],[‘x’]).labels(‘x’,t) y = nddata(t,[-1],[‘y’]).labels(‘y’,t)

z = x**2 + 2*y**2 print “dimlabels of z:”,z.dimlabels

fl.next(‘image with contours’) fl.image(z,x_first = True) # x_first is needed to align # with the contour plot z.contour(colors = ‘w’,alpha = 0.75)

fl.next(‘simple plot’) # just to show that x is the same # here as well fl.plot(z[‘y’:(0,0.01)])

fl.show(‘compare_image_contour_150911.pdf’)

label_point(data, axis, value, thislabel, show_point=True, xscale=1, **new_kwargs)

only works for 1D data: assume you’ve passed a single-point nddata, and label it

xscale gives the unit scaling

..todo:

Improve the unit scaling, so that this would also work.

Allow it to include a format string that would use the value.

Parameters:show_point (bool) – Defaults to True. Actually generate a point (circle), vs. just the label.

marked_text(marker, input_text='', sep='\n')

Creates a named marker where we can place text. If marker has been used, goes back and places text there.

mesh(plotdata, Z_normalization=None, equal_scale=True, lensoffset=0.001, show_contours=False, grey_surf=False, **kwargs)

next(input_name, legend=False, boundaries=None, twinx=None, **kwargs)

Switch to the figure given by input_name, which is used not only as a string-based name for the figure, but also as a default title and as a base name for resulting figure files.

In the future, we actually want this to track the appropriate axis object!

Parameters:

• legend (bool) – If this is set, a legend is created outside the figure.
• twinx ({0,1}) –
  1:plots on an overlayed axis (the matplotlib twinx) whose y axis is labeled on the right when you set this for the first time, you can also set a color kwarg that controls the coloring of the right axis. 0:used to switch back to the left (default) axis
• boundaries – need to add description
• kwargs (dict) – Any other keyword arguments are passed to the matplotlib (mayavi) figure() function that’s used to switch (create) figures.

phaseplot_finalize()

Performs plot decorations that are typically desired for a manual phasing plot. This assumes that the y-axis is given in units of half-cycles ($pi$ radians).

plot(*args, **kwargs)

Parameters:

• linestyle ({':','--','.','etc.'}) – the style of the line
• plottype ({'semilogy','semilogx','loglog'}) – Select a logarithmic plotting style.
• nosemilog (True) – Typically, if you supply a log-spaced axis, a semilogx plot will be automatically selected. This overrides that behavior. Defaults to False.

pop_marker()

push_marker()

setprops(**kwargs)

show(*args, **kwargs)

show_prep()

text(mytext)

twinx(autopad=False, orig=False, color=None)

use_autolegend(value=None)

No argument sets to true if it’s not already set

pyspecdata.figlist_var

alias of pyspecdata.core.figlist

pyspecdata.figlistini(first_figure)

processes a figure list argument: typically, you want to have a figure_list keyword argument for every function, which is by default set to None, then call this on the argument – it always returns a figure list, creating a new one if required similarly, somewhere I have another guy that processes the output, so that if it’s set to None, it will by default dump and show the figure list, and not return a figure list in the output

pyspecdata.figlistini_old(first_figure)

pyspecdata.figlistret(first_figure, figure_list, *args, **kwargs)

pyspecdata.find_file(searchstring, exp_type=None, postproc=None, print_result=True, verbose=False, prefilter=None, expno=None, dimname='', return_acq=False, add_sizes=[], add_dims=[], use_sweep=None, indirect_dimlabels=None, lookup={}, **kwargs)

Find the file given by the regular expression searchstring inside the directory identified by exp_type, load the nddata object, and postprocess with the function postproc.

It looks at the top level of the directory first, and if that fails, starts to look recursively. Whenever it finds a file in the current directory, it will not return data from files in the directories underneath. (For information on how to set up the file searching mechanism, see register_directory()).

Note that all loaded files will be logged in the data_files.log file in the directory that you run your python scripts from (so that you can make sure they are properly synced to the cloud, etc.).

It calls load_indiv_file(), which finds the specific routine from inside one of the modules (sub-packages) associated with a particular file-type.

If it can’t find any files matching the criterion, it logs the missing file and throws an exception.

Parameters:

• searchstring (str) – Most commonly, this is just a fragment of the file name, with any literal *, ., or ? characters preceded by a backslash. More generally, it is a regular expression, where .*searchstring.* matches a filename inside the directory appropriate for exp_type.
• expno (int) – For Bruker NMR and Prospa files, where the files are stored in numbered subdirectories, give the number of the subdirectory that you want. Currently, this parameter is needed to load Bruker and Kea files. If it finds multiple files that match the regular expression, it will try to load this experiment number from all the directories.
• exp_type (str) – Since the function assumes that you have different types of experiments sorted into different directories, this argument specifies the type of experiment see getDATADIR() for more info.
• postproc (function, str, or None) –

  This function is fed the nddata data and the remaining keyword arguments (kwargs) as arguments. It’s assumed that each module for each different file type provides a dictionary called postproc_lookup (some are already available in pySpecData, but also, see the lookup argument, below).

  If postproc is a string, it looks up the string inside the postproc_lookup dictionary that’s appropriate for the file type.

  If postproc is None, it checks to see if the any of the loading functions that were called set the postproc_type property – i.e. it checks the value of data.get_prop('postproc_type') – if this is set, it uses this as a key to pull the corresponding value from postproc_lookup. For example, if this is a bruker file, it sets postproc to the name of the pulse sequence.

  For instance, when the acert module loads an ACERT HDF5 file, it sets postproc_type to the value of (h5 root).experiment.description['class']. This, in turn, is used to choose the type of post-processing.

  dimname:passed to load_indiv_file() return_acq:passed to load_indiv_file() add_sizes:passed to load_indiv_file() add_dims:passed to load_indiv_file() use_sweep:passed to load_indiv_file() indirect_dimlabels:  passed to load_indiv_file()
• lookup (dictionary with str:function pairs) – types of postprocessing to add to the postproc_lookup dictionary

class pyspecdata.fitdata(*args, **kwargs)

Bases: pyspecdata.core.nddata

Inherits from an nddata and enables curve fitting through use of a sympy expression.

The user creates a fitdata class object from an existing nddata class object, and on this fitdata object can define the functional_form() of the curve it would like to fit to the data of the original nddata. This functional form must be provided as a sympy expression, with one of its variables matching the name of the dimension that the user would like to fit to. The user provides fit coefficients using fit_coeff() and obtains output using fit() and eval().

If you haven’t done this before, create a jupyter notebook (not checked in, just for your own playing around) with: ` import sympy as s s.init_printing() ` you can then use s.symbols( to create symbols/variables that allow you to build the mathematical expression for your fitting function

add_inactive_p(p)

analytical_covariance()

Not up to date

bootstrap(points, swap_out=None, seedval=10347, minbounds={}, maxbounds={})

copy()

Return a full copy of this instance.

Because methods typically change the data in place, you might want to use this frequently.

Parameters:data (boolean) –

Default to True. False doesn’t copy the data – this is for internal use, e.g. when you want to copy all the metadata and perform a calculation on the data.

The code for this also provides the definitive list of the nddata metadata.

covar(*names)

give the covariance for the different symbols

covarmat(*names)

eval(taxis, set_what=None, set_to=None)

after we have fit, evaluate the fit function along the axis taxis set_what and set_to allow you to forcibly set_what a specific symbol to a specific value –> however, this does not affect the class, but only the return value

fit(set_what=None, set_to=None, force_analytical=False)

actually run the fit

fitfunc(p, x)

this wraps fitfunc_raw (which gives the actual form of the fit function) to take care of forced variables

function_string

A property of the fitdata class which stores a string output of the functional form of the desired fit expression provided in func:functional_form in LaTeX format

functional_form

A property of the fitdata class which is set by the user, takes as input a sympy expression of the desired fit expression

gen_indices(this_set, set_to)

pass this this_set and this_set_to parameters, and it will return: indices,values,mask indices –> gives the indices that are forced values –> the values they are forced to mask –> p[mask] are actually active in the fit

guess(use_pseudoinverse=False)

old code that I am preserving here – provide the guess for our parameters; by default, based on pseudoinverse

latex()

show the latex string for the function, with all the symbols substituted by their values

linear(*args, **kwargs)

return the linear-form function, either smoothly along the fit function, or on the raw data, depending on whether or not the taxis argument is given can take optional arguments and pass them on to eval

makereal()

output(*name)

give the fit value of a particular symbol, or a dictionary of all values.

Parameters:name (str (optional)) – name of the symbol. If no name is passed, then output returns a dictionary of the resulting values. Returns:retval – Either a dictionary of all the values, or the value itself. Return type:dict or float

parameter_derivatives(xvals, set=None, set_to=None)

return a matrix containing derivatives of the parameters, can set dict set, or keys set, vals set_to

pinv(*args, **kwargs)

remove_inactive_p(p)

rename(previous, new)

residual(p, x, y, sigma)

just the error function

settoguess()

a debugging function, to easily plot the initial guess

pyspecdata.format_listofexps(args)

Phased out: leaving documentation so we can interpret and update old code

This is an auxiliary function that’s used to decode the experiment list.

Parameters:args (list or tuple) –

can be in one of two formats :(dirname,[i,j,k,...N]): typically used, e.g. for

Bruker NMR experiments. i,j,...N are integer numbers referring to individual experiments that are stored in subdirectories of dirname (a string).

([exp_name1,...,exp_nameN]):  just return this list of experiments given by the strings exp_name1…`exp_nameN`. ([exp_name1,...,exp_nameN],[]):  identical to previous ([exp_name1,...,exp_nameN],[]):  identical to previous (exp_name1,...,exp_nameN):  identical to previous (exp_name) or (exp_name,[]):  works for a single experiment

class pyspecdata.function

Bases: object

Create a function object.

code

a code object

globals

the globals dictionary

name

a string that overrides the name from the code object

argdefs

a tuple that specifies the default argument values

closure

a tuple that supplies the bindings for free variables

pyspecdata.gci()

Get the current colorable artist.

Specifically, returns the current .ScalarMappable instance (.Image created by imshow or figimage, .Collection created by pcolor or scatter, etc.), or None if no such instance has been defined.

The current image is an attribute of the current axes, or the nearest earlier axes in the current figure that contains an image.

Notes

Historically, the only colorable artists were images; hence the name gci (get current image).

pyspecdata.gensearch(labelname, format='%0.3f', value=None, precision=None)

obsolete – use h5gensearch

pyspecdata.getDATADIR(*args, **kwargs)

Used to find a directory containing data in a way that works seamlessly across different computers (and operating systems). Supports the case where data is processed both on a laboratory computer and (e.g. after transferring via ssh or a syncing client) on a user’s laptop. While it will return a default directory without any arguments, it is typically used with the keyword argument exp_type, described below.

Note that the most common way to use this mechanism is to set up your directories using the pyspecdata_register_dir shell command – see register_directory().

It returns the directory ending in a trailing (back)slash.

It is determined by a call to MyConfig.get_setting with the setting name data_directory and the environment variable set to PYTHON_DATA_DIR.

Parameters:exp_type (str) –

A string identifying the name of a subdirectory where the data is stored. It can contain slashes. Typically, this gives the path relative to a google drive, rclone, dropbox, etc, repository. To make code portable, exp_type should not contain a full path or or portions of the path that are specific to the computer/user.

If the directory has note been used before, all the directories listed in the user’s _pyspecdata or .pyspecdata config file will be searched recursively up to 2 levels deep.

It searches for exp_type in this order:

• Look in the ExpTypes section of the config file.

  • Note that by using this, you can store data in locations other

    than your main data directory. For example, consider the following section of the ~/.pyspecdata config file: ` [ExpTypes] alternate_base = /opt/other_data alternate_type_one = %(alternate_base)s/type_one ` which would find data with exp_type alternate_type_one in /opt/other_data/type_one.

• use os.walk to search for a directory with this name

  inside the directory identified by experimental_data. excluding things that start with ‘.’, ‘_’ or containing ‘.hfssresults’, always choosing the thing that’s highest up in the tree. If it doesn’t find a directory inside experimental_data, it will search inside all the directories already listed in ExpTypes. Currently, in both attempts, it will only walk 2 levels deep (since NMR directories can be rather complex, and otherwise it would take forever).

pyspecdata.gridandtick(ax, rotation=(0, 0), precision=(2, 2), labelstring=('', ''), gridcolor=None, formatonly=False, fixed_y_locator=None, use_grid=True, spines=None, y=True)

pyspecdata.gridon(gridcolor=None)

pyspecdata.h5addrow(bottomnode, tablename, *args, **kwargs)

add a row to a table, creating it if necessary, but don’t add if the data matches the search condition indicated by match_row match_row can be either text or a dictionary – in the latter case it’s passed to h5searchstring

pyspecdata.h5attachattributes(node, listofattributes, myvalues)

pyspecdata.h5child(thisnode, childname, clear=False, create=None)

grab the child, optionally clearing it and/or (by default) creating it

pyspecdata.h5inlist(columnname, mylist)

returns rows where the column named columnname is in the value of mylist

pyspecdata.h5join(firsttuple, secondtuple, additional_search='', select_fields=None, pop_fields=None)

pyspecdata.h5loaddict(thisnode)

pyspecdata.h5nodebypath(h5path, force=False, only_lowest=False, check_only=False, directory='.')

return the node based on an absolute path, including the filename

pyspecdata.h5remrows(bottomnode, tablename, searchstring)

pyspecdata.h5searchstring(*args, **kwargs)

generate robust search strings :parameter fieldname,value: search AROUND a certain value (overcomes some type conversion issues) optional arguments are the format specifier and the fractional precision: OR :parameter field_and_value_dictionary: generate a search string that matches one or more criteria

pyspecdata.h5table(bottomnode, tablename, tabledata)

create the table, or if tabledata is None, just check if it exists

pyspecdata.image(A, x=[], y=[], **kwargs)

Please don’t call image directly anymore – use the image method of figurelist

pyspecdata.init_logging(level=10, stdout_level=20, filename='pyspecdata.log')

A decent logging setup to log to ~/pyspecdata.log (and ~/pyspecdata.XX.log if that’s taken).

By default, everything above “debug” is logged to a file, while everything above “info” is printed to stdout.

pyspecdata.inside_sphinx()

class pyspecdata.interp1d(x, y, kind='linear', axis=-1, copy=True, bounds_error=None, fill_value=nan, assume_sorted=False)

Bases: scipy.interpolate.polyint._Interpolator1D

Interpolate a 1-D function.

x and y are arrays of values used to approximate some function f: y = f(x). This class returns a function whose call method uses interpolation to find the value of new points.

Note that calling interp1d with NaNs present in input values results in undefined behaviour.

Parameters:

• x ((N,) array_like) – A 1-D array of real values.
• y ((..,N,..) array_like) – A N-D array of real values. The length of y along the interpolation axis must be equal to the length of x.
• kind (str or int, optional) – Specifies the kind of interpolation as a string (‘linear’, ‘nearest’, ‘zero’, ‘slinear’, ‘quadratic’, ‘cubic’, ‘previous’, ‘next’, where ‘zero’, ‘slinear’, ‘quadratic’ and ‘cubic’ refer to a spline interpolation of zeroth, first, second or third order; ‘previous’ and ‘next’ simply return the previous or next value of the point) or as an integer specifying the order of the spline interpolator to use. Default is ‘linear’.
• axis (int, optional) – Specifies the axis of y along which to interpolate. Interpolation defaults to the last axis of y.
• copy (bool, optional) – If True, the class makes internal copies of x and y. If False, references to x and y are used. The default is to copy.
• bounds_error (bool, optional) – If True, a ValueError is raised any time interpolation is attempted on a value outside of the range of x (where extrapolation is necessary). If False, out of bounds values are assigned fill_value. By default, an error is raised unless fill_value="extrapolate".
• fill_value (array-like or (array-like, array_like) or "extrapolate", optional) –
  • if a ndarray (or float), this value will be used to fill in for requested points outside of the data range. If not provided, then the default is NaN. The array-like must broadcast properly to the dimensions of the non-interpolation axes.
  • If a two-element tuple, then the first element is used as a fill value for x_new < x[0] and the second element is used for x_new > x[-1]. Anything that is not a 2-element tuple (e.g., list or ndarray, regardless of shape) is taken to be a single array-like argument meant to be used for both bounds as below, above = fill_value, fill_value.

    New in version 0.17.0.

  • If “extrapolate”, then points outside the data range will be extrapolated.

    New in version 0.17.0.

• assume_sorted (bool, optional) – If False, values of x can be in any order and they are sorted first. If True, x has to be an array of monotonically increasing values.

fill_value

__call__()

See also

splrep, splev

UnivariateSpline

An object-oriented wrapper of the FITPACK routines.

interp2d

2-D interpolation

Examples

>>> import matplotlib.pyplot as plt
>>> from scipy import interpolate
>>> x = np.arange(0, 10)
>>> y = np.exp(-x/3.0)
>>> f = interpolate.interp1d(x, y)

>>> xnew = np.arange(0, 9, 0.1)
>>> ynew = f(xnew)   # use interpolation function returned by `interp1d`
>>> plt.plot(x, y, 'o', xnew, ynew, '-')
>>> plt.show()

fill_value

The fill value.

pyspecdata.ismethod(object)

Return true if the object is an instance method.

Instance method objects provide these attributes:

__doc__ documentation string __name__ name with which this method was defined __func__ function object containing implementation of method __self__ instance to which this method is bound

pyspecdata.issympy(x)

tests if something is sympy (based on the module name)

pyspecdata.join_rec(xxx_todo_changeme, xxx_todo_changeme1)

pyspecdata.lambda_rec(myarray, myname, myfunction, *varargs)

make a new field “myname” which consists of “myfunction” evaluated with the fields given by “myargs” as arguments the new field is always placed after the last argument name if myname is in myargs, the original row is popped

pyspecdata.lambdify(args, expr, modules=None, printer=None, use_imps=True, dummify=False)

Convert a SymPy expression into a function that allows for fast numeric evaluation.

Warning

This function uses exec, and thus shouldn’t be used on unsanitized input.

For example, to convert the SymPy expression sin(x) + cos(x) to an equivalent NumPy function that numerically evaluates it:

>>> from sympy import sin, cos, symbols, lambdify
>>> import numpy as np
>>> x = symbols('x')
>>> expr = sin(x) + cos(x)
>>> expr
sin(x) + cos(x)
>>> f = lambdify(x, expr, 'numpy')
>>> a = np.array([1, 2])
>>> f(a)
[1.38177329 0.49315059]

The primary purpose of this function is to provide a bridge from SymPy expressions to numerical libraries such as NumPy, SciPy, NumExpr, mpmath, and tensorflow. In general, SymPy functions do not work with objects from other libraries, such as NumPy arrays, and functions from numeric libraries like NumPy or mpmath do not work on SymPy expressions. lambdify bridges the two by converting a SymPy expression to an equivalent numeric function.

The basic workflow with lambdify is to first create a SymPy expression representing whatever mathematical function you wish to evaluate. This should be done using only SymPy functions and expressions. Then, use lambdify to convert this to an equivalent function for numerical evaluation. For instance, above we created expr using the SymPy symbol x and SymPy functions sin and cos, then converted it to an equivalent NumPy function f, and called it on a NumPy array a.

Parameters:

• args (List[Symbol]) –

  A variable or a list of variables whose nesting represents the nesting of the arguments that will be passed to the function.

  Variables can be symbols, undefined functions, or matrix symbols.

  >>> from sympy import Eq
  >>> from sympy.abc import x, y, z
  

  The list of variables should match the structure of how the arguments will be passed to the function. Simply enclose the parameters as they will be passed in a list.

  To call a function like f(x) then [x] should be the first argument to lambdify; for this case a single x can also be used:

  >>> f = lambdify(x, x + 1)
  >>> f(1)
  2
  >>> f = lambdify([x], x + 1)
  >>> f(1)
  2
  

  To call a function like f(x, y) then [x, y] will be the first argument of the lambdify:

  >>> f = lambdify([x, y], x + y)
  >>> f(1, 1)
  2
  

  To call a function with a single 3-element tuple like f((x, y, z)) then [(x, y, z)] will be the first argument of the lambdify:

  >>> f = lambdify([(x, y, z)], Eq(z**2, x**2 + y**2))
  >>> f((3, 4, 5))
  True
  

  If two args will be passed and the first is a scalar but the second is a tuple with two arguments then the items in the list should match that structure:

  >>> f = lambdify([x, (y, z)], x + y + z)
  >>> f(1, (2, 3))
  6
  

• expr (Expr) –

  An expression, list of expressions, or matrix to be evaluated.

  Lists may be nested. If the expression is a list, the output will also be a list.

  >>> f = lambdify(x, [x, [x + 1, x + 2]])
  >>> f(1)
  [1, [2, 3]]
  

  If it is a matrix, an array will be returned (for the NumPy module).

  >>> from sympy import Matrix
  >>> f = lambdify(x, Matrix([x, x + 1]))
  >>> f(1)
  [[1]
  [2]]
  

  Note that the argument order here (variables then expression) is used to emulate the Python lambda keyword. lambdify(x, expr) works (roughly) like lambda x: expr (see lambdify-how-it-works below).

• modules (str, optional) –

  Specifies the numeric library to use.

  If not specified, modules defaults to:

  • ["scipy", "numpy"] if SciPy is installed
  • ["numpy"] if only NumPy is installed
  • ["math", "mpmath", "sympy"] if neither is installed.

  That is, SymPy functions are replaced as far as possible by either scipy or numpy functions if available, and Python’s standard library math, or mpmath functions otherwise.

  modules can be one of the following types:

  • The strings "math", "mpmath", "numpy", "numexpr", "scipy", "sympy", or "tensorflow". This uses the corresponding printer and namespace mapping for that module.
  • A module (e.g., math). This uses the global namespace of the module. If the module is one of the above known modules, it will also use the corresponding printer and namespace mapping (i.e., modules=numpy is equivalent to modules="numpy").
  • A dictionary that maps names of SymPy functions to arbitrary functions (e.g., {'sin': custom_sin}).
  • A list that contains a mix of the arguments above, with higher priority given to entries appearing first (e.g., to use the NumPy module but override the sin function with a custom version, you can use [{'sin': custom_sin}, 'numpy']).
• dummify (bool, optional) –

  Whether or not the variables in the provided expression that are not valid Python identifiers are substituted with dummy symbols.

  This allows for undefined functions like Function('f')(t) to be supplied as arguments. By default, the variables are only dummified if they are not valid Python identifiers.

  Set dummify=True to replace all arguments with dummy symbols (if args is not a string) - for example, to ensure that the arguments do not redefine any built-in names.

Examples

>>> from sympy.utilities.lambdify import implemented_function
>>> from sympy import sqrt, sin, Matrix
>>> from sympy import Function
>>> from sympy.abc import w, x, y, z

>>> f = lambdify(x, x**2)
>>> f(2)
4
>>> f = lambdify((x, y, z), [z, y, x])
>>> f(1,2,3)
[3, 2, 1]
>>> f = lambdify(x, sqrt(x))
>>> f(4)
2.0
>>> f = lambdify((x, y), sin(x*y)**2)
>>> f(0, 5)
0.0
>>> row = lambdify((x, y), Matrix((x, x + y)).T, modules='sympy')
>>> row(1, 2)
Matrix([[1, 3]])

lambdify can be used to translate SymPy expressions into mpmath functions. This may be preferable to using evalf (which uses mpmath on the backend) in some cases.

>>> import mpmath
>>> f = lambdify(x, sin(x), 'mpmath')
>>> f(1)
0.8414709848078965

Tuple arguments are handled and the lambdified function should be called with the same type of arguments as were used to create the function:

>>> f = lambdify((x, (y, z)), x + y)
>>> f(1, (2, 4))
3

The flatten function can be used to always work with flattened arguments:

>>> from sympy.utilities.iterables import flatten
>>> args = w, (x, (y, z))
>>> vals = 1, (2, (3, 4))
>>> f = lambdify(flatten(args), w + x + y + z)
>>> f(*flatten(vals))
10

Functions present in expr can also carry their own numerical implementations, in a callable attached to the _imp_ attribute. This can be used with undefined functions using the implemented_function factory:

>>> f = implemented_function(Function('f'), lambda x: x+1)
>>> func = lambdify(x, f(x))
>>> func(4)
5

lambdify always prefers _imp_ implementations to implementations in other namespaces, unless the use_imps input parameter is False.

Usage with Tensorflow:

>>> import tensorflow as tf
>>> from sympy import Max, sin, lambdify
>>> from sympy.abc import x

>>> f = Max(x, sin(x))
>>> func = lambdify(x, f, 'tensorflow')

After tensorflow v2, eager execution is enabled by default. If you want to get the compatible result across tensorflow v1 and v2 as same as this tutorial, run this line.

>>> tf.compat.v1.enable_eager_execution()

If you have eager execution enabled, you can get the result out immediately as you can use numpy.

If you pass tensorflow objects, you may get an EagerTensor object instead of value.

>>> result = func(tf.constant(1.0))
>>> print(result)
tf.Tensor(1.0, shape=(), dtype=float32)
>>> print(result.__class__)
<class 'tensorflow.python.framework.ops.EagerTensor'>

You can use .numpy() to get the numpy value of the tensor.

>>> result.numpy()
1.0

>>> var = tf.Variable(2.0)
>>> result = func(var) # also works for tf.Variable and tf.Placeholder
>>> result.numpy()
2.0

And it works with any shape array.

>>> tensor = tf.constant([[1.0, 2.0], [3.0, 4.0]])
>>> result = func(tensor)
>>> result.numpy()
[[1. 2.]
 [3. 4.]]

Notes

• For functions involving large array calculations, numexpr can provide a significant speedup over numpy. Please note that the available functions for numexpr are more limited than numpy but can be expanded with implemented_function and user defined subclasses of Function. If specified, numexpr may be the only option in modules. The official list of numexpr functions can be found at: https://numexpr.readthedocs.io/en/latest/user_guide.html#supported-functions

• In previous versions of SymPy, lambdify replaced Matrix with numpy.matrix by default. As of SymPy 1.0 numpy.array is the default. To get the old default behavior you must pass in [{'ImmutableDenseMatrix':  numpy.matrix}, 'numpy'] to the modules kwarg.

  >>> from sympy import lambdify, Matrix
  >>> from sympy.abc import x, y
  >>> import numpy
  >>> array2mat = [{'ImmutableDenseMatrix': numpy.matrix}, 'numpy']
  >>> f = lambdify((x, y), Matrix([x, y]), modules=array2mat)
  >>> f(1, 2)
  [[1]
   [2]]
  

• In the above examples, the generated functions can accept scalar values or numpy arrays as arguments. However, in some cases the generated function relies on the input being a numpy array:

  >>> from sympy import Piecewise
  >>> from sympy.testing.pytest import ignore_warnings
  >>> f = lambdify(x, Piecewise((x, x <= 1), (1/x, x > 1)), "numpy")
  

  >>> with ignore_warnings(RuntimeWarning):
  ...     f(numpy.array([-1, 0, 1, 2]))
  [-1.   0.   1.   0.5]
  

  >>> f(0)
  Traceback (most recent call last):
      ...
  ZeroDivisionError: division by zero
  

  In such cases, the input should be wrapped in a numpy array:

  >>> with ignore_warnings(RuntimeWarning):
  ...     float(f(numpy.array([0])))
  0.0
  

  Or if numpy functionality is not required another module can be used:

  >>> f = lambdify(x, Piecewise((x, x <= 1), (1/x, x > 1)), "math")
  >>> f(0)
  0
  

When using this function, it helps a great deal to have an idea of what it is doing. At its core, lambdify is nothing more than a namespace translation, on top of a special printer that makes some corner cases work properly.

To understand lambdify, first we must properly understand how Python namespaces work. Say we had two files. One called sin_cos_sympy.py, with

# sin_cos_sympy.py

from sympy import sin, cos

def sin_cos(x):
    return sin(x) + cos(x)

and one called sin_cos_numpy.py with

# sin_cos_numpy.py

from numpy import sin, cos

def sin_cos(x):
    return sin(x) + cos(x)

The two files define an identical function sin_cos. However, in the first file, sin and cos are defined as the SymPy sin and cos. In the second, they are defined as the NumPy versions.

If we were to import the first file and use the sin_cos function, we would get something like

>>> from sin_cos_sympy import sin_cos # doctest: +SKIP
>>> sin_cos(1) # doctest: +SKIP
cos(1) + sin(1)

On the other hand, if we imported sin_cos from the second file, we would get

>>> from sin_cos_numpy import sin_cos # doctest: +SKIP
>>> sin_cos(1) # doctest: +SKIP
1.38177329068

In the first case we got a symbolic output, because it used the symbolic sin and cos functions from SymPy. In the second, we got a numeric result, because sin_cos used the numeric sin and cos functions from NumPy. But notice that the versions of sin and cos that were used was not inherent to the sin_cos function definition. Both sin_cos definitions are exactly the same. Rather, it was based on the names defined at the module where the sin_cos function was defined.

The key point here is that when function in Python references a name that is not defined in the function, that name is looked up in the “global” namespace of the module where that function is defined.

Now, in Python, we can emulate this behavior without actually writing a file to disk using the exec function. exec takes a string containing a block of Python code, and a dictionary that should contain the global variables of the module. It then executes the code “in” that dictionary, as if it were the module globals. The following is equivalent to the sin_cos defined in sin_cos_sympy.py:

>>> import sympy
>>> module_dictionary = {'sin': sympy.sin, 'cos': sympy.cos}
>>> exec('''
... def sin_cos(x):
...     return sin(x) + cos(x)
... ''', module_dictionary)
>>> sin_cos = module_dictionary['sin_cos']
>>> sin_cos(1)
cos(1) + sin(1)

and similarly with sin_cos_numpy:

>>> import numpy
>>> module_dictionary = {'sin': numpy.sin, 'cos': numpy.cos}
>>> exec('''
... def sin_cos(x):
...     return sin(x) + cos(x)
... ''', module_dictionary)
>>> sin_cos = module_dictionary['sin_cos']
>>> sin_cos(1)
1.38177329068

So now we can get an idea of how lambdify works. The name “lambdify” comes from the fact that we can think of something like lambdify(x, sin(x) + cos(x), 'numpy') as lambda x: sin(x) + cos(x), where sin and cos come from the numpy namespace. This is also why the symbols argument is first in lambdify, as opposed to most SymPy functions where it comes after the expression: to better mimic the lambda keyword.

lambdify takes the input expression (like sin(x) + cos(x)) and

1. Converts it to a string
2. Creates a module globals dictionary based on the modules that are passed in (by default, it uses the NumPy module)
3. Creates the string "def func({vars}): return {expr}", where {vars} is the list of variables separated by commas, and {expr} is the string created in step 1., then exec``s that string with the module globals namespace and returns ``func.

In fact, functions returned by lambdify support inspection. So you can see exactly how they are defined by using inspect.getsource, or ?? if you are using IPython or the Jupyter notebook.

>>> f = lambdify(x, sin(x) + cos(x))
>>> import inspect
>>> print(inspect.getsource(f))
def _lambdifygenerated(x):
    return (sin(x) + cos(x))

This shows us the source code of the function, but not the namespace it was defined in. We can inspect that by looking at the __globals__ attribute of f:

>>> f.__globals__['sin']
<ufunc 'sin'>
>>> f.__globals__['cos']
<ufunc 'cos'>
>>> f.__globals__['sin'] is numpy.sin
True

This shows us that sin and cos in the namespace of f will be numpy.sin and numpy.cos.

Note that there are some convenience layers in each of these steps, but at the core, this is how lambdify works. Step 1 is done using the LambdaPrinter printers defined in the printing module (see sympy.printing.lambdarepr). This allows different SymPy expressions to define how they should be converted to a string for different modules. You can change which printer lambdify uses by passing a custom printer in to the printer argument.

Step 2 is augmented by certain translations. There are default translations for each module, but you can provide your own by passing a list to the modules argument. For instance,

>>> def mysin(x):
...     print('taking the sin of', x)
...     return numpy.sin(x)
...
>>> f = lambdify(x, sin(x), [{'sin': mysin}, 'numpy'])
>>> f(1)
taking the sin of 1
0.8414709848078965

The globals dictionary is generated from the list by merging the dictionary {'sin': mysin} and the module dictionary for NumPy. The merging is done so that earlier items take precedence, which is why mysin is used above instead of numpy.sin.

If you want to modify the way lambdify works for a given function, it is usually easiest to do so by modifying the globals dictionary as such. In more complicated cases, it may be necessary to create and pass in a custom printer.

Finally, step 3 is augmented with certain convenience operations, such as the addition of a docstring.

Understanding how lambdify works can make it easier to avoid certain gotchas when using it. For instance, a common mistake is to create a lambdified function for one module (say, NumPy), and pass it objects from another (say, a SymPy expression).

For instance, say we create

>>> from sympy.abc import x
>>> f = lambdify(x, x + 1, 'numpy')

Now if we pass in a NumPy array, we get that array plus 1

>>> import numpy
>>> a = numpy.array([1, 2])
>>> f(a)
[2 3]

But what happens if you make the mistake of passing in a SymPy expression instead of a NumPy array:

>>> f(x + 1)
x + 2

This worked, but it was only by accident. Now take a different lambdified function:

>>> from sympy import sin
>>> g = lambdify(x, x + sin(x), 'numpy')

This works as expected on NumPy arrays:

>>> g(a)
[1.84147098 2.90929743]

But if we try to pass in a SymPy expression, it fails

>>> try:
...     g(x + 1)
... # NumPy release after 1.17 raises TypeError instead of
... # AttributeError
... except (AttributeError, TypeError):
...     raise AttributeError() # doctest: +IGNORE_EXCEPTION_DETAIL
Traceback (most recent call last):
...
AttributeError:

Now, let’s look at what happened. The reason this fails is that g calls numpy.sin on the input expression, and numpy.sin does not know how to operate on a SymPy object. As a general rule, NumPy functions do not know how to operate on SymPy expressions, and SymPy functions do not know how to operate on NumPy arrays. This is why lambdify exists: to provide a bridge between SymPy and NumPy.

However, why is it that f did work? That’s because f doesn’t call any functions, it only adds 1. So the resulting function that is created, def _lambdifygenerated(x): return x + 1 does not depend on the globals namespace it is defined in. Thus it works, but only by accident. A future version of lambdify may remove this behavior.

Be aware that certain implementation details described here may change in future versions of SymPy. The API of passing in custom modules and printers will not change, but the details of how a lambda function is created may change. However, the basic idea will remain the same, and understanding it will be helpful to understanding the behavior of lambdify.

In general: you should create lambdified functions for one module (say, NumPy), and only pass it input types that are compatible with that module (say, NumPy arrays). Remember that by default, if the module argument is not provided, lambdify creates functions using the NumPy and SciPy namespaces.

pyspecdata.leastsq(func, x0, args=(), Dfun=None, full_output=0, col_deriv=0, ftol=1.49012e-08, xtol=1.49012e-08, gtol=0.0, maxfev=0, epsfcn=None, factor=100, diag=None)

Minimize the sum of squares of a set of equations.

x = arg min(sum(func(y)**2,axis=0))
         y

Parameters:

• func (callable) – Should take at least one (possibly length N vector) argument and returns M floating point numbers. It must not return NaNs or fitting might fail.
• x0 (ndarray) – The starting estimate for the minimization.
• args (tuple, optional) – Any extra arguments to func are placed in this tuple.
• Dfun (callable, optional) – A function or method to compute the Jacobian of func with derivatives across the rows. If this is None, the Jacobian will be estimated.
• full_output (bool, optional) – non-zero to return all optional outputs.
• col_deriv (bool, optional) – non-zero to specify that the Jacobian function computes derivatives down the columns (faster, because there is no transpose operation).
• ftol (float, optional) – Relative error desired in the sum of squares.
• xtol (float, optional) – Relative error desired in the approximate solution.
• gtol (float, optional) – Orthogonality desired between the function vector and the columns of the Jacobian.
• maxfev (int, optional) – The maximum number of calls to the function. If Dfun is provided, then the default maxfev is 100*(N+1) where N is the number of elements in x0, otherwise the default maxfev is 200*(N+1).
• epsfcn (float, optional) – A variable used in determining a suitable step length for the forward- difference approximation of the Jacobian (for Dfun=None). Normally the actual step length will be sqrt(epsfcn)*x If epsfcn is less than the machine precision, it is assumed that the relative errors are of the order of the machine precision.
• factor (float, optional) – A parameter determining the initial step bound (factor * || diag * x||). Should be in interval (0.1, 100).
• diag (sequence, optional) – N positive entries that serve as a scale factors for the variables.

Returns:

• x (ndarray) – The solution (or the result of the last iteration for an unsuccessful call).

• cov_x (ndarray) – The inverse of the Hessian. fjac and ipvt are used to construct an estimate of the Hessian. A value of None indicates a singular matrix, which means the curvature in parameters x is numerically flat. To obtain the covariance matrix of the parameters x, cov_x must be multiplied by the variance of the residuals – see curve_fit.

• infodict (dict) – a dictionary of optional outputs with the keys:

  nfev

  The number of function calls

  fvec

  The function evaluated at the output

  fjac

  A permutation of the R matrix of a QR factorization of the final approximate Jacobian matrix, stored column wise. Together with ipvt, the covariance of the estimate can be approximated.

  ipvt

  An integer array of length N which defines a permutation matrix, p, such that fjac*p = q*r, where r is upper triangular with diagonal elements of nonincreasing magnitude. Column j of p is column ipvt(j) of the identity matrix.

  qtf

  The vector (transpose(q) * fvec).

• mesg (str) – A string message giving information about the cause of failure.

• ier (int) – An integer flag. If it is equal to 1, 2, 3 or 4, the solution was found. Otherwise, the solution was not found. In either case, the optional output variable ‘mesg’ gives more information.

See also

least_squares()

Newer interface to solve nonlinear least-squares problems with bounds on the variables. See method=='lm' in particular.

Notes

“leastsq” is a wrapper around MINPACK’s lmdif and lmder algorithms.

cov_x is a Jacobian approximation to the Hessian of the least squares objective function. This approximation assumes that the objective function is based on the difference between some observed target data (ydata) and a (non-linear) function of the parameters f(xdata, params)

func(params) = ydata - f(xdata, params)

so that the objective function is

  min   sum((ydata - f(xdata, params))**2, axis=0)
params

The solution, x, is always a 1-D array, regardless of the shape of x0, or whether x0 is a scalar.

Examples

>>> from scipy.optimize import leastsq
>>> def func(x):
...     return 2*(x-3)**2+1
>>> leastsq(func, 0)
(array([2.99999999]), 1)

pyspecdata.level_str_to_int(level)

pyspecdata.listdir()

Return a list containing the names of the files in the directory.

path can be specified as either str, bytes, or a path-like object. If path is bytes,

the filenames returned will also be bytes; in all other circumstances the filenames returned will be str.

If path is None, uses the path=’.’. On some platforms, path may also be specified as an open file descriptor;

the file descriptor must refer to a directory. If this functionality is unavailable, using it raises NotImplementedError.

The list is in arbitrary order. It does not include the special entries ‘.’ and ‘..’ even if they are present in the directory.

pyspecdata.load_indiv_file(filename, dimname='', return_acq=False, add_sizes=[], add_dims=[], use_sweep=None, indirect_dimlabels=None, expno=None)

Open the file given by filename, use file signature magic and/or filename extension(s) to identify the file type, and call the appropriate function to open it.

Parameters:

• dimname (str) – When there is a single indirect dimension composed of several scans, call the indirect dimension dimname.
• return_acq (DEPRECATED) –
• add_sizes (list) – the sizes associated with the dimensions in add_dims
• add_dims (list) – Can only be used with dimname. Break the dimension dimname into several dimensions, with the names given by the list add_dims and sizes given by add_sizes. If the product of the sizes is not the same as the original dimension given by dimname, retain it as the “outermost” (leftmost) dimension. pyspecdata.core.chunkoff() is used to do this, like so: data.chunkoff(dimname,add_dims,add_sizes)
• indirect_dimlabels (str or None) – passed through to acert.load_pulse (names an indirect dimension when dimlabels isn’t provided)

Returns:

the nddata containing the data, or else, None, indicating that this is part of a pair of files that should be skipped

Return type:

nddata or None

pyspecdata.load_t1_axis(file)

pyspecdata.log_fname(logname, fname, dirname, err=False)

logs the file name either used or missing.

Also, by setting the err flag to True, you can generate an error message that will guide you on how to selectively copy down this data from a remote source (google drive, etc.), e.g.:

``Traceback (most recent call last):

File “proc_square_refl.py”, line 21, in <module>

directory=getDATADIR(exp_type=’test_equip’))

File “c:usersjohnfnotebookpyspecdatapyspecdatacore.py”, line 6630, in __init__

check_only=True, directory=directory)

File “c:usersjohnfnotebookpyspecdatapyspecdatacore.py”, line 1041, in h5nodebypath

+errmsg)

AttributeError: You’re checking for a node in a file (200110_pulse_2.h5) that does not exist I can’t find 200110_pulse_2.h5 in C:Usersjohnfexp_datatest_equip, so I’m going to search for t in your rclone remotes checking remote g_syr: You should be able to retrieve this file with: rclone copy -v –include ‘200110_pulse_2.h5’ g_syr:exp_data/test_equip C:\Users\johnf\exp_data\test_equip``

pyspecdata.lookup_rec(A, B, indexpair)

look up information about A in table B (i.e. chemical by index, etc) indexpair is either the name of the index or – if it’s differently named – the pair of indices given in (A,B) respectively

This will just drop any fields in B that are also in A, and the output uses the first indexname

note that it it seems like the join_rec function above may be more efficient!!

pyspecdata.lrecordarray(*x, **kwargs)

pyspecdata.lsafe(*string, **kwargs)

replacement for normal lsafe – no escaping

pyspecdata.lsafen(*string, **kwargs)

see lsafe, but with an added double newline

pyspecdata.make_bar_graph_indices(mystructarray, list_of_text_fields, recursion_depth=0, spacing=0.1)

This is a recursive function that is used as part of textlabel_bargraph; it does NOT work without the sorting given at the beginning of that function

pyspecdata.make_ndarray(array_to_conv, name_forprint='unknown')

pyspecdata.make_rec(*args, **kwargs)

input,names or a single argument, which is a dictionarynstrlen = 100 gives length of the strings (which need to be specified in record arrays)nyou can also specify (especially useful with the dictionary format) the list order = [str1,str2,…] which orders the output records with the field containing str1 first, then the field containing str2, then any remaining fields

pyspecdata.maprep(*mylist)

pyspecdata.meanstd_rec(myarray, mylist, standard_error=False)

this is something like applyto_rec, except that it applies the mean and creates new rows for the “error,” where it puts the standard deviation

pyspecdata.mybasicfunction(first_figure=None)

this gives the format for doing the image thing note also nextfigure(fl,’name’) and nextfigure({‘lplotproperty’:value})

pyspecdata.mydiff(data, axis=-1)

this will replace diff with a version that has the same number of indices, with the last being the copy of the first

pyspecdata.myfilter(x, center=250000.0, sigma=100000.0)

pyspecdata.myplotfunc(*args, **kwargs)

class pyspecdata.nddata(*args, **kwargs)

Bases: object

This is the detailed API reference. For an introduction on how to use ND-Data, see the Main ND-Data Documentation.

C

shortcut for copy

btw, what we are doing is analogous to a ruby function with functioname!() modify result, and we can use the “out” keyword in numpy.

..todo::

(new idea) This should just set a flag that says “Do not allow this data to be substituted in place,” so that if something goes to edit the data in place, it instead first makes a copy.

also here, see Definition of shallow and deep copy

(older idea) We should offer “N”, which generates something like a copy, but which is sets the equivalent of “nopop”. For example, currently, you need to do something like d.C.argmax('t2'), which is very inefficient, since it copies the whole array. So, instead, we should do d.N.argmax('t2'), which tells argmax and all other functions not to overwrite “self” but to return a new object. This would cause things like “run_nopop” to become obsolete.

add_noise(intensity)

Add Gaussian (box-muller) noise to the data.

Parameters:intensity (double OR function) – If a double, gives the standard deviation of the noise. If a function, used to calculate the standard deviation of the noise from the data: e.g. lambda x: max(abs(x))/10.

aligndata(arg)

This is a fundamental method used by all of the arithmetic operations. It uses the dimension labels of self (the current instance) and arg (an nddata passed to this method) to generate two corresponding output nddatas that I refer to here, respectively, as A and B. A and B have dimensions that are “aligned” – that is, they are identical except for singleton dimensions (note that numpy automatically tiles singleton dimensions). Regardless of how the dimensions of self.data and arg.data (the underlying numpy data) were ordered, A.data and B.data are now ordered identically, where dimensions with the same label (.dimlabel) correspond to the same numpy index. This allows you do do math.

Note that, currently, both A and B are given a full set of axis labels, even for singleton dimensions. This is because we’re assuming you’re going to do math with them, and that the singleton dimensions will be expanded.

Parameters:arg (nddata or ndarray) – The nddata that you want to align to self. If arg is an ndarray, it will try to match dimensions to self based on the length of the dimension. Note: currently there is an issue where this will only really work for 1D data, since it first makes an nddata instance based on arg, which apparently collapses multi-D data to 1D data. Returns:

• A (nddata) – realigned version of self
• B (nddata) – realigned version of arg (the argument)

along(dimname)

Specifies the dimension for the next matrix multiplication (represents the rows/columns).

angle

Return the angle component of the data

argmax(*args, **kwargs)

find the max along a particular axis, and get rid of that axis, replacing it with the index number of the max value

Parameters:raw_index (bool) – return the raw (ndarray) numerical index, rather than the corresponding axis value Note that the result returned is still, however, an nddata (rather than numpy ndarray) object.

argmin(*axes, **kwargs)

If argmin(‘axisname’) find the min along a particular axis, and get rid of that axis, replacing it with the index number of the max value. If argmin(): return a dictionary giving the coordinates of the overall minimum point.

Parameters:raw_index (bool) – Return the raw (ndarray) numerical index, rather than the corresponding axis value. Note that the result returned is still, however, an nddata (rather than numpy ndarray) object.

axis(axisname)

returns a 1-D axis for further manipulation

axlen(axis)

return the size (length) of an axis, by name

Parameters:axis (str) – name of the axis whos length you are interested in

axn(axis)

Return the index number for the axis with the name “axis”

This is used by many other methods. As a simple example, self.:func:axlen`(axis) (the axis length) returns ``shape(self.data)[self.axn(axis)]`

Parameters:axis (str) – name of the axis

cdf(normalized=True, max_bins=500)

calculate the Cumulative Distribution Function for the data along axis_name

only for 1D data right now

Returns: Return type:A new nddata object with an axis labeled values, and data corresponding to the CDF.

check_axis_coords_errors()

chunk(axisin, *otherargs)

“Chunking” is defined here to be the opposite of taking a direct product, increasing the number of dimensions by the inverse of the process by which taking a direct product decreases the number of dimensions. This function chunks axisin into multiple new axes arguments.:

axesout – gives the names of the output axes shapesout – optional – if not given, it assumes equal length – if given, one of the values can be -1, which is assumed length

When there are axes, it assumes that the axes of the new dimensions are nested – e.g., it will chunk a dimension with axis: [1,2,3,4,5,6,7,8,9,10] into dimensions with axes: [0,1,2,3,4], [1,6]

..todo::

Deal with this efficiently when we move to new-style axes

chunk_auto(axis_name, which_field, dimname=None)

assuming that axis “axis_name” is currently labeled with a structured array, choose one field (“which_field”) of that structured array to generate a new dimension Note that for now, by definition, no error is allowed on the axes. However, once I upgrade to using structured arrays to handle axis and data errors, I will want to deal with that appropriately here.

circshift(axis, amount)

contiguous(lambdafunc, axis=None)

Return contiguous blocks that satisfy the condition given by lambdafunc

this function returns the start and stop positions along the axis for the contiguous blocks for which lambdafunc returns true Currently only supported for 1D data

Note

adapted from stackexchange post http://stackoverflow.com/questions/4494404/find-large-number-of-consecutive-values-fulfilling-condition-in-a-numpy-array

Parameters:

• lambdafunc (types.FunctionType) – If only one argument (lambdafunc) is given, then lambdafunc is a function that accepts a copy of the current nddata object (self) as the argument. If two arguments are given, the second is axis, and lambdafunc has two arguments, self and the value of axis.
• axis ({None,str}) – the name of the axis along which you want to find contiguous blocks

Returns:

retval – An \(N\times 2\) matrix, where the \(N\) rows correspond to pairs of axis label that give ranges over which lambdafunc evaluates to True. These are ordered according to descending range width.

Return type:

ndarray

Examples

sum_for_contiguous = abs(forplot).mean('t1')
fl.next("test contiguous")
forplot = sum_for_contiguous.copy().set_error(None)
fl.plot(forplot,alpha = 0.25,linewidth = 3)
print("this is what the max looks like",0.5*sum_for_contiguous.set_error(None).runcopy(max,'t2'))
print(sum_for_contiguous > 0.5*sum_for_contiguous.runcopy(max,'t2'))
retval = sum_for_contiguous.contiguous(quarter_of_max,'t2')
print("contiguous range / 1e6:",retval/1e6)
for j in range(retval.shape[0]):
    a,b = retval[j,:]
    fl.plot(forplot['t2':(a,b)])

contour(labels=True, **kwargs)

Contour plot – kwargs are passed to the matplotlib contour function.

See docstring of figlist_var.image() for an example

labels

Whether or not the levels should be labeled. Defaults to True

Type:boolean

convolve(axisname, filterwidth, convfunc=<function <lambda>>)

Perform a convolution.

Parameters:

• axisname (str) – apply the convolution along axisname
• filterwidth (double) – width of the convolution function.
• convfunc (function) – A function that takes two arguments – the first are the axis coordinates and the second is filterwidth. Default is a normalized Gaussian of width (\(\sigma\)) filterwidth \(\frac{1}{2 \sigma^2}\exp\left( - \frac{x^2}{2 \sigma^2} \right)\) For example if you want a complex Lorentzian with filterwidth controlled by the rate \(R\), i.e. \(\frac{-1}{-i 2 \pi f - R}\) then convfunc = lambda f,R: -1./(-1j*2*pi*f-R)

copy(data=True)

Return a full copy of this instance.

Because methods typically change the data in place, you might want to use this frequently.

Parameters:data (boolean) –

Default to True. False doesn’t copy the data – this is for internal use, e.g. when you want to copy all the metadata and perform a calculation on the data.

The code for this also provides the definitive list of the nddata metadata.

copy_axes(other)

copy_props(other)

Copy all properties (see get_prop()) from another nddata object – note that these include properties pertaining the the FT status of various dimensions.

copyaxes(other)

cropped_log(subplot_axes=None, magnitude=4)

For the purposes of plotting, this generates a copy where I take the log, spanning “magnitude” orders of magnitude This is designed to be called as abs(instance).cropped_log(), so it doesn’t make a copy

diff(thisaxis, backwards=False)

dot(arg)

Tensor dot of self with arg – dot all matching dimension labels. This can be used to do matrix multiplication, but note that the order of doesn’t matter, since the dimensions that are contracted are determined by matching the dimension names, not the order of the dimension.

>>> a = nddata(r_[0:9],[3,3],['a','b'])
>>> b = nddata(r_[0:3],'b')
>>> print a.C.dot(b)
>>> print a.data.dot(b.data)
>>> a = nddata(r_[0:27],[3,3,3],['a','b','c'])
>>> b = nddata(r_[0:9],[3,3],['a','b'])
>>> print a.C.dot(b)
>>> print tensordot(a.data,b.data,axes=((0,1),(0,1)))

>>> a = nddata(r_[0:27],[3,3,3],['a','b','c'])
>>> b = nddata(r_[0:9],[3,3],['a','d'])
>>> print a.C.dot(b)
>>> print tensordot(a.data,b.data,axes=((0),(0)))

extend(axis, extent, fill_with=0, tolerance=1e-05)

If axis is uniformly ascending with spacing \(dx\), then extend by adding a point every \(dx\) until the axis includes the point extent. Fill the newly created datapoints with fill_with.

Parameters:

• axis (str) – name of the axis to extend
• extent (double) – extend the axis axis out to this point
• fill_with (double) – fill the new data points with this value (defaults to 0)
• tolerance (double) – when checking for ascending axis labels, etc., values/differences must match to within tolerance (assumed to represent the actual precision, given various errors, etc.)

extend_for_shear(altered_axis, propto_axis, skew_amount, verbose=False)

this is propto_axis helper function for .fourier.shear

fld(dict_in, noscalar=False)

flatten dictionary – return list

fourier_shear(altered_axis, propto_axis, by_amount, zero_fill=False, start_in_conj=False)

the fourier shear method – see .shear() documentation

fromaxis(*args, **kwargs)

Generate an nddata object from one of the axis labels.

Can be used in one of several ways:

• self.fromaxis('axisname'): Returns an nddata where retval.data consists of the given axis values.
• self.fromaxis('axisname',inputfunc): use axisname as the input for inputfunc, and load the result into retval.data
• self.fromaxis(inputsymbolic): Evaluate inputsymbolic and load the result into retval.data

Parameters:

• axisname (str | list) – The axis (or list of axes) to that is used as the argument of inputfunc or the function represented by inputsymbolic. If this is the only argument, it cannot be a list.
• inputsymbolic (sympy.Expr) – A sympy expression whose only symbols are the names of axes. It is preferred, though not required, that this is passed without an axisname argument – the axis names are then inferred from the symbolic expression.
• inputfunc (function) – A function (typically a lambda function) that taxes the values of the axis given by axisname as input.
• overwrite (bool) – Defaults to False. If set to True, it overwrites self with retval.
• as_array (bool) – Defaults to False. If set to True, retval is a properly dimensioned numpy ndarray rather than an nddata.

Returns:

retval – An expression calculated from the axis(es) given by axisname or inferred from inputsymbolic.

Return type:

nddata | ndarray

ft(axes, tolerance=1e-05, cosine=False, verbose=False, **kwargs)

This performs a Fourier transform along the axes identified by the string or list of strings axes.

It adjusts normalization and units so that the result conforms to

\(\tilde{s}(f)=\int_{x_{min}}^{x_{max}} s(t) e^{-i 2 \pi f t} dt\)

Note that, as noted in the ift() documentation, the inverse transform doesn’t correspond to the equivalent expression for the IFT.

pre-FT, we use the axis to cyclically permute \(t=0\) to the first index

post-FT, we assume that the data has previously been IFT’d If this is the case, passing shift=True will cause an error If this is not the case, passing shift=True generates a standard fftshift shift=None will choose True, if and only if this is not the case

Parameters:

• pad (int or boolean) – pad specifies a zero-filling. If it’s a number, then it gives the length of the zero-filled dimension. If it is just True, then the size of the dimension is determined by rounding the dimension size up to the nearest integral power of 2.
• automix (double) – automix can be set to the approximate frequency value. This is useful for the specific case where the data has been captured on a sampling scope, and it’s severely aliased over.
• cosine (boolean) – yields a sum of the fft and ifft, for a cosine transform

ft_clear_startpoints(axis, t=None, f=None, nearest=None)

Clears memory of where the origins in the time and frequency domain are. This is useful, e.g. when you want to ift and center about time=0. By setting shift=True you can also manually set the points.

Parameters:

• t (float, 'current', 'reset', or None) – keyword arguments t and f can be set by (1) manually setting the start point (2) using the string ‘current’ to leave the current setting a lone (3) ‘reset’, which clears the startpoint and (4) None, which will be changed to ‘current’ when the other is set to a number or ‘rest’ if both are set to None.
• t – see t
• nearest (bool) –

  Shifting the startpoint can only be done by an integral number of datapoints (i.e. an integral number of dwell times, dt, in the time domain or integral number of df in the frequency domain). While it is possible to shift by a non-integral number of datapoints, this is done by applying a phase-dependent shift in the inverse domain. Applying such a axis-dependent shift can have vary unexpected effects if the data in the inverse domain is aliased, and is therefore heavily discouraged. (For example, consider what happens if we attempt to apply a frequency-dependent phase shift to data where a peak at 110 Hz is aliased and appears at the 10 Hz position.)

  Setting nearest to True will choose a startpoint at the closest integral datapoint to what you have specified.

  Setting nearest to False will explicitly override the safeties – essentially telling the code that you know the data is not aliased in the inverse domain and/or are willing to deal with the consequences.

ft_state_to_str(*axes)

Return a string that lists the FT domain for the given axes.

\(u\) refers to the original domain (typically time) and \(v\) refers to the FT’d domain (typically frequency) If no axes are passed as arguments, it does this for all axes.

ftshift(axis, value)

FT-based shift. Currently only works in time domain.

This was previously made obsolete, but is now a demo of how to use the ft properties. It is not the most efficient way to do this.

get_covariance()

this returns the covariance matrix of the data

get_error(*args)

get a copy of the errors either set_error(‘axisname’,error_for_axis) or set_error(error_for_data)

get_ft_prop(axis, propname=None)

Gets the FT property given by propname. For both setting and getting, None is equivalent to an unset value if no propname is given, this just sets the FT property, which tells if a dimension is frequency or time domain

get_plot_color()

get_prop(propname=None)

return arbitrary ND-data properties (typically acquisition parameters etc.) by name (propname)

In order to allow ND-data to store acquisition parameters and other info that accompanies the data, but might not be structured in a gridded format, nddata instances always have a other_info dictionary attribute, which stores these properties by name.

If the property doesn’t exist, this returns None.

Parameters:propname (str) –

Name of the property that you’re want returned. If this is left out or set to “None” (not given), the names of the available properties are returned. If no exact match is found, and propname contains a . or * or [, it’s assumed to be a regular expression. If several such matches are found, the error message is informative.

Todo

have it recursively search dictionaries (e.g. bruker acq)

Returns: Return type:The value of the property (can by any type) or None if the property doesn’t exist.

get_units(*args)

getaxis(axisname)

getaxisshape(axisname)

gnuplot_save(filename)

hdf5_write(h5path, directory='.')

Write the nddata to an HDF5 file.

h5path is the name of the file followed by the node path where you want to put it – it does not include the directory where the file lives. The directory can be passed to the directory argument.

You can use either find_file() or nddata_hdf5() to read the data, as shown below. When reading this, please note that HDF5 files store multiple datasets, and each is named (here, the name is test_data).

from pyspecdata import *
init_logging('debug')
a = nddata(r_[0:5:10j], 'x')
a.name('test_data')
try:
    a.hdf5_write('example.h5',getDATADIR(exp_type='Sam'))
except:
    print("file already exists, not creating again -- delete the file or node if wanted")
# read the file by the "raw method"
b = nddata_hdf5('example.h5/test_data',
        getDATADIR(exp_type='Sam'))
print("found data:",b)
# or use the find file method
c = find_file('example.h5', exp_type='Sam',
        expno='test_data')
print("found data:",c)

Parameters:

• h5path (str) – The name of the file followed by the node path where you want to put it – it does not include the directory where the file lives. (Because HDF5 files contain an internal directory-like group structure.)
• directory (str) – the directory where the HDF5 file lives.

histogram(**kwargs)

human_units()

ift(axes, n=False, tolerance=1e-05, verbose=False, **kwargs)

This performs an inverse Fourier transform along the axes identified by the string or list of strings axes.

It adjusts normalization and units so that the result conforms to

\(s(t)=t_{dw} \int_{x_{min}}^{x_{max}} \tilde{s}(f) e^{i 2 \pi f t} df\)

Where \(t_{dw}=\frac{1}{\Delta f}\), is the dwell time (with \(\Delta f\) the spectral width).

Why do we do this? Note that while the analytical integral this corresponds to is normalized, performing ft() followed by ift() on a discrete sequence is NOT completely invertible (due to integration of the implied comb function??), and would require division by a factor of \(\Delta f\) (the spectral width) in order to retrieve the original function

pre-IFT, we use the axis to cyclically permute \(f=0\) to the first index

post-IFT, we assume that the data has previously been FT’d If this is the case, passing shift=True will cause an error If this is not the case, passing shift=True generates a standard ifftshift shift=None will choose True, if and only if this is not the case

Parameters:pad (int or boolean) –

pad specifies a zero-filling. If it’s a number, then it gives the length of the zero-filled dimension. If it is just True, then the size of the dimension is determined by rounding the dimension size up to the nearest integral power of 2. It uses the start_time ft property to determine the start of the axis. To do this, it assumes that it is a stationary signal (convolved with infinite comb function). The value of start_time can differ from by a non-integral multiple of \(\Delta t\), though the routine will check whether or not it is safe to do this.

..note ::

In the code, this is controlled by p2_post (the integral \(\Delta t\) and p2_post_discrepancy – the non-integral.

imag

Return the imag component of the data

indices(axis_name, values)

Return a string of indeces that most closely match the axis labels corresponding to values. Filter them to make sure they are unique.

inhomog_coords(direct_dim, indirect_dim, tolerance=1e-05, method='linear', plot_name=None, fl=None, debug_kwargs={})

Apply the “inhomogeneity transform,” which rotates the data by \(45^{\circ}\), and then mirrors the portion with \(t_2<0\) in order to transform from a \((t_1,t_2)\) coordinate system to a \((t_{inh},t_{homog})\) coordinate system.

Parameters:

• direct_dim (str) – Label of the direct dimension (typically \(t_2\))
• indirect_dim (str) – Label of the indirect dimension (typically \(t_1\))
• method ('linear', 'fourier') – The interpolation method used to rotate the data and to mirror the data. Note currently, both use a fourier-based mirroring method.
• plot_name (str) – the base name for the plots that are generated
• fl (figlist_var) –
• debug_kwargs (dict) –

  with keys:

  correct_overlap:  if False, doesn’t correct for the overlap error that occurs during mirroring

integrate(thisaxis, backwards=False, cumulative=False)

Performs an integration – which is similar to a sum, except that it takes the axis into account, i.e., it performs: \(\int f(x) dx\) rather than \(\sum_i f(x_i)\)

Gaussian quadrature, etc, is planned for a future version.

Parameters:

• thisaxis – The dimension that you want to integrate along
• cumulative (boolean (default False)) – Perform a cumulative integral (analogous to a cumulative sum) – e.g. for ESR.
• backwards (boolean (default False)) – for cumulative integration – perform the integration backwards

interp(axis, axisvalues, past_bounds=None, return_func=False, **kwargs)

interpolate data values given axis values

Parameters:return_func (boolean) – defaults to False. If True, it returns a function that accepts axis values and returns a data value.

invinterp(axis, values, **kwargs)

interpolate axis values given data values

item()

like numpy item – returns a number when zero-dimensional

labels(*args)

label the dimensions, given in listofstrings with the axis labels given in listofaxes – listofaxes must be a numpy array; you can pass either a dictionary or a axis name (string)/axis label (numpy array) pair

like(value)

provide “zeros_like” and “ones_like” functionality

Parameters:value (float) – 1 is “ones_like” 0 is “zeros_like”, etc.

linear_shear(along_axis, propto_axis, shear_amnt, zero_fill=True)

the linear shear – see self.shear for documentation

matchdims(other)

add any dimensions to self that are not present in other

matrices_3d(also1d=False, invert=False, max_dimsize=1024, downsample_self=False)

returns X,Y,Z,x_axis,y_axis matrices X,Y,Z, are suitable for a variety of mesh plotting, etc, routines x_axis and y_axis are the x and y axes

max()

mayavi_surf()

use the mayavi surf function, assuming that we’ve already loaded mlab during initialization

mean(*args, **kwargs)

Take the mean and (optionally) set the error to the standard deviation

Parameters:std (bool) – whether or not to return the standard deviation as an error

mean_all_but(listofdims)

take the mean over all dimensions not in the list

mean_nopop(axis)

mean_weighted(axisname)

perform the weighted mean along axisname (use $sigma$ from $sigma = $self.get_error() do generate $1/sigma$ weights) for now, it clears the error of self, though it would be easy to calculate the new error, since everything is linear

unlike other functions, this creates working objects that are themselves nddata objects this strategy is easier than coding out the raw numpy math, but probably less efficient

meshplot(stride=None, alpha=1.0, onlycolor=False, light=None, rotation=None, cmap=<matplotlib.colors.LinearSegmentedColormap object>, ax=None, invert=False, **kwargs)

takes both rotation and light as elevation, azimuth only use the light kwarg to generate a black and white shading display

min()

mkd(*arg, **kwargs)

make dictionary format

multimin(minfunc, axisname, filterwidth, numberofmins)

name(*arg)

args: .name(newname) –> Name the object (for storage, etc) .name() –> Return the name

nnls(dimname, newaxis_dict, kernel_func, l=0)

Perform regularized non-negative least-squares “fit” on self.

Capable of solving for solution in 1 or 2 dimensions.

We seek to minimize \(Q = \| Ax - b \|_2 + \|\lambda x\|_2\) in order to obtain solution vector \(x\) subject to non-negativity constraint given input matrix \(A\), the kernel, and input vector \(b\), the data.

The first term assesses agreement between the fit \(Ax\) and the data \(b\), and the second term accounts for noise with the regularization parameter \(\lambda\) according to Tikhonov regularization.

To perform regularized minimization in 2 dimensions, set l to :str:`BRD` and provide a tuple of parameters :str:`dimname`, :nddata:`newaxis_dict`, and :function:`kernel_func`. Algorithm described in Venkataramanan et al. 2002 is performed which determines optimal \(\lambda\) for the data (DOI:10.1109/78.995059).

See: Wikipedia page on NNLS, Wikipedia page on Tikhonov regularization

Parameters:

• dimname (str) – Name of the “data” dimension that is to be replaced by a distribution (the “fit” dimension); e.g. if you are regularizing a set of functions \(\exp(-\tau*R_1)\), then this is \(\tau\)
• newaxis_dict (dict or nddata) – a dictionary whose key is the name of the “fit” dimension (\(R_1\) in the example above) and whose value is an array with the new axis labels. OR this can be a 1D nddata – if it has an axis, the axis will be used to create the fit axis; if it has no axis, the data will be used
• kernel_func (function) – a function giving the kernel for the regularization. The first argument is the “data” variable and the second argument is the “fit” variable (in the example above, this would be something like lambda x,y: exp(-x*y))
• l (double (default 0) or str) – the regularization parameter \(lambda\) – if this is set to 0, the algorithm reverts to standard nnls. If this is set to :str:`BRD`, then algorithm expects tuple of each parameter described above in order to perform a 2-dimensional fit.

Returns:

The regularized result. For future use, both the kernel (as an nddata, in a property called “nnls_kernel”) and the residual (as an nddata, in a property called “nnls_residual”) are stored as properties of the nddata. The regularized dimension is always last (innermost). If :str:`BRD` is specified, then the individual, uncompressed kernels \(K_{1}\) and \(K_{2}\) are returned as properties of the nddata “K1” and “K2” respectively. The number of singular values used to compressed each kernel is returned in properties of the nddata called, respectively, “s1” and “s2”.

Return type:

self

normalize(axis, first_figure=None)

oldtimey(alpha=0.5, ax=None, linewidth=None, sclinewidth=20.0, light=True, rotation=None, invert=False, **kwargs)

plot_labels(labels, fmt=None, **kwargs_passed)

this only works for one axis now

polyfit(axis, order=1, force_y_intercept=None)

polynomial fitting routine – return the coefficients and the fit ..note:

later, should probably branch this off as a new type of fit class

..warning:

for some reason, this version doesn’t use orthogonal polynomials, as the numpy routine does – we had diagnosed and determined that that creates noticeably different results, so fix that here.

Parameters:

• axis (str) – name of the axis that you want to fit along (not sure if this is currently tested for multi-dimensional data, but the idea should be that multiple fits would be returned.)
• order (int) – the order of the polynomial to be fit
• force_y_intercept (double or None) – force the y intercept to a particular value (e.g. 0)

Returns:

• c (ndarray) – a standard numpy array containing the coefficients (in ascending polynomial order)
• formult (nddata) – an nddata containing the result of the fit

popdim(dimname)

random_mask(axisname, threshold=None, inversion=False)

generate a random mask with about ‘threshold’ of the points thrown out

real

Return the real component of the data

register_axis(arg, nearest=None)

Interpolate the data so that the given axes are in register with a set of specified values. Does not change the spacing of the axis labels.

It finds the axis label position that is closest to the values given in arg, then interpolates (Fourier/sinc method) the data onto a new, slightly shifted, axis that passes exactly through the value given. To do this, it uses .ft_clear_startpoints() and uses .set_ft_prop() to override the “not aliased” flag.

Parameters:

• arg (dict (key,value = str,double)) – A list of the dimensions that you want to place in register, and the values you want them registered to.
• nearest (bool, optional) – Passed through to ft_clear_startpoints

rename(previous, new)

reorder(*axes, **kwargs)

Reorder the dimensions the first arguments are a list of dimensions

Parameters:

• *axes (str) – Accept any number of arguments that gives the dimensions, in the order that you want thee.
• first (bool) – (default True) Put this list of dimensions first, while False puts them last (where they then come in the order given).

replicate_units(other)

repwlabels(axis)

retaxis(axisname)

run(*args)

run a standard numpy function on the nddata:

d.run(func,'axisname') will run function func (e.g. a lambda function) along axis named ‘axisname’

d.run(func) will run function func on the data

in general: if the result of func reduces a dimension size to 1, the ‘axisname’ dimension will be “popped” (it will not exist in the result) – if this is not what you want, use run_nopop

run_avg(thisaxisname, decimation=20, centered=False)

a simple running average

run_nopop(func, axis)

runcopy(*args)

secsy_transform(direct_dim, indirect_dim, has_indirect=True, method='fourier', truncate=True)

Shift the time-domain data backwards by the echo time.

As opposed to secsy_transform_manual, this calls on on skew, rather than directly manipulating the phase of the function, which can lead to aliasing.

Parameters:

• has_indirect (bool) –

  (This option is largely specific to data loaded by acert_hdf5)

  Does the data actually have an indirect dimension? If not, assume that there is a constant echo time, that can be retrieved with .get_prop('te').

• truncate (bool) – If this is set, register_axis <pyspecdata.axis_manipulation.register_axis> to \(t_{direct}=0\), and then throw out the data for which \(t_{direct}<0\).
• method (str) – The shear method (linear or fourier).

secsy_transform_manual(direct_dim, indirect_dim, has_indirect=True, truncate=False)

Shift the time-domain data backwards by the echo time. As opposed to secsy_transform, this directlly manipulates the phase of the function, rather than calling on skew.

Parameters:

• has_indirect (bool) –

  (This option is largely specific to data loaded by acert_hdf5)

  Does the data actually have an indirect dimension? If not, assume that there is a constant echo time, that can be retrieved with .get_prop('te').

• truncate (bool) – If this is set, register_axis <pyspecdata.axis_manipulation.register_axis> to \(t_{direct}=0\), and then throw out the data for which \(t_{direct}<0\).

set_error(*args)

set the errors: either

set_error(‘axisname’,error_for_axis) or set_error(error_for_data)

error_for_data can be a scalar, in which case, all the data errors are set to error_for_data

Todo

several options below – enumerate them in the documentation

set_ft_prop(axis, propname=None, value=True)

Sets the FT property given by propname. For both setting and getting, None is equivalent to an unset value if propname is a boolean, and value is True (the default), it’s assumed that propname is actually None, and that value is set to the propname argument (this allows us to set the FT property more easily)

set_plot_color(thiscolor)

set_prop(*args)

set a ‘property’ of the nddata This is where you can put all unstructured information (e.g. experimental parameters, etc)

set_to(otherinst)

Set data inside the current instance to that of the other instance.

Goes through the list of attributes specified in copy, and assigns them to the element of the current instance.

This is to be used:

• for constructing classes that inherit nddata with additional methods.
• for overwriting the current data with the result of a slicing operation

set_units(*args)

setaxis(*args)

set or alter the value of the coordinate axis

Can be used in one of several ways:

• self.setaxis('axisname', values): just sets the values

• self.setaxis('axisname', '#'): just

  number the axis in numerically increasing order (e.g. if you have smooshed it from a couple other dimensions.)

• self.fromaxis('axisname',inputfunc): take the existing function, apply inputfunc, and replace
• self.fromaxis(inputsymbolic): Evaluate inputsymbolic and load the result into the axes, appropriately

shear(along_axis, propto_axis, shear_amnt, zero_fill=True, start_in_conj=False, method='linear')

Shear the data \(s\):

\(s(x',y,z) = s(x+ay,y,z)\)

where \(x\) is the altered_axis and \(y\) is the propto_axis. (Actually typically 2D, but \(z\) included just to illustrate other dimensions that aren’t involved)

Parameters:

• method ({'fourier','linear'}) –

  fourier

  Use the Fourier shift theorem (i.e., sinc interpolation). A shear is equivalent to the following in the conjugate domain:

  ..math: tilde{s}(f_x,f’_y,z) = tilde{s}(f_x,f_y-af_x,f_z)

  Because of this, the algorithm also automatically extend`s the data in `f_y axis. Equivalently, it increases the resolution (decreases the interval between points) in the propto_axis dimension. This prevents aliasing in the conjugate domain, which will corrupt the data w.r.t. successive transformations. It does this whether or not zero_fill is set (zero_fill only controls filling in the “current” dimension)

  linear

  Use simple linear interpolation.

• altered_axis (str) – The coordinate for which data is altered, i.e. ..math: x such that ..math: f(x+ay,y).
• by_amount (double) – The amount of the shear (..math: a in the previous)
• propto_axis (str) – The shift along the altered_axis dimension is proportional to the shift along propto_axis. The position of data relative to the propto_axis is not changed. Note that by the shift theorem, in the frequency domain, an equivalent magnitude, opposite sign, shear is applied with the propto_axis and altered_axis dimensions flipped.
• start_in_conj ({False, True}, optional) –

  Defaults to False

  For efficiency, one can replace a double (I)FT call followed by a shear call with a single shear call where start_in_conj is set.

  self before the call is given in the conjugate domain (i.e., \(f\) vs. \(t\)) along both dimensions from the one that’s desired. This means: (1) self after the function call transformed into the conjugate domain from that before the call and (2) by_amount, altered_axis, and propto_axis all refer to the shear in the conjugate domain that the data is in at the end of the function call.

smoosh(dimstocollapse, dimname=0, noaxis=False)

Collapse (smoosh) multiple dimensions into one dimension.

Parameters:

• dimstocollapse (list of strings) – the dimensions you want to collapse to one result dimension
• dimname (None, string, integer (default 0)) –

  if dimname is:

  • None: create a new (direct product) name,
  • a number: an index to the dimstocollapse list. The resulting smooshed dimension will be named dimstocollapse[dimname]. Because the default is the number 0, the new dimname will be the first dimname given in the list.
  • a string: the name of the resulting smooshed dimension (can be part of the dimstocollapse list or not)
• noaxis (bool) – if set, then just skip calculating the axis for the new dimension, which otherwise is typically a complicated record array

Returns:

• self (nddata) – the dimensions dimstocollapse are smooshed into a single dimension, whose name is determined by dimname. The axis for the resulting, smooshed dimension is a structured array consisting of two fields that give the labels along the original axes.
• ..todo:: – when we transition to axes that are stored using a slice/linspace-like format, allow for smooshing to determine a new axes that is standard (not a structured array) and that increases linearly.

sort(axisname, reverse=False)

sort_and_xy()

squeeze(return_dropped=False)

squeeze singleton dimensions

Parameters:return_dropped (bool (default False)) – return a list of the dimensions that were dropped as a second argument Returns:

• self
• return_dropped (list) – (optional, only if return_dropped is True)

sum(axes)

sum_nopop(axes)

to_ppm()

Function that converts from Hz to ppm using Bruker parameters

Todo

Figure out what the units of PHC1 in Topspin are (degrees per what??), and apply those as well.

make this part of an inherited bruker class

unitify_axis(axis_name, is_axis=True)

this just generates an axis label with appropriate units

units_texsafe(*args)

unset_prop(arg)

remove a ‘property’

want_to_prospa_decim_correct = False

waterfall(alpha=0.3, ax=None, rotation=None, color='b', edgecolor='k')

class pyspecdata.nddata_hdf5(pathstring, directory='.')

Bases: pyspecdata.core.nddata

pyspecdata.ndgrid(*input)

class pyspecdata.ndshape(*args)

Bases: pyspecdata.ndshape.ndshape_base

The ndshape class, including the allocation method

alloc(dtype='complex128', labels=False, format=0)

Use the shape object to allocate an empty nddata object.

Parameters:

• labels – Needs documentation
• format (0, 1, or None) – What goes in the allocated array. None uses numpy empty.

class pyspecdata.ndshape_base(*args)

Bases: object

The base ndshape class, which doesn’t include an allocation method.

axn(axis)

return the number for the axis with the name “axis”

copy()

matchdims(arg)

returns shape with [not in self, len 1] + [overlapping dims between arg + self] + [not in arg] –> this is better accomplished by using sets as I do in the matchdims below

pop(label)

remove a dimension

rename(before, after)

rename a dimension

pyspecdata.newcol_rec(A, new_dtypes)

add new, empty (i.e. random numbers) fields to A, as given by new_dtypes –> note that there are deeply nested numpy functions to do this, but the options are confusing, and I think the way these work is efficient

pyspecdata.nextfigure(figurelist, name)

obsolete – now use class

pyspecdata.nnls_regularized(A, b, l=0, maxiter=None)

Solve math:argmin_x || Ax - b ||_2^2 + lambda^2 ||x||_2^2 for x>=0. This is a wrapper for a FORTRAN non-negative least squares solver, with regularization (added by stacking $A$ on top an identity matrix times $lambda$ and $b$ on top of a matching array of zero.

Parameters:

• A (ndarray) – Matrix A as shown above.
• b (ndarray) – Right-hand side vector.
• l (double (default 0)) – \(lambda\) – if this is set to 0, the algorithm reverts to standard nnls (rather than stacking on top of two zero matrices for no reason)
• maxiter (int, optional) – Maximum number of iterations, optional. Default is 3 * A.shape[1].

Returns:

• x (ndarray) – Solution vector.
• rnorm (float) – The residual, || Ax-b ||_2.

Notes

The FORTRAN code was published in the book below. The algorithm is an active set method. It solves the KKT (Karush-Kuhn-Tucker) conditions for the non-negative least squares problem.

This was adapted from the source distributed with scipy – see scipy for relevant licensing.

References

Lawson C., Hanson R.J., (1987) Solving Least Squares Problems, SIAM

pyspecdata.normal_attrs(obj)

pyspecdata.obs(*x)

pyspecdata.obsn(*x)

pyspecdata.othergridandtick(ax, rotation=(0, 0), precision=(2, 2), labelstring=('', ''), gridcolor=None, y=True, x=True, spines=None)

pyspecdata.pinvr(C, alpha)

pyspecdata.plot(*args, **kwargs)

The base plotting function that wraps around matplotlib to do a couple convenient things.

Parameters:

• label_format_string (str) – If supplied, it formats the values of the other dimension to turn them into a label string.
• human_units (bool) –

pyspecdata.plot_color_counter(*args, **kwargs)

Try not to use this function any more – the version-to-version support for capturing and setting color cycles in matplotlib is very very bad. (And, the cycler object in newer versions of matplolib is confusing.) So, just import cycle from itertools, and use it to build a cycle that you directly call to set your properties.

Note

previous description:

if passed an argument: make it so that the next line will have the properties given by the argument

if not passed an argument: just return the current plot properties,so that I can cycle back to it

pyspecdata.plot_label_points(x, y, labels, **kwargs_passed)

pyspecdata.plot_updown(data, axis, color1, color2, symbol='', **kwargs)

pyspecdata.process_kwargs(listoftuples, kwargs, pass_through=False, as_attr=False)

This function allows dynamically processed (i.e. function definitions with **kwargs) kwargs (keyword arguments) to be dealt with in a fashion more like standard kwargs. The defaults set in listoftuples are used to process kwargs, which are then returned as a set of values (that are set to defaults as needed).

Note that having kwargs as an explicit argument avoids errors where the user forgets to pass the kwargs.

Parameters:

• kwargs (**dictionary) – The keyword arguments that you want to process.
• listoftuples (list of tuple pairs) – Tuple pairs, consisting of ('param_name',param_value), that give the default values for the various parameters.
• pass_through (bool) – Defaults to False. If it’s true, then it’s OK not to process all the kwargs here. In that case, the used kwargs are popped out of the dictionary, and you are expected to pass the unprocessed values (in the dictionary after the call) on to subsequent processing. Importantly, you should always end with a pass_through`=`False call of this function, or by passing **kwargs to a standard function in the standard way. Otherwise it’s possible for the user to pass kwargs that are never processed!
• as_attr (bool, object) – Defaults to False. If not False, it must be an object whose attributes are set to the value of the respective kwargs.
• return (tuple) – It’s expected that the output is assigned to variables with the exact same names as the string in the first half of the tuples, in the exact same order. These parameters will then be set to the appropriate values.

pyspecdata.prospa_t1_info(file)

pyspecdata.rc(*args, **kwargs)

class pyspecdata.rclass

Bases: object

pyspecdata.redim_C_to_F(a)

see redim_F_to_C

pyspecdata.redim_F_to_C(a)

the following creates a C array, reversing the apparent order of dimensions, while preserving the order in memory

pyspecdata.reformat_exp(arg)

reformat scientific notation in a nice latex format – used in both pdf and jupyter notebooks

pyspecdata.rename_fields(base, namemapper)

Rename the fields from a flexible-datatype ndarray or recarray.

Nested fields are supported.

Parameters:

• base (ndarray) – Input array whose fields must be modified.
• namemapper (dictionary) – Dictionary mapping old field names to their new version.

Examples

>>> from numpy.lib import recfunctions as rfn
>>> a = np.array([(1, (2, [3.0, 30.])), (4, (5, [6.0, 60.]))],
...   dtype=[('a', int),('b', [('ba', float), ('bb', (float, 2))])])
>>> rfn.rename_fields(a, {'a':'A', 'bb':'BB'})
array([(1, (2., [ 3., 30.])), (4, (5., [ 6., 60.]))],
      dtype=[('A', '<i8'), ('b', [('ba', '<f8'), ('BB', '<f8', (2,))])])

pyspecdata.render_matrix(arg, format_code='%.4g')

return latex string representing 2D matrix

pyspecdata.reorder_rec(myarray, listofnames, first=True)

pyspecdata.scipy_griddata(points, values, xi, method='linear', fill_value=nan, rescale=False)

Interpolate unstructured D-D data.

Parameters:

• points (2-D ndarray of floats with shape (n, D), or length D tuple of 1-D ndarrays with shape (n,)) – Data point coordinates.
• values (ndarray of float or complex, shape (n,)) – Data values.
• xi (2-D ndarray of floats with shape (m, D), or length D tuple of ndarrays broadcastable to the same shape.) – Points at which to interpolate data.
• method ({'linear', 'nearest', 'cubic'}, optional) –

  Method of interpolation. One of

  nearest

  return the value at the data point closest to the point of interpolation. See NearestNDInterpolator for more details.

  linear

  tessellate the input point set to N-D simplices, and interpolate linearly on each simplex. See LinearNDInterpolator for more details.

  cubic (1-D)

  return the value determined from a cubic spline.

  cubic (2-D)

  return the value determined from a piecewise cubic, continuously differentiable (C1), and approximately curvature-minimizing polynomial surface. See CloughTocher2DInterpolator for more details.

• fill_value (float, optional) – Value used to fill in for requested points outside of the convex hull of the input points. If not provided, then the default is nan. This option has no effect for the ‘nearest’ method.
• rescale (bool, optional) –

  Rescale points to unit cube before performing interpolation. This is useful if some of the input dimensions have incommensurable units and differ by many orders of magnitude.

  New in version 0.14.0.

Returns:

Array of interpolated values.

Return type:

ndarray

Notes

New in version 0.9.

Examples

Suppose we want to interpolate the 2-D function

>>> def func(x, y):
...     return x*(1-x)*np.cos(4*np.pi*x) * np.sin(4*np.pi*y**2)**2

on a grid in [0, 1]x[0, 1]

>>> grid_x, grid_y = np.mgrid[0:1:100j, 0:1:200j]

but we only know its values at 1000 data points:

>>> points = np.random.rand(1000, 2)
>>> values = func(points[:,0], points[:,1])

This can be done with griddata – below we try out all of the interpolation methods:

>>> from scipy.interpolate import griddata
>>> grid_z0 = griddata(points, values, (grid_x, grid_y), method='nearest')
>>> grid_z1 = griddata(points, values, (grid_x, grid_y), method='linear')
>>> grid_z2 = griddata(points, values, (grid_x, grid_y), method='cubic')

One can see that the exact result is reproduced by all of the methods to some degree, but for this smooth function the piecewise cubic interpolant gives the best results:

>>> import matplotlib.pyplot as plt
>>> plt.subplot(221)
>>> plt.imshow(func(grid_x, grid_y).T, extent=(0,1,0,1), origin='lower')
>>> plt.plot(points[:,0], points[:,1], 'k.', ms=1)
>>> plt.title('Original')
>>> plt.subplot(222)
>>> plt.imshow(grid_z0.T, extent=(0,1,0,1), origin='lower')
>>> plt.title('Nearest')
>>> plt.subplot(223)
>>> plt.imshow(grid_z1.T, extent=(0,1,0,1), origin='lower')
>>> plt.title('Linear')
>>> plt.subplot(224)
>>> plt.imshow(grid_z2.T, extent=(0,1,0,1), origin='lower')
>>> plt.title('Cubic')
>>> plt.gcf().set_size_inches(6, 6)
>>> plt.show()

pyspecdata.search_filename(searchstring, exp_type, print_result=True, unique=False)

Use regular expression searchstring to find a file inside the directory indicated by exp_type (For information on how to set up the file searching mechanism, see register_directory()).

Parameters:

• searchstring (str) – Most commonly, this is just a fragment of the file name, with any literal *, ., or ? characters preceded by a backslash. More generally, it is a regular expression, where .*searchstring.* matches a filename inside the directory appropriate for exp_type.
• exp_type (str) – Since the function assumes that you have different types of experiments sorted into different directories, this argument specifies the type of experiment see getDATADIR() for more info.
• unique (boolean (default False)) – If true, then throw an error unless only one file is found.

pyspecdata.sech(x)

pyspecdata.showtype(x)

pyspecdata.signature(obj, *, follow_wrapped=True)

Get a signature object for the passed callable.

pyspecdata.spectrogram(waveform, f_start, f_stop, npoints_fdom=40, tdom_div=2)

pyspecdata.sqrt(arg)

pyspecdata.strm(*args)

class pyspecdata.subplot_dim(firstdim, seconddim)

Bases: object

set(args, x='', g=True, y='', t='', a='')

pyspecdata.sympy_diff(f, *symbols, **kwargs)

Differentiate f with respect to symbols.

This is just a wrapper to unify .diff() and the Derivative class; its interface is similar to that of integrate(). You can use the same shortcuts for multiple variables as with Derivative. For example, diff(f(x), x, x, x) and diff(f(x), x, 3) both return the third derivative of f(x).

You can pass evaluate=False to get an unevaluated Derivative class. Note that if there are 0 symbols (such as diff(f(x), x, 0), then the result will be the function (the zeroth derivative), even if evaluate=False.

Examples

>>> from sympy import sin, cos, Function, diff
>>> from sympy.abc import x, y
>>> f = Function('f')

>>> diff(sin(x), x)
cos(x)
>>> diff(f(x), x, x, x)
Derivative(f(x), (x, 3))
>>> diff(f(x), x, 3)
Derivative(f(x), (x, 3))
>>> diff(sin(x)*cos(y), x, 2, y, 2)
sin(x)*cos(y)

>>> type(diff(sin(x), x))
cos
>>> type(diff(sin(x), x, evaluate=False))
<class 'sympy.core.function.Derivative'>
>>> type(diff(sin(x), x, 0))
sin
>>> type(diff(sin(x), x, 0, evaluate=False))
sin

>>> diff(sin(x))
cos(x)
>>> diff(sin(x*y))
Traceback (most recent call last):
...
ValueError: specify differentiation variables to differentiate sin(x*y)

Note that diff(sin(x)) syntax is meant only for convenience in interactive sessions and should be avoided in library code.

References

http://reference.wolfram.com/legacy/v5_2/Built-inFunctions/AlgebraicComputation/Calculus/D.html

See also

Derivative()

idiff()

computes the derivative implicitly

pyspecdata.sympy_expr

alias of sympy.core.expr.Expr

pyspecdata.sympy_latex(expr, full_prec=False, min=None, max=None, fold_frac_powers=False, fold_func_brackets=False, fold_short_frac=None, inv_trig_style='abbreviated', itex=False, ln_notation=False, long_frac_ratio=None, mat_delim='[', mat_str=None, mode='plain', mul_symbol=None, order=None, symbol_names=None, root_notation=True, mat_symbol_style='plain', imaginary_unit='i', gothic_re_im=False, decimal_separator='period', perm_cyclic=True, parenthesize_super=True)

Convert the given expression to LaTeX string representation.

Parameters:

• full_prec (boolean, optional) – If set to True, a floating point number is printed with full precision.
• fold_frac_powers (boolean, optional) – Emit ^{p/q} instead of ^{\frac{p}{q}} for fractional powers.
• fold_func_brackets (boolean, optional) – Fold function brackets where applicable.
• fold_short_frac (boolean, optional) – Emit p / q instead of \frac{p}{q} when the denominator is simple enough (at most two terms and no powers). The default value is True for inline mode, False otherwise.
• inv_trig_style (string, optional) – How inverse trig functions should be displayed. Can be one of abbreviated, full, or power. Defaults to abbreviated.
• itex (boolean, optional) – Specifies if itex-specific syntax is used, including emitting $$...$$.
• ln_notation (boolean, optional) – If set to True, \ln is used instead of default \log.
• long_frac_ratio (float or None, optional) – The allowed ratio of the width of the numerator to the width of the denominator before the printer breaks off long fractions. If None (the default value), long fractions are not broken up.
• mat_delim (string, optional) – The delimiter to wrap around matrices. Can be one of [, (, or the empty string. Defaults to [.
• mat_str (string, optional) – Which matrix environment string to emit. smallmatrix, matrix, array, etc. Defaults to smallmatrix for inline mode, matrix for matrices of no more than 10 columns, and array otherwise.
• mode (string, optional) – Specifies how the generated code will be delimited. mode can be one of plain, inline, equation or equation*. If mode is set to plain, then the resulting code will not be delimited at all (this is the default). If mode is set to inline then inline LaTeX $...$ will be used. If mode is set to equation or equation*, the resulting code will be enclosed in the equation or equation* environment (remember to import amsmath for equation*), unless the itex option is set. In the latter case, the $$...$$ syntax is used.
• mul_symbol (string or None, optional) – The symbol to use for multiplication. Can be one of None, ldot, dot, or times.
• order (string, optional) – Any of the supported monomial orderings (currently lex, grlex, or grevlex), old, and none. This parameter does nothing for Mul objects. Setting order to old uses the compatibility ordering for Add defined in Printer. For very large expressions, set the order keyword to none if speed is a concern.
• symbol_names (dictionary of strings mapped to symbols, optional) – Dictionary of symbols and the custom strings they should be emitted as.
• root_notation (boolean, optional) – If set to False, exponents of the form 1/n are printed in fractonal form. Default is True, to print exponent in root form.
• mat_symbol_style (string, optional) – Can be either plain (default) or bold. If set to bold, a MatrixSymbol A will be printed as \mathbf{A}, otherwise as A.
• imaginary_unit (string, optional) – String to use for the imaginary unit. Defined options are “i” (default) and “j”. Adding “r” or “t” in front gives \mathrm or \text, so “ri” leads to \mathrm{i} which gives mathrm{i}.
• gothic_re_im (boolean, optional) – If set to True, Re and Im is used for re and im, respectively. The default is False leading to operatorname{re} and operatorname{im}.
• decimal_separator (string, optional) – Specifies what separator to use to separate the whole and fractional parts of a floating point number as in 2.5 for the default, period or 2{,}5 when comma is specified. Lists, sets, and tuple are printed with semicolon separating the elements when comma is chosen. For example, [1; 2; 3] when comma is chosen and [1,2,3] for when period is chosen.
• parenthesize_super (boolean, optional) – If set to False, superscripted expressions will not be parenthesized when powered. Default is True, which parenthesizes the expression when powered.
• min (Integer or None, optional) – Sets the lower bound for the exponent to print floating point numbers in fixed-point format.
• max (Integer or None, optional) – Sets the upper bound for the exponent to print floating point numbers in fixed-point format.

Notes

Not using a print statement for printing, results in double backslashes for latex commands since that’s the way Python escapes backslashes in strings.

>>> from sympy import latex, Rational
>>> from sympy.abc import tau
>>> latex((2*tau)**Rational(7,2))
'8 \\sqrt{2} \\tau^{\\frac{7}{2}}'
>>> print(latex((2*tau)**Rational(7,2)))
8 \sqrt{2} \tau^{\frac{7}{2}}

Examples

>>> from sympy import latex, pi, sin, asin, Integral, Matrix, Rational, log
>>> from sympy.abc import x, y, mu, r, tau

Basic usage:

>>> print(latex((2*tau)**Rational(7,2)))
8 \sqrt{2} \tau^{\frac{7}{2}}

mode and itex options:

>>> print(latex((2*mu)**Rational(7,2), mode='plain'))
8 \sqrt{2} \mu^{\frac{7}{2}}
>>> print(latex((2*tau)**Rational(7,2), mode='inline'))
$8 \sqrt{2} \tau^{7 / 2}$
>>> print(latex((2*mu)**Rational(7,2), mode='equation*'))
\begin{equation*}8 \sqrt{2} \mu^{\frac{7}{2}}\end{equation*}
>>> print(latex((2*mu)**Rational(7,2), mode='equation'))
\begin{equation}8 \sqrt{2} \mu^{\frac{7}{2}}\end{equation}
>>> print(latex((2*mu)**Rational(7,2), mode='equation', itex=True))
$$8 \sqrt{2} \mu^{\frac{7}{2}}$$
>>> print(latex((2*mu)**Rational(7,2), mode='plain'))
8 \sqrt{2} \mu^{\frac{7}{2}}
>>> print(latex((2*tau)**Rational(7,2), mode='inline'))
$8 \sqrt{2} \tau^{7 / 2}$
>>> print(latex((2*mu)**Rational(7,2), mode='equation*'))
\begin{equation*}8 \sqrt{2} \mu^{\frac{7}{2}}\end{equation*}
>>> print(latex((2*mu)**Rational(7,2), mode='equation'))
\begin{equation}8 \sqrt{2} \mu^{\frac{7}{2}}\end{equation}
>>> print(latex((2*mu)**Rational(7,2), mode='equation', itex=True))
$$8 \sqrt{2} \mu^{\frac{7}{2}}$$

Fraction options:

>>> print(latex((2*tau)**Rational(7,2), fold_frac_powers=True))
8 \sqrt{2} \tau^{7/2}
>>> print(latex((2*tau)**sin(Rational(7,2))))
\left(2 \tau\right)^{\sin{\left(\frac{7}{2} \right)}}
>>> print(latex((2*tau)**sin(Rational(7,2)), fold_func_brackets=True))
\left(2 \tau\right)^{\sin {\frac{7}{2}}}
>>> print(latex(3*x**2/y))
\frac{3 x^{2}}{y}
>>> print(latex(3*x**2/y, fold_short_frac=True))
3 x^{2} / y
>>> print(latex(Integral(r, r)/2/pi, long_frac_ratio=2))
\frac{\int r\, dr}{2 \pi}
>>> print(latex(Integral(r, r)/2/pi, long_frac_ratio=0))
\frac{1}{2 \pi} \int r\, dr

Multiplication options:

>>> print(latex((2*tau)**sin(Rational(7,2)), mul_symbol="times"))
\left(2 \times \tau\right)^{\sin{\left(\frac{7}{2} \right)}}

Trig options:

>>> print(latex(asin(Rational(7,2))))
\operatorname{asin}{\left(\frac{7}{2} \right)}
>>> print(latex(asin(Rational(7,2)), inv_trig_style="full"))
\arcsin{\left(\frac{7}{2} \right)}
>>> print(latex(asin(Rational(7,2)), inv_trig_style="power"))
\sin^{-1}{\left(\frac{7}{2} \right)}

Matrix options:

>>> print(latex(Matrix(2, 1, [x, y])))
\left[\begin{matrix}x\\y\end{matrix}\right]
>>> print(latex(Matrix(2, 1, [x, y]), mat_str = "array"))
\left[\begin{array}{c}x\\y\end{array}\right]
>>> print(latex(Matrix(2, 1, [x, y]), mat_delim="("))
\left(\begin{matrix}x\\y\end{matrix}\right)

Custom printing of symbols:

>>> print(latex(x**2, symbol_names={x: 'x_i'}))
x_i^{2}

Logarithms:

>>> print(latex(log(10)))
\log{\left(10 \right)}
>>> print(latex(log(10), ln_notation=True))
\ln{\left(10 \right)}

latex() also supports the builtin container types list, tuple, and dictionary.

>>> print(latex([2/x, y], mode='inline'))
$\left[ 2 / x, \  y\right]$

pyspecdata.sympy_sqrt(arg, evaluate=None)

Returns the principal square root.

Parameters:evaluate (bool, optional) – The parameter determines if the expression should be evaluated. If None, its value is taken from global_parameters.evaluate.

Examples

>>> from sympy import sqrt, Symbol, S
>>> x = Symbol('x')

>>> sqrt(x)
sqrt(x)

>>> sqrt(x)**2
x

Note that sqrt(x**2) does not simplify to x.

>>> sqrt(x**2)
sqrt(x**2)

This is because the two are not equal to each other in general. For example, consider x == -1:

>>> from sympy import Eq
>>> Eq(sqrt(x**2), x).subs(x, -1)
False

This is because sqrt computes the principal square root, so the square may put the argument in a different branch. This identity does hold if x is positive:

>>> y = Symbol('y', positive=True)
>>> sqrt(y**2)
y

You can force this simplification by using the powdenest() function with the force option set to True:

>>> from sympy import powdenest
>>> sqrt(x**2)
sqrt(x**2)
>>> powdenest(sqrt(x**2), force=True)
x

To get both branches of the square root you can use the rootof function:

>>> from sympy import rootof

>>> [rootof(x**2-3,i) for i in (0,1)]
[-sqrt(3), sqrt(3)]

Although sqrt is printed, there is no sqrt function so looking for sqrt in an expression will fail:

>>> from sympy.utilities.misc import func_name
>>> func_name(sqrt(x))
'Pow'
>>> sqrt(x).has(sqrt)
Traceback (most recent call last):
  ...
sympy.core.sympify.SympifyError: SympifyError: <function sqrt at 0x10e8900d0>

To find sqrt look for Pow with an exponent of 1/2:

>>> (x + 1/sqrt(x)).find(lambda i: i.is_Pow and abs(i.exp) is S.Half)
{1/sqrt(x)}

See also

sympy.polys.rootoftools.rootof(), root(), real_root()

References

[1]	https://en.wikipedia.org/wiki/Square_root

[2]	https://en.wikipedia.org/wiki/Principal_value

pyspecdata.sympy_symbol

alias of sympy.core.symbol.Symbol

pyspecdata.sympy_var(names, **args)

Create symbols and inject them into the global namespace.

This calls symbols() with the same arguments and puts the results into the global namespace. It’s recommended not to use var() in library code, where symbols() has to be used:

.. rubric:: Examples

>>> from sympy import var

>>> var('x')
x
>>> x
x

>>> var('a,ab,abc')
(a, ab, abc)
>>> abc
abc

>>> var('x,y', real=True)
(x, y)
>>> x.is_real and y.is_real
True

See symbols() documentation for more details on what kinds of arguments can be passed to var().

class pyspecdata.testclass

Bases: object

pyspecdata.text_on_plot(x, y, thistext, coord='axes', **kwargs)

pyspecdata.textlabel_bargraph(mystructarray, othersort=None, spacing=0.1, ax=None, tickfontsize=8)

pyspecdata.unmake_ndarray(array_to_conv, name_forprint='unknown')

Convert this item to an ndarray

pyspecdata.whereblocks(a)

returns contiguous chunks where the condition is true but, see the “contiguous” method, which is more OO