Python Integration (Stat-Ease 360® only)

This page documents the different functions available in the statease Python module. The module is available on pypi.org, and can be installed with the Python package manager command, pip install statease. If you have not yet done this, you will need to follow the instructions in the Python Introduction tutorial. This will guide you through the process of installing the module, as well as configuring Stat-Ease to use the correct Python environment.

Running a Python Script

There are several ways to run a Python script in SE360.

The recommended method is to simply open the script dialog via the Python button in the main toolbar. From there you can open your script, or create a new one. The dialog includes an editor with syntax highlighting and an output window.

You can also use the included dx_console.exe executable to process a script from the command line. Simply pass the Python script you want to run as a parameter and it will run immediately.

"C:\Program Files\Stat-Ease 360\dx_console.exe" example.py

Finally, you can use dx_console.exe to run in “listen” mode by passing –listen as an argument. This will wait for a Python script running from an external interpreter (e.g. from another terminal, or from the JetBrains IDE) to connect and execute.

"C:\Program Files\Stat-Ease 360\dx_console.exe" --listen

Connecting to Stat-Ease 360

In order to interact with Stat-Ease, you first need to connect to it using the statease.connect() function. This will create a statease.SEClient instance that you will want to store. It is used for high-level interaction with Stat-Ease.

statease.connect()[source]

Creates a connection to Stat-Ease 360.

Return type

statease.client.SEClient

Example
>>> import statease as se
>>> se_conn = se.connect()
class statease.SEClient[source]
create_analysis(response_name, analysis_name, transform=Transform.No_Transform, **kwargs)[source]

Creates an analysis for a response.

Parameters
  • response_name (str) – The name of the response to analyze.

  • analysis_name (str) – The desired name for this analysis.

  • transform (str) – The transform to apply to the response for this analysis. The default is “No Transform”.

create_factor(factor_name, factor_levels=[- 1, 1], factor_type='numeric', categoric_type='nominal')[source]

Creates a factor.

Parameters
  • factor_name (str) – The name of the factor.

  • factor_levels (list) – The actual levels of the factor. For continuous factors this should simply be [low, high]. For categoric or discrete factors this should be a list of all valid factor levels. The default is [-1, 1].

  • factor_type (str) – The type of the factor. The default is “numeric”.

  • categoric_type (str) – If the factor type is “categoric”, this will set type of categoric factor (e.g. nominal or ordinal). The default is “nominal”.

create_response(response_name, response_units='', response_format='General')[source]

Creates a response. :param str response_name: The desired name of the response. :param str response_units: The response units. :param str response_format: The format of the response values in the user interface. The default is “General”.

delete_analysis(analysis_name)[source]

Deletes an analysis.

Parameters

analysis_name (str) – The name of the analysis to delete.

delete_factor(factor_name)[source]

Deletes a factor.

Parameters

factor_name (str) – The name of the factor to delete.

delete_response(response_name)[source]

Deletes a response.

Parameters

response_name (str) – The name of the response to delete.

get_factor(name)[source]

Retrieves a factor from the current design.

Parameters

name (str) – The name of the factor. Case insensitive.

Return type

statease.factor.Factor

Example
>>> import statease as se
>>> se_conn = se.connect()
>>> se_conn.get_factor("n-propanol")
name: “N-Propanol”
units: “wt %”
length: 20
get_factors()[source]

Retrieve all Factor objects in the current design. :rtype: Python list of statease.factor.Factor objects

Example
>>> import statease as se
>>> se_conn = se.connect()
>>> factors = se_conn.get_factors()
get_preference(key)[source]

Retrieves the current value of a preference.

Parameters

key (str) – The preference key. This can be found in the Stat-Ease 360 preference dialog.

get_response(name)[source]

Retrieves a response from the current design.

Parameters

name (str) – The name of the response. Case insensitive.

Return type

statease.response.Response

Example
>>> import statease as se
>>> se_conn = se.connect()
>>> se_conn.get_response("CFU")
name: “CFU”
units: “per cm^2”
length: 20
get_responses()[source]

Retrieve all response objects in the current design. :rtype: Python list of statease.response.Response objects

Example
>>> import statease as se
>>> se_conn = se.connect()
>>> responses = se_conn.get_responses()
list_factors()[source]

Returns a list of all factor names in the current design.

Use get_factor() to retrieve factor settings and row data.

Example
>>> import statease as se
>>> se_conn = se.connect()
>>> se_conn.list_factors()
["A", "B", "C"]
list_responses()[source]

Returns a list of all response names in the current design.

Use get_response() to retrieve response settings and row data.

Example
>>> import statease as se
>>> se_conn = se.connect()
>>> se_conn.list_responses()
["R1", "R2"]
set_comment(row, comment)[source]

Sets the comment on a row.

Example
>>> se_conn.set_row_comment(1, 'Bad batch')
set_preference(key, value, area='')[source]

Sets a preference.

Parameters
  • key (str) – The preference key. This can be found in the Stat-Ease 360 preference dialog.

  • value (str) – The value to assign to the preference.

set_row_status(rows, status)[source]

Sets the status of one or more rows.

Example
>>> # ignores rows 2/4/6/8
>>> se_conn.set_row_status([ 1, 3, 5, 7], RowStatus.IGNORED)

Design Properties

These functions allow you to interact with factors and responses in Stat-Ease, as well as other properties of the current design.

Factors

class statease.factor.Factor(client, name)[source]

The Factor class holds information about an individual Factor in Stat-Ease 360. Instances of this class are typically created by statease.client.SEClient.get_factor()

Attributes:

name (str): the name of the factor

units (str): the units of the factor

values (tuple): the values of the factor, in run order

low (str, read only): the actual low that corresponds to the coded low (this is usually, but not necessarily, the minimum observed value)

high (str, read only): the actual high that corresponds to the coded high (this is usually, but not necessarily, the maximum observed value)

coded_low (str, read only): the coded low value, typically -1 or 0

coded_high (str, read only): the coded high value, typically 1

property coded_values

Get the coded factor values in the current coding.

Example
>>> # get a list of the coded values
>>> xc = factor.coded_values
is_categorical()[source]

Test for categorical factor type.

Example
>>> # get a list of the coded values
>>> #  values if the factor is categorical
>>> x = []
>>> if (factor.is_categorical):
>>>   x = factor.coded_values
>>> else: # Factor is not categorical
>>>   x = factor.values
property values

Get or set the factor values. When setting the factor values, you may use either a list or a dictionary. If fewer values are assigned than there are rows in the design, they will be filled in starting with first row. If a dictionary is used, it must use integers as keys, and it will fill factor values in rows indexed by the dictionary keys. The indices are 0-based, so the first row is index 0, the second index 1, and so on.

Example
>>> # sets the first 4 rows to a list of values
>>> factor.values = [.1, .2, .3, .4]
>>> # sets the 7th through 10th rows to specific values
>>> factor.values = { 6: .1, 7: .2, 8: .3, 9: .4 }
>>> # sets the 6th run to a specific value
>>> factor.values = { 5: .8 }

Responses

class statease.response.Response(client, name)[source]

The Response class holds information about an individual Response in Stat-Ease 360. Instances of this class are typically created by statease.client.SEClient.get_response().

Variables
  • name (str) – the name of the response

  • units (str) – the units of the response

  • values (list) – the values of the response, in run order

simulate(equation, std_dev=1, variance_ratio=1, is_simulation=True)[source]

Simulates data for a response.

Parameters
  • equation (str) – An equation that is recognized by the Stat-Ease 360 simulator. Search the help for “Equation Entry” for more information on the equation format.

  • std_dev (float) – This adds some normal error to each simulated value.

  • variance_ratio (float) – If there are groups in the design, inter-group variability will be simulated using a combination of this parameter and the std_dev parameter.

  • is_simulation (bool) – If False, sets the std_dev parameter to 0 and sets the response analysis to “equation only”. Use this to create a function that does not require regression analysis, but will availble in numerical optimization. Note: The default is true, but this parameter takes precendance over the std_dev parameter when False.

Example
>>> response.simulate('a+b+sin(a)', std_dev=2) # A simulation with noise
>>> response.simulate('exp(1+a-2*b)',is_simulation=False) # Noiseless equation
property values

Get or set the response values. When setting the response values, you may use either a list or a dictionary. If fewer values are assigned than there are rows in the design, they will be filled in starting with first row. If a dictionary is used, it must use integers as keys, and it will fill response values in rows indexed by the dictionary keys. The indices are 0-based, so the first row is index 0, the second index 1, and so on.

Example
>>> # sets the first 4 rows to a list of values
>>> response.values = [.1, .2, .3, .4]
>>> # sets the 7th through 10th rows to specific values
>>> response.values = { 6: .1, 7: .2, 8: .3, 9: .4 }
>>> # sets the 6th run to a specific value
>>> response.values = { 5: .8 }

Analyses

class statease.analysis.Analysis(client, name)[source]

The Analysis class holds information about an Analysis in Stat-Ease 360. Instances of this class are typically created by statease.client.SEClient.get_analysis().

analyze()[source]

Runs the analyses on the selected model.

auto_select(initial_model, criterion, method, alpha=None, select_by_degree=False, **kwargs)[source]

Performs an auto-selection on an initial model.

Parameters
  • initial_model (str) – A model to auto-select a subset of terms from.

  • criterion (str) – The criterion used to evaluate each sub-model. Valid options are “AICc”, “BIC”, “pValues”, or “AdjRSquared” (case-insensitive).

  • method (str) – The method used to select sub-models. Valid options are “Forward”, “Backward”, “Stepwise”, and “AllHierarchical” (case-insensitive).

  • alpha (float) – This is the alpha used to either include or exclude terms when using the “pValues” criterion. You can also pass alpha_in and/or alpha_out to set those values separately (setting both only has an effect when using the “Stepwise” method).

  • select_by_degree (bool) – Restricts the sub-model comparisons to lower order terms before considering higher order terms.

Example
>>> result_model = analysis.auto_select('A+B+C+AB+BC+ABC', 'BICc', 'Backward')
>>> print(result_model)
>>> "A+B+AB"
get_anova()[source]

Retrieves an AnovaResults object for this analysis.

get_diagnostics()[source]

Retrieves an DiagnosticsResults object for this analysis.

get_prediction(points, **kwargs)[source]

Retrieves a Prediction object for one or more points.

go_to_node(node)[source]

Forces the Stat-Ease 360 GUI to display a particular node.

predict(points, coded=False, **kwargs)[source]

Makes predictions at one or more points.

set_model(model=None, **kwargs)[source]

Sets the model used in the analysis.

Optimizer

class statease.optimizer.Goal(value)[source]

An enumeration representing the different types of goals a Criteria can have.

class statease.optimizer.Criteria(factor=None, analysis=None)[source]

The Criteria class is used by the optimizer to calculate a desirability score for a given point in the design space, which is then used to search for an optimal point.

Each Analysis and Factor can have a Criteria (e.g. you might maximize the output of an Analysis, and target a certian value of a Factor).

property goal

The goal of this Criteria (e.g. Goal.MAXIMIZE).

property importance

The importance of this Criteria, relative to other Criteria.

property lower_limit

The lower limit for this Criteria.

property lower_weight

The lower weight for this Criteria.

property target

The target for this Criteria, if using Goal.EQUAL_TO or Goal.TARGET

property upper_limit

The upper limit for this Criteria.

property upper_weight

The upper weight for this Criteria.

class statease.optimizer.Optimizer(client)[source]

The Optimizer class is used to set criteria on one or more Analyses, then use those criteria to find the optimal parameters.

optimize()[source]

Runs the optimization routine. Must have one or more Criteria specified.

Samples

multiple-plots.py

poisson-variation.py (uses organism-count.dxpx)