professor is hosted by Hepforge, IPPP Durham

professor.tools

This module contains helper functions for common tasks in the Professor system. Some may also be useful for user scripts, such as logging and file/directory handling.

professor.tools.io

Helper module with static methods to check for directories and access rights, and some helpers for file and directory creation and handling, with suitable checks and permissions.

The makeDir() function is a handy way to create a readable/writeable directory without having to manually do all the edge-case checks that the native :module:`os` module tools require.

The is* tests return true or false, i.e. are just packaged versions of standard I/O functions from os and os.path. The assert* tests, by contrast, raise an IOTestFailed exception if the condition is not met.

The isFile* tests actually test that the path is not a directory. This allows use with pipes, links, etc. as well as actual files.

Note

The exception is raised here and not in the functions where the checks are performed to save some typing, because usually such an IO error means that the script fails. If the script should continue, the exception can be ‘excepted’.

Todo

Allow user to pass in an error-handling function as an argument, rather than see the exception?

Todo

Remove test* aliases for I/O asserts.

professor.tools.io.assertDirR(path)

Assert that ‘path’ is a dir-like object and readable.

professor.tools.io.assertDirRW(path)

Assert that ‘path’ is a dir-like object and readable & writeable.

professor.tools.io.assertDirW(path)

Assert that ‘path’ is a dir-like object and writeable.

professor.tools.io.assertFileR(path)

Assert that ‘path’ is a file-like object and readable.

professor.tools.io.assertFileRW(path)

Assert that ‘path’ is a file-like object and readable and writeable.

professor.tools.io.assertFileW(path)

Assert that ‘path’ is a file-like object and writeable.

professor.tools.io.isDirR(path)

Check that ‘path’ is a dir-like object and readable.

professor.tools.io.isDirRW(path)

Check that ‘path’ is a dir-like object and readable & writeable.

professor.tools.io.isDirW(path)

Check that ‘path’ is a dir-like object and writeable.

professor.tools.io.isFileR(path)

Check that ‘path’ is a file-like object and readable.

professor.tools.io.isFileRW(path)

Check that ‘path’ is a file-like object and readable and writeable.

professor.tools.io.isFileW(path)

Check that ‘path’ is a file-like object and writeable.

professor.tools.io.makeDir(path)

Make sure that directory exists, creating it if it doesn’t already.

Parameters :

path : str

The path to check/create

professor.tools.io.testReadDir(path)

Assert that ‘path’ is a dir-like object and readable.

professor.tools.io.testReadFile(path)

Assert that ‘path’ is a file-like object and readable.

professor.tools.io.testReadWriteDir(path)

Assert that ‘path’ is a dir-like object and readable & writeable.

professor.tools.io.testReadWriteFile(path)

Assert that ‘path’ is a file-like object and readable and writeable.

professor.tools.io.testWriteDir(path)

Assert that ‘path’ is a dir-like object and writeable.

professor.tools.io.testWriteFile(path)

Assert that ‘path’ is a file-like object and writeable.

professor.tools.decorators

Library with useful method/function decorators:

virtualmethod

A little tool to make interface definition and inheritance easier. Allows completely virtual methods like in C++:

C{ virtual void func(...) = 0; }

Usage example:

>>> class Super:
...    @virtualmethod
...    def virt(arg1, arg2):
...        pass
...
>>>
>>> class Sub(Super):
...     def virt(arg1, arg2):
...         pass
...
>>> mum = Super()
>>> daughter = Sub()
>>> mum.virt(1, 2)
[...]
VirtualMethodError: virtual method "virt" called!

deprecated

Use this if you want to log a deprecation method with warning priority everytime a function is called.

Usage:

>>> def new(*args, **kwargs):
>>>     pass
>>>
>>> @deprecated(new)
>>> def old(*args, **kwargs):
>>>     pass
>>> old(foo, bar)
>>> # some warning log
or:
>>> @deprecated("newfunction")
>>> def oldname(*args, **kwargs):
>>>     pass
>>> old(foo, bar)
>>> # some warning log
exception professor.tools.decorators.VirtualMethodError

Bases: exceptions.Exception

professor.tools.decorators.addmethodattribute(attrname, attrvalue)

Add an attribute to a method.

Be careful if combining with other decorators that usually do not care about method attributes.

Parameters attrname : str

The attribute identifier.
attrvalue : any
The attribute value
professor.tools.decorators.deprecated(arg=None)

Throw a warning everytime an old function is called.

If the deprecated decorator gets a string argument it treats it as the name of the new function that replaces the deprecated one.

Parameters :

arg : str,callable

The new function name, if it’s a string. Usage:

>>> @deprecated("new function name")
... def f(foo, bar):
[...]

The old function, if it’s not a string. Usage:

>>> @deprecated
... def f(foo, bar):
[...]

TODO: The code might be clearer if the decorator was a callable class :

rather than a function with many nested sub-functions.

professor.tools.decorators.virtualmethod(f)

Descriptor function for virtual methods.

Returns a function always raising a VirtualMethodError when called.

professor.tools.stats

Functions for statistical measures and correlations.

professor.tools.stats.checkForClustering(plist, K, param)
professor.tools.stats.convertCovMatToArray(covmat, names=None)

This converts a dict-type correlation or covariance matrix into an array-type matrix, suitable for e.g. the eigenDecomposition.

professor.tools.stats.convertCovMatToCorrMat(covmat)

This converts the dict-type covariance matrix into a dict-type correlation matrix.

professor.tools.stats.gauss(x, mu=0, sigma=1)

Calculate value of a Gaussian at x.

professor.tools.stats.getCorrelation(covmat, par1, par2)

Returns the correlation of two parameters using the covariance matrix.

covmat has to be a dictionary with keys as such: (par_i, par_j) e.g. as stored in MinimizationResult.covariance

professor.tools.stats.getCovMatFromSample(sample)

sample is a dict {PARAM:[values...] ...}

professor.tools.stats.n_choose_k(n, k)

Calculate the binomial coefficent of n over k

Deprecated: this is an unsafe implementation, use prof.tools.permut.nCr instead.

TODO: remove!

professor.tools.stats.rms(alist)

Compute the RMS of a number list.

professor.tools.stats.weightedMean(tuplelist)

Compute weighted mean of a tuple list, e.g. [(x0, sigma x0), (x1, sigma x1), ...]

professor.tools.permut

Tools for generating and handling combinatoric permutations.

professor.tools.permut.getIntersection(*lists)

return the intersection of an arbitrary number of lists

professor.tools.permut.nCr(n, r)
professor.tools.permut.randomUniqueCombinations(items, nchoose, howmany=None)

Create a list of unique sets of nchoose elements selected from items.

professor.tools.permut.shuffledCombinations(items, n, length=False)
professor.tools.permut.xrandomUniqueCombinations(items, nchoose, howmany=None)

Iterate through a list of unique sets of nchoose elements selected from items.

professor.tools.permut.xuniqueCombinations(items, n)

Recursively construct all combinations, without explicitly holding them all in memory. Deterministic, highly-correlated ordering of results.

professor.tools.eigen

Functions for handling eigen-decompositions of covariance matrices and the like. Mostly kept general in terms of NumPY/SciPy data objects, although some specifics to MinimizationResult may also occur until there’s an obvious better place to put them.

professor.tools.eigen.eigenDecomposition(mat)

Given a symmetric, real NxN matrix, M, an eigen decomposition is always possible, such that M can be written as M = T_transp * S * T (orthogonal transformation) with T_transp * T = 1_N and S being a diagonal matrix with the eigenvalues of M on the diagonal.

Returns :

T_trans : numpy.matrix

S : numpy.ndarray

The real eigen values.

T : numpy.matrix

professor.tools.eigen.getExtremalDirections(covmat)

Calculate an extremal direction (of a MinimizationResult) based on a diagonalised covariance matrix.

If covmat is a ParameterMatrix object, ParameterPoint objects are returned.

Parameters :

covmat : array_like, ParameterMatrix

The (non-diagonal) covariance matrix.

Returns :

shallow : numpy.ndarray, ParameterPoint

The direction along the largest eigenvalue.

steep : numpy.ndarray, ParameterPoint

The direction along the smallest eigenvalue.

professor.tools.eigen.transformParameter(parameter, T_transp)

This transforms a parameter into the space where a certain covariance matrix is diagonal.

parameter has to be a list

professor.tools.pointsampling

Random generator tools for sampling points in a space.

class professor.tools.pointsampling.RandomPointGenerator(range_)

Bases: object

Generate random parameter points.

The numpy RNG is used.

Attributes

_range ParameterRange The range from which to sample.

Methods

generate(num)

Return a Python generator with new points.

Parameters :

num : int

The number of points.

newPoint()

Get a new random point.

static seed(SEED)

Pass-through to numpy.random.seed.

class professor.tools.pointsampling.ScanPointGenerator(range_)

Bases: professor.tools.pointsampling.RandomPointGenerator

Generate line scan parameter points.

Different modes of line generation are available through factory functions:

mkDiagonal
sample along the diagonal of the given hyper cube
mkSteep, mkShallow
sample along the a line through a point of tuned values in the direction of the extremal uncertainties. The directions are calculated from the covariance matrix estimated by the minimizer.

Attributes

_range Parameterrange The endpoints of the line.

Methods

generate(num)

Return a Python generator with new points.

Parameters :

num : int

The number of points.

classmethod mkDiagonal(range_, pivot=None, symmetric=False)

Return a point generator along the diagonal of range_.

classmethod mkShallow(range_, result, symmetric=False)

Return a point generator along the ‘shallow’ direction of the covariance matrix from result.

Parameters :

range_ : ParameterRange

The extremal parameter values that are allowed.

result : MinimisationResult

symmetric : bool

Make the line symmetric around result.

classmethod mkSteep(range_, result, symmetric=False)

Return a point generator along the ‘steep’ direction of the covariance matrix from result.

Parameters :

range_ : ParameterRange

The extremal parameter values that are allowed.

result : MinimisationResult

symmetric : bool

Make the line symmetric around result.

classmethod mkSubRangeDiagonal(range_, center)

Return a point generator along the diagonal of the maximal sub-hypercube of range_ centered at center.

The direction is parallel to the diagonal of range_.

Parameters :

center : ParameterPoint

A point, defining the center of the sub-range.

newPoint(t)

Get a new point along the line.

Parameters :

t : float

The position along the line.

static seed(*args, **kwargs)

professor.tools.config