oapackage package

Submodules

oapackage.Doptim module

Module to generate D-optimal designs

For more information see: https://doi.org/10.1080/00401706.2016.1142903

Pieter Eendebak <pieter.eendebak@gmail.com>

oapackage.Doptim.Doptimize(arrayclass, nrestarts=10, optimfunc=[1, 0, 0], verbose=1, maxtime=180, selectpareto=True, nout=None, method=0, niter=100000, nabort=0, dverbose=1)

Calculate D-efficient designs

The method uses a coordinate-exchange algorithm find a D-efficient (sometimes called D-optimal) design in the class specified by the arrayclass. The optimality is defined in terms of the optimization parameters. The optimization is performed multiple times (specified by the nrestarts parameter) to prevent finding a design in a local minmum of the target function.

Parameters

  • arrayclass (object) – Specifies the type of design to optimize

  • nrestarts (int) – Number of restarts of the algorithm

  • optimfunc (list with 3 floats) – Gives the optimization weights \(\alpha\) of the target function \(\alpha[0] D+\alpha[1] D_s+\alpha[2] D_1\)

  • verbose (int) – Verbosity level. A higher numer gives more output

  • maxtime (float) – Maximum running time of the algorithm. If this time is exceeded the algorithm is aborted.

  • selectpareto (bool) – default is True. If True then only the Pareto optimal designs are returned

  • nout (int or None) – Maximum number of designs to return. If None, return all designs

  • method (coordinate_exchange_method_t) – Specifies the method use for updating elements in the coordinate-exchange algorithm.

  • niter (int) – Maximum number of iterations of the coordinate-exchange algorithm

  • nabort (int) – If no improvements have been found after this number of updates, then abort this run

  • dverbose (int) – Verbosity level passed to the C++ Doptimize function

Returns

  • scores (list) – list of scores

  • dds (array) – array with calculated efficiencies

  • designs (list) – list of generated designs

  • nrestarts (int) – number of restarts used

The optimization target and the Pareto optimality are defined in terms of the D-efficiency, main effect robustness (or Ds-optimality) and the D1-efficiency of the design. A full definition of these efficiencies is available in the documentation at https://oapackage.readthedocs.io/en/latest/properties.html#optimality-criteria-for-d-efficient-designs. For more details and motivation of these efficiencies, see the paper “Two-Level Designs to Estimate All Main Effects and Two-Factor Interactions”, https://doi.org/10.1080/00401706.2016.1142903.

exception oapackage.Doptim.MissingMatplotLibException

Bases: Exception

oapackage.Doptim.array2Dtable(array_list: List, verbose: int = 1, titlestr: Optional[str] = None)

Generate HTML table with information about for a list of designs

Parameters

  • array_list (list) – list of arrays

  • verbose (int) – verbosity level

  • titlestr (str) – Not used

oapackage.Doptim.calcScore(dds, optimfunc)

Calculate D-efficiency score using multiple efficiencies and a weight factor

Parameters

  • dds (array) – the rows contains the effieciencies for various designs

  • optimfunc (array) – aray with the weight factors for the efficiencies

oapackage.Doptim.filterPareto(scores, dds, arrays, verbose=0)

From a list of designs select only the pareto optimal designs

Parameters

  • scores (array) – array of scores

  • dds (array) – array with D-efficiency values

  • arrays (list) – list of designs

Returns

list of scores of pareto optimal designs pareto_efficiencies (list): list of D-efficiency values of pareto optimal designs pareto_designs (list) : list of selected designs

Return type

pareto_scores (list)

oapackage.Doptim.generateDpage(outputdir, arrayclass, dds, allarrays, fig=20, optimfunc=(1, 0, 0), nofig=False, urlprefix='', makeheader=True, verbose=1, lbls=None)

Helper function to generate web page with D-optimal design results

oapackage.Doptim.generateDscatter(dds, second_index=0, first_index=1, lbls=None, ndata=3, nofig=False, fig=20, scatterarea=80, verbose=0, setWindowRectangle=False)

Generate scatter plot for D and Ds efficiencies

Parameters

dds (array) – array with D-efficiencies

Returns

contains handles to plotting elements

Return type

dict

oapackage.Doptim.optimDeffPython(A0, arrayclass=None, niter=10000, nabort=2500, verbose=1, alpha=[1, 0, 0], method=0)

Optimize array using specified optimization method

Parameters

  • A0 (array_link) – design to optimize

  • arrayclass (object) – contains class of designs to optimize

  • alpha (list) – specifies the optimization function

Returns

efficiencies A (array): optimized design

Return type

d (array)

oapackage.Doptim.scoreDn(dds, optimfunc)

Calculate scores from various efficiencies

Parameters

  • dds (array) – calculated D-efficiencies

  • optimfunc (list) – parameters for optimization function

Returns

scores (array)

oapackage.Doptim.selectDn(scores, dds, sols, nout=1, sortfull=True)

Select best arrays according to given scores

The resulting data is sorted

Parameters

  • scores (array) – scores for the designs

  • dds (array) – array with efficiencies of the designs

  • sols (list) – list of designs

  • nout (integer or None) – Number of results to return. None means return all results

  • sortfull (boolean) – If True, then sort on both the scores and the dds values

Returns

scores, dds, sols

Return type

sorted arrays

oapackage.conference module

Module with functions to work with conference designs

oapackage.conference.conferenceProjectionStatistics(array, ncolumns=4, verbose=0)

Calculate the projection statistics of a conference design

The PECk, PICk and PPCk are calculated with k the number of columns specified. The projection statistics are calculated by determined the modelStatistics() of all k-column subdesigns and then taking the mean of the statistics for the subdesigns. For more details of the calculation, see https://oapackage.readthedocs.io/.

Parameters

  • array (array) – conference design

  • ncolumns (int) – number of columns on which to project

Returns

calculated statistics

Return type

pec, pic, ppc (float)

oapackage.conference.modelStatistics(dsd, verbose=0, moment_matrix=None, use_condition_number=True)

Calculate statistics of a definitive screening design from the model matrix

Parameters

dsd (array) – definitive screening design

Returns

calculated statistics. Calculated are whether the model is estible, the Defficiency and the inverse APV.

Return type

list

oapackage.conference.momentMatrix(k)

Return the moment matrix of a conference design

Parameters

k (int) – number of columns of the conference design

Returns

moment matrix

Return type

array

oapackage.graphtools module

Module to work with designs and graphs

@author: Pieter Eendebak <pieter.eendebak@gmail.com>

oapackage.graphtools.oa2graph(al, adata, verbose=1)

Convert orthogonal array to graph representation

The conversion method is as in Ryan and Bulutoglu. The resulting graph is bi-partite. The graph representation can be used for isomorphism testing.

Example

> im, colors, r = oa2graph( A, oadata );

oapackage.graphtools.selectIsomorphismClasses(sols, verbose=1)

Select isomorphism classes from a list of designs

Parameters

  • sols (list of arrays) – list of arrays from which to determine the unique ones

  • verbose (int) – verbosity level

Returns

indices of the isomorphism classes mm (list of arrays): the arrays in normal form

Return type

indices (list of integers)

Example

>>> import oapackage.graphtools; import numpy as np
>>> sols=[oapackage.exampleArray(idx) for idx in [26,26,27,26]]
>>> idx, mm = oapackage.graphtools.selectIsomorphismClasses(sols, verbose=0)
>>> _, unique_indices = np.unique(idx, return_index=True)
>>> print('found %d isomorphism classes from %d arrays' % (len(unique_indices), len(sols)) )
found 2 isomorphism classes from 4 arrays
>>> representatives = [sols[idx] for idx in unique_indices]

oapackage.oahelper module

Collection of helper functions for OA package

@author: Pieter Eendebak <pieter.eendebak@gmail.com>

oapackage.oahelper.DefficiencyBound(D, k, k2)

Calculate the D-efficiency bound of an array extension

Parameters

  • D (float) – D-efficiency of the design

  • k (int) – numbers of columns

  • k2 (int) – numbers of columns

Returns

bound on the D-efficiency of extensions of a design with k columns to k2 columns

Return type

float

oapackage.oahelper.argsort(seq)

Stable version of argsort

oapackage.oahelper.array2html(X, header=1, tablestyle='border-collapse: collapse;', trclass='', tdstyle='', trstyle='', thstyle='')

Convert Numpy array to HTML table

Parameters

  • X (numpy array) – array to be converted

  • header (integer) – use header or not

Returns

page – generated table in HTML

Return type

markup html object

oapackage.oahelper.array2latex(X, header=1, hlines=(), floatfmt='%g', comment=None, hlinespace=None, mode='tabular', tabchar='c')

Convert numpy array to Latex tabular

oapackage.oahelper.arrayfile_generator(afile)

Return generator to read all files in the array file

oapackage.oahelper.checkArrayFile(afile, cache=1)

Check whether a file or list of files exists If the file does not exist, check whether a compressed file does exist cache: 0 (no), 1 (check), -1 (always)

oapackage.oahelper.checkFiles(lst, cache=1, verbose=0)

Check whether a file or list of files exists cache: 0 (no), 1 (check), -1 (always)

Returns False if one or more of the files do not exist Returns True if all files exist

oapackage.oahelper.checkFilesOA(lst, cache=1, verbose=0)

Check whether a file or list of files exists

Parameters

  • lst (list) – list of files

  • cache (int) – 0 (always return False), 1 (check), -1 (always return True)

For array files also the .gz extension is checked Returns False if one or more of the files do not exist Returns True if all files exist

oapackage.oahelper.checkOAfile(afile, verbose=0)

Return pointer to array file

Automatically check for compressed array files

Parameters

afile (str) – location of array file

Returns

arrayfile_t or None

oapackage.oahelper.choose(n: int, k: int) → int

Return n choose k

oapackage.oahelper.compressOAfile(afile, decompress=False, verbose=1)

Compress an OA array file

Parameters

  • afile (str) – array to compress

  • decompress (bool) – If True then decompress

  • verbose (int) – verbosity level

oapackage.oahelper.createPareto(dds, verbose=1)

Create Pareto object from dataset

oapackage.oahelper.create_pareto_element(values, pareto=None)

Create a vector of mvalue_t elements :param vv: list with tuples or arrays :type vv: list

Returns

Pareto element

Return type

object

oapackage.oahelper.deprecated(func)

This is a decorator which can be used to mark functions as deprecated. It will result in a warning being emitted when the function is used.

oapackage.oahelper.designStandardError(al) → Tuple[float, float, float]

Return standard errors for a design

Parameters

al (array) – design

Returns

array with standard errors

Return type

array

oapackage.oahelper.enlargelims(factor: float = 1.05)

Enlarge the limits of a plot

Parameters

factor (float) – factor by which to make the plot margins wider

oapackage.oahelper.extendSingleArray(A, adata, t=3, verbose=1)

Extend a single orthogonal array

oapackage.oahelper.fac(n)

Return n! (factorial)

Parameters

n (int) – number to calculate factorial

Returns

integer: factorial of number

oapackage.oahelper.finddirectories(directory, pattern=None)

Get a list of directories :param directory: directory to search :type directory: str :param patt: pattern :type patt: str

Returns

list of matched directories

Return type

list

oapackage.oahelper.findfiles(directory, pattern=None)

Get a list of files :param directory: directory to search :type directory: str :param patt: pattern :type patt: str

Returns

list of matched files

Return type

list

oapackage.oahelper.findfilesR(directory, pattern)

Get a list of files (recursive)

Parameters

  • directory (str) – directory to search

  • patt (str) – pattern

Returns

list of matched files

Return type

list

oapackage.oahelper.floatformat(number, mind=2, maxd=4)

Format a floating point number into a string

oapackage.oahelper.formatC(al, wrap: bool = True) → str

Format array for inclusion in C code

Parameters

  • array – Array to be converted to C code representation

  • wrap – If True, then add code to create a variable

Returns

Formatted string

oapackage.oahelper.getArrayFile(afile: str) → str

Return pointer to array file Automatically check for compressed array files

oapackage.oahelper.guitest_monitorSizes()
oapackage.oahelper.gwlp2str(gmadata, t=None, sformat=None, jstr=',')

Convert GWLP value to string format

oapackage.oahelper.helmert_contrasts(number_of_levels, verbose=0)

Calculate Helmert contrasts for a given number of levels

The Helmert contrasts are orthogonal and normalize such that the square equals to number of levels. :param number_of_levels: number of levels in the number_of_levels

Returns

array with calculated Helmert contrasts

Return type

array

oapackage.oahelper.isstr(s: Any) → bool
oapackage.oahelper.joinArrayLists(ww)

Concetenate a list of array lists into a single list

oapackage.oahelper.jseq(xx, comb)

Convert array to array_link object

Parameters

array (numpy array or array_link) – array to convert

Returns

array_link

oapackage.oahelper.mkdirc(directory_name: str) → str

Create directory

oapackage.oahelper.monitorSizes(verbose=0)

Return monitor sizes

oapackage.oahelper.nArrayFile(filename, verbose=1)

Return number of arrays in file

Parameters

afile (str) – name of array file

oapackage.oahelper.niceplot(ax, fig=None, despine=True, verbose=0, figurebg=True, tightlayout=True, legend=None, almost_black='#222222')

Create a good looking plot

The code:

  • removes spines

  • makes legend and spines lighter

  • makes legend lighter

oapackage.oahelper.oaIsBinary(filename: str) → bool

Return true if array file is in binary format

oapackage.oahelper.oainfo(filename, verbose=1)

Print information about a file containing arrays

oapackage.oahelper.parseProcessingTime(logfile, verbose=0)

Parse a log file to calculate the processing time

oapackage.oahelper.plot2Dline(line, *args, **kwargs)

Plot a 2D line in a matplotlib figure

oapackage.oahelper.randomizearrayfile(input_filename, output_filename, verbose=1)

Randomize a file with orthogonal arrays

Each array is transformed with a random transformation

Parameters

  • afile (str) – input file

  • afileout (str) – output file

oapackage.oahelper.runExtend(N, k, t=3, l=2, verbose=1, initsols=None, nums=[], algorithm=None)

Run extension algorithm and return arrays

Parameters

  • N (int) – number of rows

  • k (int) – number of columns to extend to

  • t (int) – strength of the arrays

  • l (int) – factors of the designs

  • initsols (None or list) – list of arrays to extend, None to start with root

Returns

list of generated designs

Return type

list

Example

>>> import oapackage
>>> designs = oapackage.oahelper.runExtend(16, 5, 3, verbose=0)
oapackage.oahelper.runcommand(cmd: str, dryrun=0, idstr: None = None, verbose: int = 1, logfile: Optional[str] = None, shell: bool = True)

Run specified command in external environment

Parameters

cmd – Command to execute

Returns

return value of the shell command

Return type

r (int)

oapackage.oahelper.safemax(data, default=0)

Return maximum of array with default value for empty array

Parameters

  • data (array or list) – data to return the maximum

  • default (obj) – default value

Returns

maximum value in the array or the default value

Return type

object

oapackage.oahelper.safemin(data, default=0)

Return mininum of array with default value for empty array

Parameters

  • data (array or list) – data to return the maximum

  • default (obj) – default value

Returns

minimum value in the array or the default value

Return type

object

oapackage.oahelper.selectArrays(infile, outfile, idx, afmode=0, verbose=1, cache=1)

Select arrays in a file by indices

Parameters

  • infile (str) – file with designs

  • outfile (str) – output file with designs

  • inx (list of indices) –

Returns

None

oapackage.oahelper.selectArraysInFile(infile, outfile, idx, afmode=0, verbose=1, cache=1)

Select arrays in a file by indices

Parameters

  • infile (str) – file with designs

  • outfile (str) – output file with designs

  • inx (list of indices) –

Returns

None

oapackage.oahelper.selectJ(sols0, jj=5, jresults=None, verbose=1)

Select only arrays with J-characteristics non-zero

We asssume the designs are in even-odd ordering (i.e. only check the J value of first columns)

oapackage.oahelper.selectParetoArrays(array_list, pareto_object)

Select arrays using a Pareto object

Parameters

  • array_list (list) – list of arrays

  • pareto (object) – oapackage Pareto object

Returns

list with all Pareto optimal designs

Return type

list

oapackage.oahelper.series2htmlstr(ad, html=1, case=0)

Convert arraydata_t to html formatted string

oapackage.oahelper.setWindowRectangle(x, y=None, w=None, h=None, mngr=None, be=None)

Position the current Matplotlib figure at the specified position

oapackage.oahelper.sortcols(array)

Sort columns of an array, return indices

The array is sorted low to high with the row column as the major row.

Parameters

array (numpy array) –

Returns

indices of columns of sorted array

Return type

list

oapackage.oahelper.sortrows(x)

Sort rows of an array, return indices

The array is sorted low to high with the first column as the major column.

Parameters

array (numpy array) –

Returns

indices of rows of sorted array

Return type

list

oapackage.oahelper.static_var(varname, value)

Helper function to create a static variable

oapackage.oahelper.testHtml(html_code=None)

Test a short snippet of HTML

oapackage.oahelper.test_checkFiles()
oapackage.oahelper.test_selectJ()
oapackage.oahelper.tilefigs(lst, geometry, ww=None, raisewindows=False, tofront=False, verbose=0)

Tile figure windows on a specified area

oapackage.oahelper.timeString(tt=None) → str

Return a string with the current time or specified time

Parameters

tt (struct_time or None) – time to convert

Returns

Formatted time

oapackage.oahelper.tprint(string, dt=1, output=False)

Print progress of a loop every dt seconds

oapackage.oahelper.write_text_arrayfile(filename: str, designs: List[Any], comment: Optional[str] = None)

Write designs to disk in text format

oapackage.scanf module

oapackage.scanf.sscanf(inputString, formatString)

Simple scanf function

Parameters

  • inputString (str) – string to be parsed

  • formatString (str) – specification

Returns

list of parsed arguments

Return type

list