ace package

Subpackages

• ace.samples package
  • Submodules
  • ace.samples.breiman85 module
  • ace.samples.smoother_friedman82 module
  • ace.samples.supersmoother_friedman82 module
  • ace.samples.wang04 module
  • Module contents
• ace.tests package
  • Submodules
  • ace.tests.test_ace module
  • ace.tests.test_model module
  • ace.tests.test_smoother module
  • Module contents
• ace.validation package
  • Submodules
  • ace.validation.run_supsmu module
  • ace.validation.validate_smoothers module
  • Module contents

Submodules

ace.ace module

The Alternating Condtional Expectation (ACE) algorithm

ACE was invented by L. Breiman and J. Friedman [Breiman85]. It is a powerful way to perform multidimensional regression without assuming any functional form of the model. Given a data set:

\(y = f(X)\)

where \(X\) is made up of a number of independent variables xi, ACE will tell you how \(y\) varies vs. each of the individual independents \(xi\). This can be used to:

• Understand the relative shape and magnitude of y’s dependence on each xi
• Produce a lightweight surrogate model of a more complex response
• other stuff

class ace.ace.ACESolver

Bases: object

Runs the Alternating Conditional Expectation algorithm to perform regressions

Methods

solve()

Run the ACE calculational loop

specify_data_set(x_input, y_input)

Define input to ACE

Parameters:

x_input : list

list of iterables, one for each independent variable

y_input : array

the dependent obeservations

write_input_to_file(fname='ace_input.txt')

Write y and x values used in this run to a space-delimited txt file

write_transforms_to_file(fname='ace_transforms.txt')

Write y and x transforms used in this run to a space-delimited txt file

ace.ace.plot_input(ace_model, fname='ace_input.png')

Plot the transforms

ace.ace.plot_transforms(ace_model, fname='ace_transforms.png')

Plot the transforms

ace.ace.sort_vector(data, indices_of_increasing)

permutate 1-d data using given indices

ace.ace.unsort_vector(data, indices_of_increasing)

unpermutate 1-D data that is sorted by indices_of_increasing

ace.model module

The Model module is a front-end to the ace.ace module. ACE itself just gives transformations back as discontinuous data points. This module loads data, runs ACE, and then performs interpolations on the results, giving the user continuous functions that may be evaluated at any point within the range trained.

This is a convenience/frontend/demo module. If you want to control ACE yourself, you may want to just use the ace module manually.

class ace.model.Model

Bases: object

A continuous model of data based on ACE regressions

Methods

build_interpolators()

Compute 1-D interpolation functions for all the transforms so they’re continuous.

build_model_from_txt(fname)

Construct the model and perform regressions based on data in a txt file.

Parameters:

fname : str

The name of the file to load.

build_model_from_xy(x_values, y_values)

Construct the model and perform regressions based on x, y data.

eval(x_values)

evaluate the ACE regression at any combination of independent variable values

Parameters:

x_values : iterable

a float x-value for each independent variable, e.g. (1.5, 2.5)

init_ace(x_values, y_values)

Specify data for the ACE solver object

run_ace()

Perform the ACE calculation

ace.model.read_column_data_from_txt(fname)

reads data from a simple text file.

Format should be just numbers. First column is the dependent variable. others are independent. Whitespace deliminted.

Returns:

x_values : list

List of x columns

y_values : list

list of y values

ace.smoother module

Scatterplot smoother with a fixed span. Takes x,y scattered data and returns a set of (x,s) points that form a smoother curve fitting the data with moving least squares estimates. Similar to a moving average, but with better characteristics. The fundamental issue with this smoother is that the choice of span (window size) is not known in advance. The SuperSmoother uses these smoothers to figure out which span is optimal.

This is a Python port of J. Friedman’s 1982 fixed-span Smoother [Friedman82]

Example:

s = Smoother()
s.specify_data_set(x, y, sort_data = True)
s.set_span(0.05)
s.compute()
smoothed_y = s.smooth_result

class ace.smoother.BasicFixedSpanSmoother

Bases: ace.smoother.Smoother

A basic fixed-span smoother

Simple least-squares linear local smoother.

Uses fast updates of means, variances.

Methods

compute()

Perform the smoothing operations

class ace.smoother.BasicFixedSpanSmootherSlowUpdate

Bases: ace.smoother.BasicFixedSpanSmoother

Uses slow means and variances at each step. Used to validate fast updates

Methods

ace.smoother.DEFAULT_BASIC_SMOOTHER

alias of BasicFixedSpanSmoother

class ace.smoother.Smoother

Bases: object

Smoothers accept data and produce smoother curves that fit the data.

Methods

add_data_point_xy(x, y)

add a new data point to the data set to be smoothed

compute()

Perform the smoothing operations

plot(fname=None)

Plot the input data and resulting smooth

Parameters:

fname : str, optional

name of file to produce. If none, will show interactively.

set_span(span)

Set the window-size for computing the least squares fit

Parameters:

span : float

Fraction on data length N to be considered in smoothing

specify_data_set(x_input, y_input, sort_data=False)

Fully define data by lists of x values and y values.

This will sort them by increasing x but remember how to unsort them for providing results.

Parameters:

x_input : iterable

list of floats that represent x

y_input : iterable

list of floats that represent y(x) for each x

sort_data : bool, optional

If true, the data will be sorted by increasing x values.

ace.smoother.perform_smooth(x_values, y_values, span=None, smoother_cls=None)

Convenience function to run the basic smoother

Parameters:

x_values : iterable

List of x value observations

y_ values : iterable

list of y value observations

span : float, optional

Fraction of data to use as the window

smoother_cls : Class

The class of smoother to use to smooth the data

Returns:

smoother : object

The smoother object with results stored on it.

ace.supersmoother module

A variable-span data smoother. This uses the fixed-span smoother to determine a changing optimal span for the data based on cross-validated residuals. It is an adaptive smoother that requires several passes over the data.

The SuperSmoother provides a mechanism to evaluate the conditional expectations in the ACE algorithm.

Based on [Friedman82].

Example:

s = SuperSmoother()
s.specify_data_set(x, y, sort_data = True)
s.compute()
smoothed_y = s.smooth_result

class ace.supersmoother.SuperSmoother

Bases: ace.smoother.Smoother

Variable-span smoother

Methods

compute()

set_bass_enhancement(alpha)

Bass enhancement amplifies the bass span

This gives the resulting smooth a smoother look, which is sometimes desirable if the underlying mechanisms are known to be smooth.

class ace.supersmoother.SuperSmootherWithPlots

Bases: ace.supersmoother.SuperSmoother

Auxiliary subclass for researching/understanding the SuperSmoother

Methods

Module contents

ace is a multivariate regression tool that solves alternating conditional expectations

See full documentation at http://partofthething.com/ace

To use, get some sample data:

from ace.samples import wang04
x, y = wang04.build_sample_ace_problem_wang04(N=200)

and run:

from ace import model
myace = model.Model()
myace.build_model_from_xy(x, y)
myace.eval([0.1, 0.2, 0.5, 0.3, 0.5])

For some plotting (matplotlib required), try:

from ace import ace
ace.plot_transforms(myace, fname = 'mytransforms.pdf')
myace.ace.write_transforms_to_file(fname = 'mytransforms.txt')