API Reference

pysymlog.inverse_symmetric_logarithm(arginv, base=10, shift=1)

Inverse symmetric logarithm transform, for converting transformed values back to linear space. The following describes this transform: # positive: (arg+shift)/shift = 10**arginv | negative: -shift/(arg+shift) = 10**argvinv # arg = (10**arginv)*shift-shift | arg = -shift/(10**arginv)-shift

Parameters:

• arginv (float, or array-like) – The value(s) to be transformed

• base (int, or float) – The logarithm base

• shift (int, or float) – The amount to shift values in the transform. Values smaller in scale than this value will appear more stretched – decrease to stretch small values more, or increase to minimize the stretching effect. Similar to the parameter ‘linthresh’ in matplotlib’s ‘symlog’ scale, though values for shift here should be ~ 1/10 of linthresh for close results.

Returns:

inverse_symmetric_logarithm

Return type:

float, or numpy.array

pysymlog.make_inverse_symmetric_logarithm(base=10, shift=1)

Convenience function to generate a new inverse symmetriclog function with specified logarithm base and shift values.

pysymlog.make_symmetric_logarithm(base=10, shift=1)

Convenience function to generate a new symmetriclog function with specified logarithm base and shift values.

pysymlog.register_mpl()

Calling this function imports matplotlib and registers the symmetric log scale for use, and also adds these classes and functions to the pysymlog namespace: - SymmetricLogarithmLocator - SymmetricLogarithmTransform - InvertedSymmetricLogarithmTransform - MinorSymmetricLogLocator - SymmetricLogarithmScale - MinorSymLogLocator - set_symmetriclog_minorticks() - set_symlog_minorticks() - symlogbin_hist_mpl() - SymmetricLogarithmNorm [colorbar normalization]

pysymlog.register_plotly()

Calling this function imports plotly graph_objects and defines functions for using symmetric log transforms in plotly Figures. The following functions are defined and added to the pysymlog namespace: - set_plotly_scale_symmetriclog() - go_scatter_symlog() - go_line_symlog() - go_histogram_symlog() - px_scatter_symlog() - px_line_symlog() - px_histogram_symlog()

Example

xdata = np.arange(-2, 5.0, 0.01) ydata = np.tan(xdata) fig = go.Figure() psl.go_scatter_symlog(fig, xdata, ydata, xy=’y’) fig.show()

pysymlog.symlogbin_histogram(data, Nbins, limits=['auto', 'auto'], shift=1, base=10, density=False, weights=None)

Convenience function to call numpy.histogram() using symmetric log scaled bins, which are calculated from the data array and specified number of bins.

Parameters:

• data (array_like) – Input data. The histogram is computed over the flattened array.

• Nbins (int) – Desired number of bins that will be equal-width in symmetric log space.

• limits ([float,float] or ['auto','auto']) – Limits to impose on the output histogram bin minimum/maximum, specified in order [lo,hi]. ‘auto’ determines the value automatically as the min or max value in the input data array. Supercedes the usage of the range parameter in np.histogram

• base (int, or float) – The logarithm base for the transform

• shift (int, or float) – The amount to shift values in the transform. Values smaller in scale than this value will appear more stretched – decrease to stretch small values more, or increase to minimize the stretching effect. Similar to the parameter ‘linthresh’ in matplotlib’s ‘symlog’ scale, though values for shift here should be ~ 1/10 of linthresh for close results.

• weights (array_like, optional) – An array of weights, of the same shape as a. Each value in a only contributes its associated weight towards the bin count (instead of 1). If density is True, the weights are normalized, so that the integral of the density over the range remains 1.

• density (bool, optional) – If False, the result will contain the number of samples in each bin. If True, the result is the value of the probability density function at the bin, normalized such that the integral over the range is 1. Note that the sum of the histogram values will not be equal to 1 unless bins of unity width are chosen; it is not a probability mass function.

Returns:

• hist (array) – The values of the histogram. See density and weights for a description of the possible semantics.

• bin_edges (array of dtype float) – Return the bin edges (length(hist)+1).

Examples

testdat = np.tan( np.linspace(-5,10, 1000) ) counts,symlogbins = symlogbin_histogram(testdat, 101, limits=[‘auto’,’auto’], shift=1e-4) count_densities,symlogbins2 = symlogbin_histogram(testdat, 101, limits=[-1e-5,1e3], shift=1e-3, density=True)

pysymlog.symlogbin_histogram2d(xdata, ydata, Nbins, limits=[['auto', 'auto'], ['auto', 'auto']], shift=1, base=10, density=False, weights=None)

Convenience function to call numpy.histogram() using symmetric log scaled bins, which are calculated from the data array and specified number of bins.

Parameters:

• xdata (array_like) – Array containing the x-coordinate values of the data to be histogrammed.

• ydata (array_like) – Array containing the y-coordinate values of the data to be histogrammed.

• Nbins (int or [int,int]) – Desired number of bins that will be equal-width in symmetric log space. If int, the number of bins for each of the two dimensions (nx=ny=Nbins). If [int, int], the number of bins in each dimension (nx, ny = Nbins).

• limits ([[float,float], [float,float]] or [['auto','auto'], ['auto','auto']]) – Limits to impose on the output histogram bin minima/maxima, specified in order [[x_lo,x_hi], [y_lo,y_hi]]. ‘auto’ determines the specific values automatically as the min or max value in the input data array. Supercedes the usage of the range parameter in np.histogram2d

• base (int, or float) – The logarithm base for the transform

• shift (float or [float, float]) – The amount to shift values in the transform. Values smaller in scale than this value will appear more stretched – decrease to stretch small values more, or increase to minimize the stretching effect. Similar to the parameter ‘linthresh’ in matplotlib’s ‘symlog’ scale, though values for shift here should be ~ 1/10 of linthresh for close results. Either input as a single value to apply to both x and y components, or as a list/tuple/array_like of values in order [x_shift, y_shift]

• weights (array_like, optional) – An array of values w_i weighing each sample (x_i, y_i). Weights are normalized to 1 if density is True. If density is False, the values of the returned histogram are equal to the sum of the weights belonging to the samples falling into each bin.

• density (bool, optional) – If False, the result will contain the number of samples in each bin. If True, the result is the value of the probability density function at the bin, normalized such that the integral over the range is 1. Note that the sum of the histogram values will not be equal to 1 unless bins of unity width are chosen; it is not a probability mass function. If False (the default), returns the number of samples in each bin. If True, returns the probability density function at the bin, normalized as ( bin_count / sample_count / bin_area ).

Returns:

• H (ndarray, shape(nx, ny)) – The bi-dimensional histogram of samples x and y. Values in x are histogrammed along the first dimension and values in y are histogrammed along the second dimension.

• xedges (ndarray, shape(nx+1,)) – The bin edges along the first (x-coordinate) dimension.

• yedges (ndarray, shape(ny+1,)) – The bin edges along the second (y-coordinate) dimension.

Examples

dx = np.random.exponential(scale=1, size=5000)*np.random.randn(5000) dy = np.random.exponential(scale=3, size=5000)*np.random.randn(5000) # 101 auto-calculated bins in each of x,y directions counts, bins_x, bins_y = psl.symlogbin_histogram2d(dx,dy, 101, limits=[‘auto’,’auto’], shift=1e-1) # 31 bins in x, 101 bins in y, and returning count density count_densities,bins_x2, bins_y2 = psl.symlogbin_histogram2d(dx,dy, [31,101], limits=[[-5,5],[-50,50]], shift=1e-1, density=True)

pysymlog.symmetric_log_decades(lo, hi, thresh, include_zero=True)

Generate the decades from lo to hi, using the threshold, stopping at the specified threshold if the range crosses zero. This is used in particular for generating lists of tick locations and labels.

Parameters:

• lo (float) – The low value to consider, given in linear space

• hi (float) – The high value to consider, given in linear space

• thresh (float) – The lowest (absolute value) numerical scale to use in the generation of the list of decades – if the lo-hi range crosses zero (lo is negative and hi is positive).

• include_zero (bool) – If True, include zero in the resulting array (if the array crosses zero)

Returns:

decades

Return type:

numpy.array

Examples

symmetric_log_decades(-100, 100, 1e-1) #–> array([-100. , -10. , -1. , -0.1, 0. , 0.1, 1. , 10. , 100. ]) symmetric_log_decades(-1.2345, 0.987, 1e-2) #–> array([-1. , -0.1 , -0.01, 0. , 0.01 , 0.1 , 1. ]) symmetric_log_decades(-1e6, 1e3, 1000) #–> array([-1000000., -100000., -10000., -1000., 0., 1000.]) symmetric_log_decades(-1e6, 1e3, 1000, include_zero=False) #–> array([-1000000., -100000., -10000., -1000., 1000.])

pysymlog.symmetric_log_decades_from_array(data, thresh='auto', auto_percentile=10.0, include_zero=True)

Convenience function to calculate an array of symmetric log decades from an input data set based on the range in its values. If a scale threshold is not specified, or set to ‘auto’, a reasonable attempt is made to estimate a threshold heuristically based on a percentile of its absolute values. (This hopefully captures a meaningful lower scale.)

Parameters:

• data (array-like) – The data set from which a range will be determined to calculate the array of symmetric log decades.

• thresh (float, or 'auto') – The threshold lowest absolute scale to consider for the decades, which is used when the data set range crosses the zero mark (includes positive and negative values).

• auto_percentile (float) – The percentile to use in automatic threshold determination.

• include_zero (bool) – If True, include zero in the resulting array (if the array crosses zero)

Returns:

decades

Return type:

numpy.array

Example

testdat = np.tan( np.linspace(-5,10, 1000) ) print(np.nanpercentile(testdat, [0.01,99.99])) #–> [-404.29964885 840.36255943] psl.symmetric_log_decades_from_array(testdat)#, thresh=’auto’, auto_percentile=10., include_zero=True) #–> np.array([-1.e+03, -1.e+02, -1.e+01, -1.e+00, -1.e-01, 0.e+00, 1.e-01, # 1.e+00, 1.e+01, 1.e+02, 1.e+03])

pysymlog.symmetric_logarithm(arg, base=10, shift=1)

Transform a value into a symmetric log space that allows for smooth continuous stretch display in plotting utilites. The following describes the transform: # positive: log10( (arg+shift)/shift ) | negative: -log( shift/(arg+shift) ) # = log(arg+shift) - log(shift) | = -log(-arg+shift) + log(shift)

Parameters:

• arg (float, or array-like) – The value(s) to be transformed

• base (int, or float) – The logarithm base

• shift (int, or float) – The amount to shift values in the transform. Values smaller in scale than this value will appear more stretched – decrease to stretch small values more, or increase to minimize the stretching effect. Similar to the parameter ‘linthresh’ in matplotlib’s ‘symlog’ scale, though values for shift here should be ~ 1/10 of linthresh for close results.

Returns:

symmetric_logarithm

Return type:

float, or numpy.array

pysymlog.symmetric_logspace(lo, hi, N, input_format='linear', shift=1, base=10)

Function to generate a sequence of values in log space based on low and high values, similar to the functionality of e.g. np.logspace but instead using a symmetric log transform.

Parameters:

• lo (float) – The low limit

• hi – The high limit

• N (int) – The number of elements the output array should have

• input_format (str) – Specifies whether the input lo,hi values are given in ‘linear’, ‘log’, or ‘symlog’. For example, if input_format=’linear’ then lo,hi are given as their linear values (e.g. 1e-2 and 1000), if input_format=’log’ then they are taken as log values (e.g. -2 and 3 instead of 1e-2 and 1000). If input_format=’symlog’ then they are taken as log values with negative values meaning less than zero (not as a fraction less than one). To avoid confusion, it’s best to input lo and hi values in linear space.

• shift (float) – The amount to shift values in the transform. See symmetric_logarithm() for more detail.

• base (int, or float) – The logarithm base

Returns:

inverse_symmetriclog_array – The linear scale values of

Return type:

numpy.array

Examples

psl.symmetric_logspace(-10, 100, N=5) #–> np.array([-10., -0.90530352, 2.03015151, 16.49415053, 100.]) psl.symmetric_logspace(-np.log10(10), np.log10(100), N=5, input_format=’symlog’) #–> np.array([-10., -0.90530352, 2.03015151, 16.49415053, 100.]) psl.symmetric_logspace(-2, 3, N=3, input_format=’log’) #–> np.array([1.00000000e-02, 3.07963834e+01, 1.00000000e+03])

pysymlog.symmetric_logspace_from_array(array, N, input_format='linear', shift=1, base=10)

Function to generate a sequence of values in log space based on the low and high values from an input array. Similar to the functionality of np.logspace but instead using a symmetric log transform. Useful in particular for generating histogram bins in symmetric log space from a particular array.

Parameters:

• array (array-like (list, tuple, np.array...)) – The input array of values from which to determine low and high limits.

• N (int) – The number of elements the output array should have

• input_format (str) – Specifies whether the input lo,hi values are given in ‘linear’, ‘log’, or ‘symlog’. For example, if input_format=’linear’ then lo,hi are given as their linear values (e.g. 1e-2 and 1000), if input_format=’log’ then they are taken as log values (e.g. -2 and 3 instead of 1e-2 and 1000). If input_format=’symlog’ then they are taken as log values with negative values meaning less than zero (not as a fraction less than one). To avoid confusion, it’s best to input lo and hi values in linear space.

• shift (float) – The amount to shift values in the transform. See symmetric_logarithm() for more detail.

• base (int, or float) – The logarithm base

Returns:

inverse_symmetriclog_array

Return type:

numpy.array

Example

testdat = np.random.randn(1000) print([testdat.min(),testdat.max()]) #–> [-3.0152414613412186, 3.336199242183869] psl.symmetric_logspace_from_array(testdat, N=4, shift=1e-2) #–> np.array([-3.01524146, -0.05491167, 0.06179836, 3.33619924])