API reference

noctiluca.parallel 

Parallelization for noctiluca functions

class noctiluca.parallel.DummyExecutor

Bases: Executor

submit(fun, *args, **kwargs)

Submits a callable to be executed with the given arguments.

Schedules the callable to be executed as fn(*args, **kwargs) and returns a Future instance representing the execution of the callable.

Returns:: A Future representing the given call.

class noctiluca.parallel.Parallelize(n=None)

Bases: object

Context manager for parallelization

We indicate in docstrings that certain functions are “parallel-aware”, if they make use of this functionality

Parameters:

n (int, optional) – how many cores to use; defaults to maximum available
chunksize (int, optional) – chunk size for parallel execution, when used. Note that the default of 1 might make things very slow (as also noted in the multiprocessing docs).

Examples

>>> import noctiluca as nl
...
... with nl.Parallelize():
...     # parallel-aware stuff goes here

Notes

It is generally recommended to avoid hyperthreading when parallelizing computations; this can be achieved by running >>> import os … os.environ[‘OMP_NUM_THREADS’] = ‘1’

at the very beginning of your code, before any other imports (technically: before multiprocessing is imported, which e.g. this module does).

map(func, todo, chunksize=None)

static serial_map(*args, chunksize=None, **kwargs)

noctiluca.parallel.chunky(kwarg_name='chunksize', default=1)

A decorator for functions using the Parallelize interface

This decorator adds a kwarg ‘chunksize’ (or custom name) and sets parallel._chunksize accordingly before running the function. This facilitates user control over parallelization level.

Parameters:

kwarg_name (str) – the name for the kwarg to add
default (int) – the default chunksize value

noctiluca.plot 

Provide simple plotting capabilities

noctiluca.plot.vstime(traj, ax=None, maskNaNs=True, label='', **kwargs)

Plot a given trajectory vs time

Parameters:

traj (Trajectory) – the trajectory to plot
ax (matplotlib axes, optional) – the axes to plot into. Defaults to plt.gca().
maskNaNs (bool, optional) – whether to plot through missing values. matplotlib by default leaves gaps when it encounters nan values; this can be either quite useful to stay aware of missing data, or equally suboptimal, since a single valid frame surronded by nan’s will be missing from the plot (with default settings). Since the latter is a bigger problem, by default we plot a continuous line and just ignore missing frames; set maskNaNs = False to plot with gaps.
label (str or None, optional) – prefix for plot label. Curves will be labelled with label+[N=..]+ d=... Set label=None to prevent labelling.
kwargs (keyword arguments) – forwarded to ax.plot().

Returns:

list of Line2D – the output of ax.plot(), ordered by (N, d). Use this to customize the plot.

Notes

If ax is specified, the trajectory plot is simply added to the existing axes; if it is unspecified, we plot to plt.gca() and adjust some optics (e.g. constrain xticklabels to be integers)

noctiluca.plot.spatial(traj, ax=None, dims=(0, 1), maskNaNs=True, label='', **kwargs)

Plot a trajectory in space

Parameters:

traj (Trajectory) – the trajectory to plot
ax (matplotlib axes, optional) – the axes to plot into. Defaults to plt.gca().
dims (2-tuple of int, optional) – which dimensions to plot
maskNaNs (bool, optional) – whether to plot through missing values. matplotlib by default leaves gaps when it encounters nan values; this can be either quite useful to stay aware of missing data, or equally suboptimal, since a single valid frame surronded by nan’s will be missing from the plot (with default settings). Since the latter is a bigger problem, by default we plot a continuous line and just ignore missing frames; set maskNaNs = False to plot with gaps.
label (str or None, optional) – prefix for plot label. Curves will be labelled with label+[N=..]. Set label=None to prevent labelling.
kwargs (keyword arguments) – forwarded to ax.plot().

Returns:

list of Line2D – the output of ax.plot(), ordered by (N, d). Use this to customize the plot.

Notes

If ax is specified, the trajectory plot is simply added to the existing axes; if it is unspecified, we plot to plt.gca() and adjust some optics (e.g. constrain xticklabels to be integers)

noctiluca.plot.msd_overview(dataset, ax=None, dt=1.0, **kwargs)

Plot individual and ensemble MSDs of the given dataset

All keyword arguments are forwarded to plt.plot() for plotting of the individual trajectory MSDs

Parameters:

dataset (TaggedSet of Trajectory) – the dataset to use
ax (matplotlib axes, optional) – default is to plot to plt.gca()
dt (float, optional) – the time step between two frames of the trajectory; this will simply rescale the horizontal axis of the plot.

Returns:

list of Line2D – all the lines added to the axes. The last entry in the list is the plot of the ensemble mean

noctiluca.taggedset 

class noctiluca.taggedset.TaggedSet(iterable=[], hasTags=True)

Bases: object

A set with tags for each object.

This class can be used as an iterator in constructs such as for datum in myset: .... The subset to be iterated over can be adjusted using makeSelection. If you also need the tags for each datum, use myset(giveTags=True).

For processing data (in the sense of “applying a function to all of them”) it is often useful to simply use the built-in map. If the function in question has to overwrite the data, you can use apply. Note that in-place modification can be achieved with map().

Parameters:

iterable (iterable of data or (datum, tags) pairs, optional) – most useful things to use here: an actual list, or a generator. Remember to set hasTags accordingly.
hasTags (bool, optional) – whether the iterable in the first argument gives data only or (datum, tags) pairs.

Notes

For a TaggedSet myset, the following operations are defined:

len(myset): return number of data in current selection
myset(giveTags): return a generator yielding single data or (datum, tags) pairs, depending on the value of giveTags (False by default).
iter(myset): shortcut for myset(giveTags=False). This enables the construction for datum in myset: ...
myset[i]: element access within the current selection. You can use indices from 0 to len(myset)-1.
myset |= otherset: add the data in otherset into myset. This is a shortcut for myset.mergein(otherset).

static makeTagsSet(tags)

Input reformatting, mostly internal use.

Make sure that the frequently used tags argument is a set of strings.

Parameters:: tags (str, list of str, set of str, or None)
Returns:: set of str

add(datum, tags=None)

Append the given datum with the given tags.

Parameters:

datum (object) – the datum to append
tags (str, list of str, or set of str, optional) – the tags to attach to this new datum

Notes

The newly added datum will be part of the current selection.

__call__(giveTags=False, randomize=False)

Iterate through the current selection of the set.

Parameters:

giveTags (bool, optional) – whether to yield only data or (datum, tags) pairs.
randomize (bool, optional) – set to True to randomize the order in which data are yielded.

Yields:

datum – the data in the current selection
set of str, optional – the tags associated with the datum

See also

makeSelection

makeSelection(arg=None, **kwargs)

Mark a subset of the current set as ‘current selection’. For most purposes, the set will behave as if it contained only these data.

There are multiple ways to select data. Which one is used depends on the kwargs given. With increasing preference, these methods are

select randomly: use the kwargs nrand or prand
select by tag: use the kwargs tags and logic
select with a user-specified function: use kwarg selector

Call this without arguments to reset the selection to the whole dataset.

Parameters:

arg (<various>) – catch-all argument that dispatches to any of the below by type (e.g. str is interpreted as single tag, float as prand, any iterable as tags, etc.)
nrand (int) – number of trajectories to select at random
prand (float, in [0, 1]) – fraction of trajectories to select at random
random_seed (int, str, or bytes, optional) – seed for random selection. Note that this can be a string.
tags (str, list of str, or set of str) – the tags to select. How these go together will be determined by logic.
logic (callable with signature bool = logic(<list of bool>)) – the logic for handling multiple tags. Set this to (the built-in) all to select the data being tagged with all the given tags, or to any (the default) to select the data having any of the given tags.
selector (callable with signature bool = selector(datum, tags)) – should expect the datum and a set of tags as input and return True if the datum is to be selected, False otherwise.
refining (bool, optional) – set to True to apply the current selection scheme only to those data that are already part of the selection. This can be used to successively refine a selection by using different selection methods (e.g. first by tag, then by some other criterion).

refineSelection(*args, **kwargs): A wrapper for makeSelection(..., refining=True).

See also

makeSelection

saveSelection()

Return a copy of the current selection for reference.

This is useful when planning to undo subsequent selections without having to redo the whole selection from scratch.

Returns:: list of bool – the current selection.

See also

restoreSelection, makeSelection

restoreSelection(selection)

Restore a previously saved selection.

Parameters:: selection (list of bool) – the selection that was saved using saveSelection. Will be copied.

See also

saveSelection, makeSelection

copySelection()

Generate a new (copied) set from the current selection.

Returns:: The new set

See also

makeSelection

deleteSelection()

Remove the selected entries from the set

See also

makeSelection, copySelection

Notes

Since everything in the current selection is deleted, the selection will be reset.

mergein(other, additionalTags=None)

Add the contents of the TaggedSet other to the caller.

Parameters:

other (TaggedSet) – the set whose data to add
additionalTags (str, list of str, or set of str, optional) – additional tag(s) to add to all of the new data.

Notes

This can also be invoked as self |= other. In that case no additional tags can be added.

addTags(tags)

Add new tag(s) to all data in the current selection

Parameters:: tags (str, list of str, or set of str) – the tag(s) to add

tagset()

Return the set of all tags in the current selection.

Returns:: set of str – set of all tags in the current selection

apply(fun, inplace=False)

Apply a given function to all data.

Parameters:

fun (callable) – should have signature datum = fun(datum). Will be mapped across the current selection.
inplace (bool, optional) – set to True to run in place, i.e. overwrite the original entries. Otherwise, a new TaggedSet with the processed data will be returned

Returns:

TaggedSet or None

See also

builtins.map

Notes

This function is applicable when modifying the actual data in the TaggedSet; for simply applying a function to all data in the set, use python’s built-in map(). The benefit of apply() over a construction like TaggedSet(map(fun, data)) is just that it keeps the tags in order.

This function is parallel-aware (ordered).

map_unique(fun)

Apply a function to all data and check that the result is unique.

Parameters:: fun (callable with signature ret = fun(datum)) – the function to apply. The return value can be any object for which ret1 == ret2 is defined.
Returns:: ret (object) – if fun returns the same value on all data, that value.
Raises:: RuntimeError – if the return value of fun is not the same on all data.

See also

builtins.map

Notes

Returns None if len(self) == 0 (i.e. the caller / its current selection does not contain any data)

noctiluca.trajectory 

class noctiluca.trajectory.Trajectory(data=None, t=None, *, localization_error=None, parity=None, **kwargs)

Bases: object

kwargs are written to meta
(N, T, d), (T, d), (T,) array for data
generic meta entries got converted to attributes
localization error is (d,), (N, d), (N, T, d)

property N: Number of loci

property T: Length in frames

property F: Number of valid frames

property d: Number of dimensions

count_valid_frames()

Return the number of frames that have data.

We regard a frame as unusable as soon as any data is missing. So this function counts the number of frames in the trajectory where none of the data is np.nan.

Returns:: int

See also

F

__getitem__(key)

Element-access

Parameters:: key (index or slice into the T dimension)
Returns:: np.ndarray – the corresponding part of the trajectory.

Notes

The N dimension will be squeezed, i.e. for single locus trajectories that first dimension will be removed. The T dimension of the output follows the numpy conventions (i.e. depends on the format of key), while d is guaranteed to be present.

abs(order=None, keepmeta=None)

Modifier: 2-norm (or other norm, see order)

Parameters:

order (float or None, optional) – order of the norm; see numpy.linalg.norm’s ord parameter. Defaults to 2-norm (i.e. Euclidean norm)
keepmeta (list of str or None, optional) – which entries from the meta dict to copy to the new trajectory

Returns:

Trajectory

Notes

For multi-locus trajectories, this will take the norm of each locus individually. To get a Trajectory of relative distance, use Trajectory.relative().abs().

See also

diff, dims, relative

diff(dt=1, keepmeta=None)

Modifier: displacements

Calculate the displacements over dt frames.

Parameters:

dt (integer) – the time lag to use for displacement calculation default: 1, i.e. frame to frame displacements
keepmeta (list of str or None, optional) – which entries from the meta dict to copy to the new trajectory

Returns:

Trajectory

See also

abs, dims, relative

dims(key, keepmeta=None)

Modifier: select dimensions

Parameters:

key (list of int, or slice) – which dimensions to use. Attention: this cannot be a single int. To get the i-th spatial component, use traj.dims([i]).
keepmeta (list of str or None, optional) – which entries from the meta dict to copy to the new trajectory

Returns:

Trajectory

See also

abs, diff, relative

rescale(factor, keepmeta=None)

Modifier: rescale all data by a constant factor

Parameters:

factor (float)

Returns:

Trajectory
keepmeta (list of str or None, optional) – which entries from the meta dict to copy to the new trajectory

See also

abs, offset

offset(off, keepmeta=None)

Modifier: shift the trajectory by some offset

Parameters:

off (float or array of shape (d,), (N, d), or (N, T, d)) – the offset to add
keepmeta (list of str or None, optional) – which entries from the meta dict to copy to the new trajectory

Returns:

Trajectory

See also

abs, rescale

relative(ref=None, keepmeta=None)

Modifier: Return Trajectory of pairwise distances

Parameters:

ref (int or None, optional) – which locus to use as reference. If None (the default) return sequential differences (i.e. 2-1, 3-2, 4-3, ...). Otherwise, returned distances are 1-ref, 2-ref, ...
keepmeta (list of str or None, optional) – which entries from the meta dict to copy to the new trajectory

Returns:

Trajectory

Raises:

ValueError – when called on trajectories with only a single locus

See also

abs, diff, dims

API reference

noctiluca.parallel

noctiluca.plot

noctiluca.taggedset

noctiluca.trajectory

noctiluca.parallel 

noctiluca.plot 

noctiluca.taggedset 

noctiluca.trajectory 