tramway.analyzer package¶

class tramway.analyzer.RWAnalyzer¶

Bases: tramway.analyzer.attribute.WithLogger

A RWAnalyzer object gathers the parameters of all the processing steps of a standard processing chain, from SPT data loading/generation to inferring model parameters at microdomains.

The supported steps are defined in a declarative way with special attributes; these steps and corresponding attributes are as follows:

images: microscopy images
localizer: single molecule localization
tracker: single particle tracking
spt_data: SPT data loading or generation
roi: regions of interest
tesseller: spatial segmentation
time: temporal segmentation of the tracking data
sampler: assignment of SPT data points to microdomains
mapper: estimation of model parameters at each microdomains

Most attributes are self-morphing, i.e. they first are initializers and exhibit from_… methods (for example from_dataframe() and from_ascii_file() for spt_data) and then, once any such initializer method is called, they specialize into a new attribute and exhibit specific attributes depending on the chosen initializer:

from tramway.analyzer import *
a = RWAnalyzer()
a.spt_data.from_ascii_files('my_data_repository/*.txt')

The more conventional assignment form is also available using functions of modules exported by the tramway.analyzer subpackage. These modules are named following the attribute they are dedicated to:

a = RWAnalyzer()
a.spt_data = spt_data.from_ascii_files('my_data_repository/*.txt')

In most cases, a third form is also available, with a class constructor:

a = RWAnalyzer()
a.spt_data = spt_data.SPTAsciiFiles('my_data_repository/*.txt')

Anyway, most of the attributes of an RWAnalyzer object are properties that perform various checks and may raise exceptions if misused.

Specialized attributes can also exhibit self-morphing attributes. For example, regions of interest can be defined globally using the main roi attribute, or on a per-SPT-datafile basis:

a = RWAnalyzer()
a.spt_data.from_ascii_files('my_data_repository/*.txt')
a.roi.from_squares(roi_centers, square_size)

or

a = RWAnalyzer()
a.spt_data.from_ascii_files('my_data_repository/*.txt')
for spt_file in a.spt_data:
    spt_file.roi.from_squares(roi_centers, square_size)

In the above example, per-dataset ROI definition is useful when multiple datasets are loaded and the ROI may differ between datasets. The main roi attribute is still convenient as it allows to iterate over all the defined ROI, omitting the spt_data loop (continues any of the code blocks above):

for r in a.roi:
    roi_spt_data = r.crop()

The ROI object is denoted r here. Name roi already exists if the analyzer module is imported with from tramway.analyzer import *. In this case, roi points to the roi module.

Note there exists multiple iterators for the collections of ROI. In the further examples of iterated ROI, the preferred iterator is made explicit. See the documentation for the roi attribute for more information about the available iterators.

While the spt_data and roi attributes act as data providers, the time, tesseller, sampler and mapper attributes do not feature direct access to the data and require the SPT data to be passed as input argument to their main processing methods. For example:

a.tesseller.from_plugin('kmeans')
for r in a.roi.as_support_regions():
    roi_spt_data = r.crop()
    tessellation = a.tesseller.tessellate(roi_spt_data)

Similarly, the images attribute defines data location, while the localizer and tracker attributes define processing steps on these data.

Other attributes drive the execution of the processing chain. The run() method launches the processing chain, which is operated by the pipeline attribute.

Various parallelization schemes are available, and the platform-specific implementation of these schemes are provided by the env attribute.

Last but not least, the RWAnalyzer features plotting utilities. Some of them are available through the mpl sub-attribute of some main RWAnalyzer attributes or items, for example images.mpl (Mpl), spt_data.mpl (Mpl), tesseller.mpl (Mpl), mapper.mpl (Mpl). In addition, the browser attribute can plot the inferred parameter maps from a Jupyter notebook, or calling the bokeh serve command:

from tramway.analyzer import *

a = RWAnalyzer()

# load the rwa files available in the current directory:
a.spt_data.from_rwa_files('*.rwa')

# help the analyzer locate this piece of code:
try:
    a.script = __file__
except NameError: # in a notebook
    a.script = 'MyNotebook.ipynb' # this notebook's name (please adapt)

a.browser.show_maps()

See also Browser for additional information on how to export data and figures while browsing the inferred parameter maps.

spt_data¶

SPT data accessor.

See SPTDataInitializer and SPTData.

roi¶

ROI accessor.

See ROIInitializer and ROI.

time¶

Time segmentation procedure.

See TimeInitializer and Time.

tesseller¶

Tessellation procedure.

See TessellerInitializer and Tesseller.

sampler¶

Sampling procedure.

See SamplerInitializer and Sampler.

mapper¶

Inference procedure.

See MapperInitializer and Mapper.

images¶

Microscopy image stacks.

See ImagesInitializer and Images.

localizer¶

Single molecule localization procedure.

See LocalizerInitializer and Localizer.

tracker¶

Single particle tracking procedure.

See TrackerInitializer and Tracker.

env¶

Environment backend for operating the pipeline.

If not set, the pipeline will run locally in the current interpreter.

See environments.

pipeline¶

Parallelization scheme.

See Pipeline.

run()¶

Launches the pipeline.

Alias for pipeline run().

add_collectible(collectible)¶

Designates a file generated on the worker side to be transferred back to the submit side.

Alias for pipeline add_collectible().

browser¶

Data visualization and export.

See Browser.

script¶

Path to the __main__ file in which the analyzer is defined.

Designating a script is required for parallelizing computations, or visualizing maps without explicitly calling the bokeh serve command (e.g. from a Jupyter notebook).

Alias for env script.

exception tramway.analyzer.SideEffectWarning¶: Bases: UserWarning

tramway.analyzer.artefact package¶

tramway.analyzer.attribute package¶

class tramway.analyzer.attribute.InitializerMethod(method, attrname=None)¶

Bases: object

Useful for explicit typing.

tramway.analyzer.attribute.initializer_method(method, attrname=None)¶: Properly set the docstring for the wrapped method.

tramway.analyzer.images package¶

class tramway.analyzer.images.Images¶

Bases: tramway.analyzer.attribute.abc.Attribute

Abstract base class for the images attribute of an RWAnalyzer object.

as_frames(index=None, return_time=False)¶

Generator function; yields frames as arrays.

See for example as_frames().

crop_frames(bounding_box, index=None, return_time=False)¶

Generator function similar to as_frames(), with ROI cropping.

See for example crop_frames().

class tramway.analyzer.images.Image¶

Bases: object

Abstract base class for single image stacks an Images object contains.

class tramway.analyzer.images.ImagesInitializer(attribute_setter, parent=None)¶

Bases: tramway.analyzer.attribute.Initializer

Initial value for the RWAnalyzer images attribute.

from_… methods alters the parent attribute which specializes into an initialized Images object.

from_tiff_file(filepath)¶

Defines the raw single molecule imaging file.

Loading is not performed while calling this method.

from_tiff_files(filepattern)¶

Defines the raw single molecule imaging files.

Loading is not performed while calling this method.

class tramway.analyzer.images.RawImages(stacks, **kwargs)¶: Bases: tramway.analyzer.images.ImageIterator

class tramway.analyzer.images.ImageFiles(filepattern, **kwargs)¶: Bases: tramway.analyzer.images.ImageIterator

class tramway.analyzer.images.TiffFiles(filepattern, **kwargs)¶: Bases: tramway.analyzer.images.ImageFiles

tramway.analyzer.images.mpl module¶

class tramway.analyzer.images.mpl.Mpl(parent=None)¶

Bases: tramway.analyzer.attribute.AnalyzerNode

Matplotlib plotting utilities for 2D data; no time support.

plot(x, *args, origin=None, frame=None, **kwargs)¶

Converts localization data from micrometers to pixels and plots them.

Can overlay locations onto a frame image as plotted with imshow and default parameters (origin='upper').

roi(frame, origin, *args, axes=None, colormap='gray', **kwargs)¶

Plots a frame corresponding to a region of interest.

origin should be provided by cropping_bounds(), if frame is given by crop_frames().

Extra input arguments are passed to the imshow() function.

This method works in combination with spt_data.mpl.Mpl.plot().

tramway.analyzer.localizer package¶

class tramway.analyzer.localizer.UNetLocalizer(**kwargs)¶

Bases: tramway.analyzer.attribute.AnalyzerNode

Loads the weights of a U-Net network for image deconvolution.

Not implemented yet, as long as the UNet package is broken.

weights_locator¶

Uniform resource locator for the U-Net weights

Type:	str

localize(stack)¶: Not implemented yet, as long as the UNet package is broken.

class tramway.analyzer.localizer.LocalizerInitializer(attribute_setter, parent=None)¶

Bases: tramway.analyzer.attribute.Initializer

Initializer class for the RWAnalyzer localizer main attribute.

The localizer attribute self-modifies on calling any of the from_… methods.

from_UNet()¶

Loads a trained U-Net network for image deconvolution.

tramway.analyzer.tracker package¶

class tramway.analyzer.tracker.NonTrackingTracker(**kwargs)¶

Bases: tramway.analyzer.tracker.BaseTracker

Non-tracking tracker.

class tramway.analyzer.tracker.Tracker¶

Bases: tramway.analyzer.attribute.abc.Attribute

Abstract base class for the tracker attribute of an RWAnalyzer object.

class tramway.analyzer.tracker.TrackerInitializer(attribute_setter, parent=None)¶

Bases: tramway.analyzer.attribute.Initializer

Initializer class for the RWAnalyzer tracker main attribute.

The tracker attribute self-modifies on calling any of the from_… methods.

from_single_particle()¶

Considers every single molecule localization datablocks as single trajectories.

tramway.analyzer.spt_data package¶

class tramway.analyzer.spt_data.SPTData¶

Bases: tramway.analyzer.attribute.abc.Attribute

Abstract base class for the spt_data attribute of an RWAnalyzer object.

as_dataframes(source=None)¶

Generator function; yields pandas.DataFrame objects.

source can be a source name (filepath) or a boolean function that takes a source string as input argument.

bounds¶

Lower (index min) and upper (index max) bounds for the SPT data

Type:	pandas.DataFrame

columns¶

Data column names

Type:	list of str

discard_static_trajectories(dataframe=None, min_msd=None)¶

The minimum mean-square-displacement is set to the localization error per default.

If an input dataframe is given, then discard_static_trajectories() returns the processed dataframe and self does not maintain any copy of it.

Otherwise, discard_static_trajectories() applies inplace to the internal dataframe and does not return any dataframe. Note that it may set a flag instead of actually processing the internal dataframe, for the parcimonious processing in regions of interest only.

frame_interval¶

Time interval between successive frames, in seconds

Type:	float

localization_error¶

Localization error in $\mu m^2$

Type:	float

reset_origin(columns=None, same_origin=False)¶: Translates the lower bound of the spatial data to zero.

class tramway.analyzer.spt_data.SPTDataItem¶

Bases: object

Abstract base class for SPT data blocks an SPTData object contains.

analyses¶

Analysis tree

Type:	Analyses

bounds¶

Lower (index min) and upper (index max) bounds for the SPT data

Type:	pandas.DataFrame

columns¶

Data column names

Type:	list of str

dataframe¶

Raw SPT data

Type:	pandas.DataFrame

frame_interval¶

Time interval between successive frames, in seconds

Type:	float

localization_error¶

Localization error in $\mu m^2$

Type:	float

source¶

File path or identifier

Type:	str

class tramway.analyzer.spt_data.SPTParameters(localization_precision=None, localization_error=None)¶

Bases: object

Mixin class for storing common experimental parameters, including the localization error, time interval and temperature.

Children classes should define the _frame_interval, _localization_error and _temperature attributes, or overload the frame_interval, localization_error and temperature properties.

Default values should be None.

discard_static_trajectories(dataframe, min_msd=None, **kwargs)¶

The minimum mean-square-displacement is set to the localization error per default.

If an input dataframe is given, then discard_static_trajectories() returns the processed dataframe and self does not maintain any copy of it.

Otherwise, discard_static_trajectories() applies inplace to the internal dataframe and does not return any dataframe. Note that it may set a flag instead of actually processing the internal dataframe, for the parcimonious processing in regions of interest only.

dt¶

Alias for the frame_interval property

Type:	float

frame_interval¶

Time interval between successive frames, in seconds

Type:	float

localization_error¶

Localization error in $\mu m^2$

Type:	float

localization_precision¶

Localization precision in $\mu m$; localization_error $\sigma^2$ is affected by localization_precision $\sigma$ and vice versa

Type:	float

set_precision(precision)¶

Sets the numerical precision of the raw data.

Parameters:	precision (dict or str) – any of `'half'`, `'single'`, `'double'`, or a dictionnary of dtypes with column names as keys, as admitted by `pandas.DataFrame.astype()`.

temperature¶

Temperature in K; can be set as a value-unit pair, with unit any of 'K', 'C' and 'F'

Type:	float

time_step¶

Alias for the frame_interval property

Type:	float

class tramway.analyzer.spt_data.StandaloneDataItem¶

Bases: object

Partial implementation for single data item SPTData attribute.

class tramway.analyzer.spt_data.SPTDataIterator(**kwargs)¶

Bases: tramway.analyzer.attribute.AnalyzerNode, tramway.analyzer.spt_data.SPTParameters

Partial implementation for multi-item SPTData.

Children classes must implement the __iter__() method.

as_dataframes(source=None, return_index=False)¶

Generator function; yields pandas.DataFrame objects.

source can be a source name (filepath) or a boolean function that takes a source string as input argument.

bounds¶

Lower (index min) and upper (index max) bounds for the SPT data

Type:	pandas.DataFrame

discard_static_trajectories(dataframe=None, min_msd=None, **kwargs)¶

The minimum mean-square-displacement is set to the localization error per default.

If an input dataframe is given, then discard_static_trajectories() returns the processed dataframe and self does not maintain any copy of it.

Otherwise, discard_static_trajectories() applies inplace to the internal dataframe and does not return any dataframe. Note that it may set a flag instead of actually processing the internal dataframe, for the parcimonious processing in regions of interest only.

dt¶

Alias for the frame_interval property

Type:	float

filter_by_source(source_filter, return_index=False)¶

Generator function; similar to __iter__(); yields SPTDataItem objects.

source can be a single str value, or a set of str values, or a sequence of str values (the order is followed), or a callable that takes a str value and returns a bool value.

frame_interval¶

Time interval between successive frames, in seconds

Type:	float

localization_error¶

Localization error in $\mu m^2$

Type:	float

reload_from_rwa_files(skip_missing=False)¶

Reloads the SPT data and analysis tree from the corresponding rwa files.

The rwa file that corresponds to an SPT file should be available at the same path with the .rwa extension instead of the SPT file’s extension.

This method is known to fail with a TypeError exception in cases where not any matching .rwa file can be found.

Note

As this operation modifies the SPT data source and filepath attributes, aliases should be favored when identifying or filtering SPT data items.

self_update(new_self)¶

set_precision(precision)¶

Sets the numerical precision of the raw data.

Parameters:	precision (dict or str) – any of `'half'`, `'single'`, `'double'`, or a dictionnary of dtypes with column names as keys, as admitted by `pandas.DataFrame.astype()`.

temperature¶

Temperature in K; can be set as a value-unit pair, with unit any of 'K', 'C' and 'F'

Type:	float

time_step¶

Alias for the frame_interval property

Type:	float

class tramway.analyzer.spt_data.SPTDataInitializer(attribute_setter, parent=None)¶

Bases: tramway.analyzer.attribute.Initializer

Initial value for the RWAnalyzer spt_data attribute.

from_… methods alters the parent attribute which specializes into an initialized SPTData object.

from_ascii_file(filepath)¶

Sets a text file as the source of SPT data.

Note that data loading is NOT performed while calling this method. Loading is postponed until the data is actually required. This lets additional arguments to be provided to the RWAnalyzer spt_data attribute before the data are loaded.

tramway.analyzer.spt_data.mpl module¶

class tramway.analyzer.spt_data.mpl.LineDealer(ax, n=None, colors=['darkgreen', 'darkkhaki', 'darkmagenta', 'darkolivegreen', 'darkorange', 'darkorchid', 'darkred', 'darksalmon', 'darkseagreen', 'darkslateblue', 'darkslategray', 'darkviolet', 'deeppink', 'deepskyblue', 'dodgerblue', 'firebrick', 'forestgreen', 'gold', 'goldenrod', 'hotpink', 'indianred', 'indigo', 'lightblue', 'lightcoral', 'lightpink', 'lightsalmon', 'lightseagreen', 'lightskyblue', 'lightsteelblue', 'limegreen', 'maroon', 'mediumaquamarine', 'mediumorchid', 'mediumpurple', 'mediumseagreen', 'mediumslateblue', 'mediumspringgreen', 'mediumturquoise', 'mediumvioletred', 'midnightblue', 'navajowhite', 'navy', 'olive', 'olivedrab', 'orange', 'orangered', 'orchid', 'palegreen', 'paleturquoise', 'palevioletred', 'papayawhip', 'peachpuff', 'peru', 'pink', 'plum', 'powderblue', 'purple', '#663399', 'rosybrown', 'royalblue', 'saddlebrown', 'salmon', 'sandybrown', 'seagreen', 'sienna', 'skyblue', 'slateblue', 'springgreen', 'steelblue', 'tan', 'teal', 'thistle', 'tomato', 'turquoise', 'violet', 'wheat', 'yellowgreen'], **kwargs)¶

Bases: object

Makes glyphs for trajectories to be drawn as lines and keeps track of the trajectories passed to animate so that glyphs are freed as soon as possible and can be assigned to new trajectories.

animate(trajs, dt)¶

Makes the function to be passed as second positional argument to FuncAnimation.

Parameters:	trajs (DataFrame) – trajectories. dt (float) – time step.
Returns:	function that takes a list of index slices.
Return type:	callable

init_func()¶: To be passed as argument init_func to FuncAnimation.

plot(trajs)¶

Updates the glyphs with the active trajectories.

Parameters:	trajs (list) – list of active trajectories (dataframes).
Returns:	sequence of updated glyphs.
Return type:	tuple

tramway.analyzer.roi package¶

class tramway.analyzer.roi.BaseRegion(spt_data, label=None, **kwargs)¶

Bases: tramway.analyzer.attribute.AnalyzerNode

This class should not be directly instanciated. It brings basic functionalities to all the available representations of regions of interest, merely labelling and analysis registration.

class tramway.analyzer.roi.IndividualROI(spt_data, label=None, **kwargs)¶

Bases: tramway.analyzer.roi.BaseRegion

for typing only

class tramway.analyzer.roi.BoundingBox(bb, label, spt_data, **kwargs)¶

Bases: tramway.analyzer.roi.IndividualROI

See BoundingBoxes.

crop_frames(**kwargs)¶

Iterates and crops the image frames.

kwargs are passed to the Images crop_frames() method.

class tramway.analyzer.roi.SupportRegion(r, regions, spt_data, **kwargs)¶

Bases: tramway.analyzer.roi.BaseRegion

Union of overlapping ROI.

crop_frames(**kwargs)¶

Iterates and crops the image frames, based on bounding_box.

kwargs are passed to the Images crop_frames() method.

add_metadata(sampling, inplace=False)¶

Modifies sampling or returns a modified copy of sampling.

In both cases, returns the resulting Partition object.

add_sampling(sampling, label=None, comment=None, metadata='inplace')¶

If metadata=='inplace' (default), sampling is modified to store ROI-related information.

Pass metadata=True instead to store a copy of sampling in the analysis tree. Note however that sampling is copied only if modified.

class tramway.analyzer.roi.FullRegion(spt_data, label=None, **kwargs)¶

Bases: tramway.analyzer.roi.BaseRegion

Wraps the full dataset; does not actually crop.

A FullRegion can be both an individual ROI and a support region.

crop_frames(**kwargs)¶: Note

Time cropping is not supported yet.

class tramway.analyzer.roi.DecentralizedROIManager(first_record=None, **kwargs)¶

Bases: tramway.analyzer.attribute.AnalyzerNode

This class allows to iterate over the ROI defined at the level of each SPT data item.

as_individual_roi(index=None, collection=None, source=None, **kwargs)¶

Generator function; loops over all the individual roi.

Filtering is delegated to the individual SPTDataItem.roi attributes.

A callable filter takes a single key (int for indices, str for labels and paths) and returns a bool.

Parameters:	index (int, set of int, sequence of int, or callable) – individual ROI index filter; indices apply within a collection collection (str, set of str, sequence of str, or callable) – collection label filter source (str, set of str, sequence of str, or callable) – SPT data source filter

as_support_regions(index=None, source=None, **kwargs)¶

Generator function; loops over all the support regions.

Support regions are equivalent to individual ROI if group_overlapping_roi was set to False.

Filtering is delegated to the individual SPT data block roi attributes.

A callable filter takes a single key (int for indices, str for paths) and returns a bool.

Parameters:	index (int, set of int, sequence of int, or callable) – support region index filter source (str, set of str, sequence of str, or callable) – SPT data source filter

class tramway.analyzer.roi.ROIInitializer(attribute_setter, parent=None)¶

Bases: tramway.analyzer.attribute.Initializer

Initial value for the RWAnalyzer roi attribute.

from_… methods alters the parent attribute which specializes into an initialized ROI object.

from_bounding_boxes(bb, label=None, group_overlapping_roi=False)¶

Defines ROI as bounding boxes.

Parameters:	bb (sequence) – collection of bounding boxes, each bounding boxes being a pair of lower and upper bounds (numpy.ndarray) label (str) – unique label for the collection group_overlapping_roi (bool) – if `False`, `as_support_regions()` will behave similarly to `as_individual_roi()`, otherwise support regions are unions of overlapping ROI

tramway.analyzer.roi.utils module¶

tramway.analyzer.roi.utils.set_contiguous_time_support_by_count(points, space_bounds, time_window, min_points, min_segments=1, group_overlapping_roi=False, start_stop_min_points=None)¶

Parameters:

points (DataFrame) – location or translocation data
space_bounds (dict or sequence) – (collections of) boundaries, each boundary being a pair of NumPy arrays (lower, upper)
time_window (float or pair of floats) – window duration or window duration and shift
min_points (int) – desired minimum number of data rows per time segment
min_segments (int) – desired minimum number of selected time segments.
group_overlapping_roi (bool) – see RoiCollections

Returns:

similar to points, with an additional column for time: in each bound array.

Return type:

dict or list

tramway.analyzer.roi.utils.group_roi(a, *args, overlap=0.75, return_matches_only=False)¶

Returns the smallest rectangles that contain the ROI grouped depending on whether they overlap or not.

A ROI should be a pair (tuple) of numpy.ndarray for (lower-,upper-) bounds.

Time is handled just like any space coordinate. As a consequence, if time bounds are also specified, the corresponding values should be scaled so that time can be artificially related to space in the volume calculation carried out in the estimatation of the amount of overlap.

tramway.analyzer.roi.utils.distance_to_roi_center(roi_obj, sampling)¶

Parameters:	roi_obj (IndividualROI) – ROI object sampling (Partition or Analysis) – tessellation
Returns:	distance between each cell center and the ROI center
Return type:	ndarray

tramway.analyzer.tesseller package¶

class tramway.analyzer.tesseller.TessellerInitializer(attribute_setter, parent=None)¶

Bases: tramway.analyzer.attribute.Initializer

Initializer class for the RWAnalyzer tesseller main attribute.

The tesseller attribute self-modifies on calling any of the from_… methods.

The easiest way to define a tesseller is to set the tesseller attribute with any of the tesseller classes provided by the tessellers module:

from tramway.analyzer import *

a = RWAnalyzer()
a.tesseller = tessellers.KMeans

Note that tessellers is made available by importing tramway.analyzer.

from_callable(cls)¶

Argument:

cls (callable):

no-argument callable object (usually a class) that returns a Tesseller object.

mpl¶

Matplotlib utilities

Type:	tramway.analyzer.tesseller.mpl.Mpl

class tramway.analyzer.tesseller.Tesseller¶

Bases: tramway.analyzer.attribute.abc.Attribute

Abstract base class for the tesseller attribute of an RWAnalyzer object.

resolution¶

Desired spatial resolution in $\mu m$

Type:	float

class tramway.analyzer.tesseller.TessellerProxy(cls, **kwargs)¶

Bases: tramway.analyzer.attribute.AnalyzerNode

Encapsulates a tessellation plugin as defined in the tramway.tessellation package.

Attributes are managed with the following rules:

if an attribute is set using a proxy property, the value is flagged as 'explicit' and overrides any default value;
the arguments in _init_kwargs are passed to the wrapped tesseller’s __init__(); these arguments are intended to prevent __init__() from crashing if the later requires some arguments to be defined; non-explicit values are likely to be overriden and both explicit and non-explicit values may be altered by __init__();
the arguments in _tessellate_kwargs are passed to the wrapped tesseller’s tessellate() method; all available arguments should be defined in the proxy’s __init__(), with default values;
the wrapped tesseller’s attributes can be accessed using proxy properties; as a consequence, any key in _explicit_kwargs, that is not in _init_kwargs or _tessellate_kwargs, is considered as an actual attribute;
an argument should not be defined both in _init_kwargs and _tessellate_kwargs;
explicit __init__() arguments take precedence over standard attributes;

reset(clear_explicit_attrs=False)¶: resets the tesseller to let the calibration parameters vary.

helper_cls¶

Tessellation helper class, inheriting from tramway.helper.tessellation.Tessellate

Type:	type

tessellate(spt_dataframe)¶: Grows and returns the tessellation.

mpl¶

Matplotlib utilities

Type:	tramway.analyzer.tesseller.mpl.Mpl

class tramway.analyzer.tesseller.TessellerPlugin(name, **kwargs)¶

Bases: tramway.analyzer.tesseller.proxy.TessellerProxy

Wraps any plugin referenced in tramway.tessellation.plugins.

class tramway.analyzer.tesseller.TessellationPostProcessing¶

Bases: tramway.analyzer.attribute.abc.Attribute

Abstract base class for the post attribute of a Tesseller object.

tramway.analyzer.tesseller.proxy module¶

class tramway.analyzer.tesseller.proxy.TessellerProxy(cls, **kwargs)¶

Bases: tramway.analyzer.attribute.AnalyzerNode

Encapsulates a tessellation plugin as defined in the tramway.tessellation package.

Attributes are managed with the following rules:

if an attribute is set using a proxy property, the value is flagged as 'explicit' and overrides any default value;
the arguments in _init_kwargs are passed to the wrapped tesseller’s __init__(); these arguments are intended to prevent __init__() from crashing if the later requires some arguments to be defined; non-explicit values are likely to be overriden and both explicit and non-explicit values may be altered by __init__();
the arguments in _tessellate_kwargs are passed to the wrapped tesseller’s tessellate() method; all available arguments should be defined in the proxy’s __init__(), with default values;
the wrapped tesseller’s attributes can be accessed using proxy properties; as a consequence, any key in _explicit_kwargs, that is not in _init_kwargs or _tessellate_kwargs, is considered as an actual attribute;
an argument should not be defined both in _init_kwargs and _tessellate_kwargs;
explicit __init__() arguments take precedence over standard attributes;

helper_cls¶

Tessellation helper class, inheriting from tramway.helper.tessellation.Tessellate

Type:	type

mpl¶

Matplotlib utilities

Type:	tramway.analyzer.tesseller.mpl.Mpl

reset(clear_explicit_attrs=False)¶: resets the tesseller to let the calibration parameters vary.

tessellate(spt_dataframe)¶: Grows and returns the tessellation.

tramway.analyzer.tesseller.proxy.proxy_property(propname, level='default', doc=None)¶

Property factory function similar to builtin property, dedicated to the TessellerProxy class.

For 'tessellate' level properties, the default level is safe.

For '__init__' level properties, the level must be specified.

For standard attributes, it is safer to make the level explicit, so that some conflicts may be detected earlier (e.g. at module loading).

class tramway.analyzer.tesseller.proxy.FreeResolutionTesseller(cls, **kwargs)¶: Bases: tramway.analyzer.tesseller.proxy.TessellerProxy

tramway.analyzer.tesseller.proxied module¶

This module is exported by the tramway.analyzer package as tessellers.

class tramway.analyzer.tesseller.proxied.Squares(**kwargs)¶

Bases: tramway.analyzer.tesseller.proxy.FreeResolutionTesseller

Wraps tramway.tessellation.grid.RegularMesh.

avg_distance¶

Average distance between adjacent square centers or, equivalently, average square size; ignored if avg_probability is defined

Type:	float

avg_probability¶

Average probability for a point to fall within any given square

Type:	float

count_per_dim¶

Number of squares per space dimension

Type:	int

lower_bound¶

Scaled lower space bounds

Type:	ndarray or Series

min_distance¶

Minimum distance between adjacent square centers or, equivalently, minimum square size; ignored if avg_distance is defined

Type:	float

upper_bound¶

Scaled upper space bounds

Type:	ndarray or Series

class tramway.analyzer.tesseller.proxied.Hexagons(**kwargs)¶

Bases: tramway.analyzer.tesseller.proxy.FreeResolutionTesseller

Wraps tramway.tessellation.hexagon.HexagonalMesh.

avg_distance¶

Average distance between adjacent hexagon centers or, equivalently, average diameter of the inscribed circle; ignored if avg_probability is defined

Type:	float

avg_probability¶

Average probability for a point to fall within any given hexagon

Type:	float

lower_bound¶

Scaled lower space bounds

Type:	ndarray or Series

min_distance¶

Minimum distance between adjacent hexagon centers or, equivalently, minimum diameter of the inscribed circle; ignored if avg_distance is defined

Type:	float

tilt¶

Angle of the “main” axis, in $\frac{\pi}{6}$ radians; 0= the main axis is the x-axis; 1= the main axis is the y-axis

Type:	float

upper_bound¶

Scaled upper space bounds

Type:	ndarray or Series

class tramway.analyzer.tesseller.proxied.KMeans(**kwargs)¶

Bases: tramway.analyzer.tesseller.proxy.FreeResolutionTesseller

Wraps tramway.tessellation.kmeans.KMeansMesh.

avg_distance¶

Average distance between adjacent cell centers; affects the 'grid' initialization only

Type:	float

avg_probability¶

Average probability for a point to fall within any given cell

Type:	float

initial¶

Any of 'grid' (default), 'random' and 'center'; 'grid' uses Squares to initialize the cell centers; 'random' randomly samples the initial cell centers; 'center' is similar to 'random' but confines the random cell centers within a tiny area in the middle

Type:	str

min_distance¶

Minimum distance between adjacent cell centers; affects the 'grid' initialization only

Type:	float

prune¶

Maximum edge length for the Voronoi graph, relative to the median edge length; if True, defaults to 2.5; the edges that exceed the derived threshold value are pruned

Type:	bool or float

tol¶

Error tolerance; passed as thresh to scipy.cluster.vq.kmeans()

Type:	float

class tramway.analyzer.tesseller.proxied.GWR(**kwargs)¶

Bases: tramway.analyzer.tesseller.proxy.TessellerProxy

Wraps tramway.tessellation.gwr.GasMesh.

alpha_risk¶

Threshold p-value in the comparison between distance distributions to determine whether the edges that are not in the Delaunay graph are still valid

Type:	float

batch_size¶

Number of points per epoch; this merely affects the node merging mechanism triggered between epochs

Type:	int

collapse_tol¶

Maximum ratio of the number of collapsed nodes over the total number of nodes

Type:	float

complete_delaunay¶

Use the Delaunay graph instead, for determining the cell adjacency; default is True

Type:	bool

error_count_tol¶

Maximum rate of errors as defined by residual_factor and the batch size; as long as the rate does not fall below this threshold value, tessellate() keeps on sampling batches

Type:	float

lifetime¶

Edge lifetime in number of iterations; taken as absolute, if greater than 1; otherwise relative to the number of nodes in the graph

Type:	float

min_growth¶

Minimum relative increase in the number of nodes

Type:	float

min_probability¶

Minimum probability for a point to fall within any given cell

Type:	float

pass_count¶

Number of points to sample (with replacement), as a multiple of the total size of the data; a pair of values denotes the lower and upper bounds on the number of points; a single value is interpreted as the lower bound, and the upper bound is then set equal to 2 * pass_count

Type:	float or (float, float)

residual_factor¶

Maximum residual for each sample point, relative to _max_distance

Type:	float

tau¶

Habituation scaling factor, in number of iterations, for the nearest and second nearest nodes respectively

Type:	float or (float, float)

tessellate(spt_dataframe)¶: Grows and returns the tessellation.

topology¶

Any of 'approximate density' and 'displacement length' (default for trajectory/translocation data)

Type:	str

trust¶

Confidence in outstanding points to become new nodes; the new node is set as $\frac{(1-\rm{trust})*w + (1+\rm{trust})*\eta}{2}$; the original GWR algorithm corresponds to trust = 0

Type:	float

verbose¶

Verbose mode; default is False

Type:	bool

tramway.analyzer.tesseller.plugin module¶

class tramway.analyzer.tesseller.plugin.TessellerPlugin(name, **kwargs)¶

Bases: tramway.analyzer.tesseller.proxy.TessellerProxy

Wraps any plugin referenced in tramway.tessellation.plugins.

tramway.analyzer.tesseller.plugin.tesseller_plugin(name)¶: Translate plugin names into RWAnalyzer-ready tessellers as defined in the tessellers module, if available, else returns a generic TessellerPlugin initializer.

tramway.analyzer.tesseller.post package¶

class tramway.analyzer.tesseller.post.TessellationPostProcessingInitializer(attribute_setter, parent=None)¶

Bases: tramway.analyzer.attribute.Initializer

Initializer class for attribute tesseller post.

For now, a single use case is available:

a = RWAnalyzer()
# initialize attribute `tesseller`
a.tesseller = tessellers.KMeans
# .. so that attribute `post` is exposed
a.tesseller.post = cell_mergers.ByTranslocationCount
# .. and now `tesseller.post` is initialized
a.tesseller.post.count_threshold = 20

Note that cell_mergers is exported by the tramway.analyzer module, just like tessellers.

tramway.analyzer.tesseller.post.merger module¶

This module is exported by the tramway.analyzer package as cell_mergers.

class tramway.analyzer.tesseller.post.merger.ByTranslocationCount(**kwargs)¶

Bases: tramway.analyzer.tesseller.post.merger.CellMerger

Merges the cells/microdomains that exhibit a number of translocations below some threshold.

Note

For now, all locations are counted instead of translocations only.

tramway.analyzer.tesseller.mpl module¶

class tramway.analyzer.tesseller.mpl.Mpl(parent=None)¶

Bases: tramway.analyzer.attribute.AnalyzerNode

Matplotlib plotting utilities for 2D data; no time support.

animate(fig, sampling, axes=None, voronoi_options={}, location_options={}, **kwargs)¶

As this method is of limited interest, it has been poorly tested.

The RWAnalyzer.time attribute is accessed.

plot(tessellation, locations=None, axes=None, voronoi_options={}, delaunay_options=None, location_options={}, **kwargs)¶

Plot the particle locations and the Voronoi graph (or tessellation).

plot does not access any RWAnalyzer attribute and can be safely called with no side effect.

plot_cell_indices(tessellation, axes=None, voronoi_options={}, delaunay_options=None, aspect='equal', title=None, **kwargs)¶

Plot the Voronoi graph and Voronoi cell indices.

The placement of the text elements is not optimized.

tramway.analyzer.time package¶

class tramway.analyzer.time.DT¶

Bases: object

Implements the default behavior of methods common to the initializer and the specialized attributes.

It gives access to the frame interval (the dt and time_step attributes are aliases of frame_interval), and features the as_time_segments() slicer.

The default implementation suits the initializer’s behavior, i.e. a single all-in time segment.

enable_regularization()¶: This method is called before running the inference plugins that define time_prior parameters.

n_time_segments(sampling)¶: Returns the number of time segments (int) that sampling includes, under the hypothesis that sampling was generated following this segments definition (self).

as_time_segments(sampling, maps=None, index=None, return_index=False, return_times=True)¶

Generator function; yields single-segment sampling and map objects.

Slices sampling and maps and yields tuples with elements in the following order:

segment index (int), if return_index is True,
segment start and stop times (float, float), if return_times is True (default),
segment Partition object, from sampling,
segment maps (pandas.DataFrame) from maps, if maps is defined.

index is a selector on the segment index, either as an int, a set of int, a sequence of int, or a callable that takes a segment index (int) as input argument and returns a bool.

dt¶

See dt

Type:	float

time_step¶

See time_step

Type:	float

frame_interval¶

See frame_interval

Type:	float

get_spatial_segmentation(sampling, segment=None)¶: Returns the spatial tessellation.

class tramway.analyzer.time.TimeInitializer(*args, **kwargs)¶

Bases: tramway.analyzer.attribute.Initializer, tramway.analyzer.time.DT

Initializer Time class for the RWAnalyzer time main attribute.

The time attribute self-modifies on calling from_… methods.

from_sliding_window(duration=None, shift=None)¶

Defines a sliding time window.

Parameters:	duration (float) – window duration in seconds shift (float) – time shift between successive segments, in seconds; by default, equals to duration

tramway.analyzer.sampler package¶

class tramway.analyzer.sampler.BaseSampler(**kwargs)¶

Bases: tramway.analyzer.attribute.AnalyzerNode

wraps the Partition.cell_index logics that readily implements all the possibilities mentioned in this module.

min_location_count¶

Minimum number of assigned (trans-)locations, as given by the default Voronoi sampling; any microdomain with too few assigned (trans-)locations are marked as disabled and are excluded from further analyses

Type:	int

class tramway.analyzer.sampler.VoronoiSampler(**kwargs)¶

Bases: tramway.analyzer.sampler.BaseSampler

nearest neighbor assignment.

Each data point is assigned to exactly one cell/microdomain.

class tramway.analyzer.sampler.SamplerInitializer(attribute_setter, parent=None)¶

Bases: tramway.analyzer.attribute.Initializer

Initializer class for the RWAnalyzer sampler main attribute.

The sampler attribute self-modifies on calling any of the from_… methods.

The default not-initialized sampler attribute behaves like:

a = RWAnalyzer()
a.sampler.from_voronoi()

from_voronoi()¶

default sampler.

The data points are assigned to the nearest cell/microdomain.

tramway.analyzer.mapper package¶

class tramway.analyzer.mapper.MapperInitializer(attribute_setter, parent=None)¶

Bases: tramway.analyzer.attribute.Initializer, tramway.analyzer.mapper.plugin.MapperAttribute

from_maps(label_or_maps=None, exclude_attrs=(), verbose=False)¶

Sets the mapper up on basis of parameters in a Maps object.

If a label is passed instead of a Maps object (or nothing), the corresponding artefact is sought for in the analysis tree, starting from the first branch (first sampling) in the first tree.

This method has been designed for the stochastic.dv plugin. Application to other plugins has not been tested.

Parameters:	label_or_maps (Maps or Analysis or int or str or tuple or list) – maps object or label(s) of the maps artefact to be found in any registered analysis tree exclude_attrs (iterable) – attributes of the maps object to be ignored verbose (bool) – prints the plugin name and loaded attributes

class tramway.analyzer.mapper.Mapper¶

Bases: tramway.analyzer.attribute.abc.Attribute

Abstract base class for the mapper attribute of an RWAnalyzer object.

class tramway.analyzer.mapper.MapperPlugin(plugin, **kwargs)¶: Bases: tramway.analyzer.attribute.AnalyzerNode, tramway.analyzer.mapper.plugin.MapperAttribute

tramway.analyzer.mapper.utils module¶

tramway.analyzer.mapper.mpl module¶

class tramway.analyzer.mapper.mpl.PatchCollection(ax, mesh, bounding_box=None, overlay_locations=False, time_label_fmt='t= %t-%ts', time_label_loc=(0.01, 1.01), **kwargs)¶

Bases: object

Makes glyphs for space bins to be drawn as patches.

For constant spatial mesh and 2D localization data only.

Vector maps are not supported yet.

animate(map)¶

To be passed as second positional argument to FuncAnimation.

Parameters:	map (Series) – parameter values; can also be a tuple with the actual map argument being last.
Returns:	list of glyphs to update.
Return type:	callable

init_func()¶: To be passed as argument init_func to FuncAnimation.

plot(map, times=None, locations=None)¶

Updates the color of the patches.

Parameters:	map (Series) – parameter values. times (tuple) – time segment bounds, in seconds. locations (DataFrame) – segment locations.
Returns:	sequence of updated glyphs.
Return type:	tuple

class tramway.analyzer.mapper.mpl.Mpl(parent=None)¶

Bases: tramway.analyzer.attribute.AnalyzerNode

Matplotlib interface for maps.

animate(fig, maps, feature, sampling=None, overlay_locations=False, axes=None, aspect='equal', logscale=False, composable=True, **kwargs)¶

Animates the time-segmented inference parameters.

Vector features are represented as amplitude.

The RWAnalyzer.time attribute is accessed.

Parameters:	fig (matplotlib.figure.Figure) – figure. maps (Analysis or Maps) – map series. feature (str) – parameter to be drawn. sampling (Analysis or Partition) – spatial bins and time segments; optional only if maps is an `Analysis`. overlay_locations (bool or dict) – styling options for the overlaid locations. axes (matplotlib.axes.Axes) – figure axes. aspect (str or None) – aspect ratio. logscale (bool or str) – transform the color-coded values in natural logarithm; can also be ‘log’, ‘natural’ or ‘log10’. composable (bool) – returns an overloaded `FuncAnimation` object that can be passed in place of argument fig in later calls to `animate()` so to stack animations on different axes (axes) of a same figure (fig).
Returns:	animation object.
Return type:	matplotlib.animation.FuncAnimation

Extra input arguments are passed to FuncAnimation or PatchCollection (and scalar_map_2d()).

Notebook example:

Note: the above example seems to work equally well without composable=True.

clabel(feature, kwargs, logscale=None, map_kwargs=None)¶: Extracts from kwargs arguments related to the colorbar label and adds a 'unit' or clabel argument to map_kwargs if necessary.

plot(maps, feature, sampling=None, axes=None, aspect='equal', interior_contour=None, overlay_locations=False, logscale=None, **kwargs)¶

Calls map_plot().

May be reworked in the future to remove the helper dependency.

logscale applies only to the color-coded background of field maps.

new in 0.5.2: argument interior_contour is a :class`dict` with the following keys allowed: margin, linestyle, linewidth and color. The default value for margin (or relative_margin) is 0.01.

plot does not access any analyzer attributes and can be safely called from any analyzer:

from tramway.analyzer import RWAnalyzer

RWAnalyzer().mapper.mpl.plot(…)

or instanciating an Mpl object:

from tramway.analyzer.mapper.mpl import Mpl

Mpl().plot(…)

tramway.analyzer.pipeline package¶

class tramway.analyzer.pipeline.Pipeline(*args, **kwargs)¶

Bases: tramway.analyzer.attribute.AnalyzerNode

pipeline attribute of an RWAnalyzer object.

The main methods are append_stage() and run().

add_collectible(filepath)¶: Registers a file as to be collected after stage completion.

append_stage(stage, granularity=None, requires_mutability=None, **options)¶

Appends a pipeline stage to the processing chain.

Parameters:

stage (callable) – function that takes an RWAnalyzer object as unique input argument.
granularity (str) – smallest data item stage can independently process; any of 'coarsest' or equivalently 'full dataset', 'source' or equivalently 'spt data', 'data source' or 'spt data source', 'roi' or equivalently 'region of interest', 'time' or equivalently 'segment' or 'time segment' (case-insensitive). new in 0.6.2: granularity can be prefixed with min:
requires_mutability (bool) – callable object stage alters input argument self. Stages with this argument set to True are always run as dependencies. Default is False.
update_existing_rwa_files (bool) – see also PipelineStage.
run_everywhere (bool) – new in 0.6.2; see also PipelineStage.

new in 0.6.2: the min: prefix for granularity can be passed to prevent flexible-level stages to be combined with others of incompatible granularity. For example, a fresh_start stage should operate no below source, because it may delete source-level files, which is not compatible with a roi-level stage that may be split into multiple jobs working on the same source file. Note however that passing run_everywhere=True to a fresh_start stage is preferred as this is more portable.

early_setup(**kwargs)¶

Sets the submit_side/worker_side properties of the env attribute.

early_setup() can be called once env is initialized and before run() is called. This allows to run some conditional code, specifically on the submit side or on the worker side.

This method returns silently if env is not initialized and both the env.EnvironmentInitializer.submit_side and env.EnvironmentInitializer.worker_side properties are False.

reset()¶: Empties the pipeline processing chain.

resume(**kwargs)¶

Looks for orphaned remote jobs and collect the generated files.

Works as a replacement for the run() method to recover after connection loss.

Recovery procedures featured by the env backend may fail or recover some of the generated files only.

See also the resume() method of the env attribute, if available.

run()¶: Sequentially runs the different stages of the pipeline.

class tramway.analyzer.pipeline.PipelineStage(run, granularity=None, requires_mutability=None, update_existing_rwa_files=None, run_everywhere=None, **options)¶

Bases: object

Wrapper for callables to be run on calling Pipeline.run().

requires_mutability defaults to False.

update_existing_rwa_files defaults to False as of version 5.2.

new in 0.6.2: boolean argument and attribute run_everywhere. The main difference with requires_mutability is that the run_everywhere stage runs at most once on each host.

A fresh_start stage will typically set run_everywhere to True, while a reload stage will set requires_mutability to True instead.

granularity¶

See Pipeline.append_stage()

Type:	str

name¶

Callable’s name

Type:	str

requires_mutability¶

See Pipeline.append_stage()

Type:	bool

run_everywhere¶

Run once on every host, both local and remote

Type:	bool

tramway.analyzer.pipeline.stages module¶

This module is exported by the tramway.analyzer package.

Standard analysis steps for RWAnalyzer.pipeline

tramway.analyzer.pipeline.stages.tessellate(label=None, roi_expected=False, spt_data=True, tessellation='freeze', **kwargs)¶

Returns a standard pipeline stage for SPT data sampling.

Although the name ‘tessellate’ refers merely to the spatial segmentation, time segmentation is also handled, if defined. The name alludes to the standalone tramway.helper.tessellation.tessellate() function.

The default granulariy is set to ‘spt data’, whereas in principle the finest valid granularity is ‘roi’. The tessellation step is fast enough to a avoid the overhead of saving as many files as regions of interest.

Important

If the input SPT data is defined as ascii file(s), the corresponding .rwa files will be overwritten.

If analysis trees already reference analysis artefacts for the specified label, these artefacts are also overwritten.

This stage building function features two mechanisms to make the resulting .rwa files smaller in size:

with option spt_data=’placeholder’, the SPT data can be omitted in the .rwa files; see also restore_spt_data();
the spatial tessellation can be freezed (default); this implies the tesellation cannot be updated any longer with extra data.

tramway.analyzer.pipeline.stages.infer(map_label=None, sampling_label=None, roi_expected=False, overwrite=False, single_path=False, **kwargs)¶

Returns a standard pipeline stage for inferring model parameters on each region of interest, or SPT data item if no roi are defined.

The default granularity is set to ‘roi’, which is suitable for computer-intensive inferences such as ‘DV’.

With default overwrite=False, if the specified output label map_label already exists in analysis trees, the inference is skipped for these analysis trees and the corresponding artefact not overwritten. However, if map_label is None, overwrite is ignored and the stage acts like if overwrite were True.

tramway.analyzer.pipeline.stages.reload(skip_missing=True)¶

Returns a pipeline stage to reload the generated .rwa files.

This is useful if a first computation - e.g. tessellate - was dispatched (including with the environments.LocalHost environment) and the .rwa files were generated and retrieved from the worker environments. In the case a second stage has to be dispatched - e.g. infer, the local pipeline must be updated with the content of these retrieved files.

This may also be required on the worker side for the next stages, for example if the SPT data was initially defined from ascii files and the coming stages should take over from the corresponding .rwa files. As a consequence, this reload stage is set with requires_mutability=True.

tramway.analyzer.pipeline.stages.restore_spt_data()¶

Reintroduces the original SPT dataframe into the .rwa files.

This post-processing stage - typically post-infer stage - is expected to be called only when the tessellate stage was called before with option spt_data=’placeholder’.

This stage was tested with SPT data defined as SPTAsciiFiles or spt_data.RWAFiles. However, with SPTAsciiFiles, the alias attribute should be defined.

tramway.analyzer.pipeline.stages.tessellate_and_infer(map_label=None, sampling_label=None, spt_data=True, overwrite=False, roi_expected=False, load_rwa_files=None, **kwargs)¶

Combines tessellate and infer at roi granularity.

See infer() for important notes on overwrite argument.

new in 0.6: unless load_rwa_files=False, .rwa files are loaded if the SPT data source has not already been loaded from such files.

tramway.analyzer.env package¶

class tramway.analyzer.env.EnvironmentInitializer(attribute_setter, parent=None)¶

Bases: tramway.analyzer.attribute.Initializer

Can be left not-initialized.

For local multi-processing:

a.env = environments.LocalHost

For sbatch job scheduling on an SSH-reachable server:

a.env = environments.SlurmOverSSH

See LocalHost and SlurmOverSSH.

script¶

Path to the local script; this compatibility attribute is actually used by the browser

Type:	str

collectibles¶

Compatilibity attribute; not used

Type:	set

class tramway.analyzer.env.Environment¶

Bases: tramway.analyzer.attribute.abc.Attribute

Abstract base class for the env attribute of an RWAnalyzer object.

script¶

Path to the local script; usually a filename

Type:	str

dispatch(**kwargs)¶

Input arguments must be keyworded.

Parameters:	stage_index (int) – index of the pipeline stage which material has to be dispatched. source (str) – source name of the spt dataset to be dispatched.

tramway.analyzer.env.environments module¶

This module is exported by the tramway.analyzer package as environments.

class tramway.analyzer.env.environments.Environment¶

Bases: tramway.analyzer.attribute.abc.Attribute

Abstract base class for the env attribute of an RWAnalyzer object.

dispatch(**kwargs)¶

Input arguments must be keyworded.

Parameters:	stage_index (int) – index of the pipeline stage which material has to be dispatched. source (str) – source name of the spt dataset to be dispatched.

script¶

Path to the local script; usually a filename

Type:	str

class tramway.analyzer.env.environments.LocalHost(**kwargs)¶

Bases: tramway.analyzer.env.environments.Env

Runs jobs in local python processes.

Because of a design limitation in tramway.analyzer.pipeline (type check), Every class that similarly implements local-only parallel processing should ideally be derived from this class. This may not be critical, as failure to do so will only make run_everywhere stages to run twice instead of once.

interrupt_jobs()¶: Interrupts the running jobs.

worker_count¶

Desired number of workers

Type:	int

class tramway.analyzer.env.environments.SlurmOverSSH(**kwargs)¶

Bases: tramway.analyzer.env.environments.Slurm, tramway.analyzer.env.environments.RemoteHost

Calls sbatch through an SSH connection to a Slurm server.

Note

All filepaths should be absolute or relative to the $HOME directory. This applies especially to all file-based initializers.

collect_results(stage_index=None, inplace=False, reload_existing_rwa_files=False)¶

Downloads the reported collectibles from the remote host (worker side) to the local host (submit side).

See Env.collect_results() for information on the distinct behavior of the inplace=True case.

delete_temporary_data()¶: Deletes all the temporary data, on both the submit and worker sides.

dispatch(**kwargs)¶: Prepares the worker side. To be called from the submit side only.

early_setup(*argv, connect=False, **kwargs)¶

Determines which side is running and sets the submit_side/worker_side attributes.

Takes command-line arguments (sys.argv).

filter_script_content(content)¶

Processes the script content for its dispatch onto the worker side.

Parameters:	content (list of str) – lines with the `'n'` character at the end of each line
Returns:	modified lines
Return type:	list of str

make_job(stage_index=None, source=None, region_index=None, segment_index=None)¶

Registers a new pending job.

Parameters:	stage_index (int or list of int) – stage index(ices) source (str) – SPT datablock identifier (source path or alias) region_index (int) – index of the support region (see also `as_support_regions()`) segment_index (int) – index of the time segment

pack_temporary_rwa_files(log=None, wd=None, stage_index=None, job_id=None)¶

Similarly to resume(), pack_temporary_rwa_files combines the intermediate .rwa files in the temporary directory for a running instance on the compute host.

This does not move files out of the temporary directory. Instead, the intermediate .rwa files are replaced by new (but fewer) intermediate .rwa files that result from combining the former files.

This may be useful to save disk space, as the localization data is duplicated as many times as there are intermediate files.

Warning

not tested yet

resume(log=None, wd=None, stage_index=None, job_id=None)¶

Parses log output of the disconnected instance, looks for the current stage index, and tries to collect the resulting files.

This completes the current stage only. Further stages are not run.

Parameters:	log (str) – log output; progress information can be omitted wd (str) – location of the working directory on the remote host stage_index (int or list) – index of the stage(s) to resume job_id (str) – Slurm job array ID

setup(*argv, connect=True, **kwargs)¶

Determines which side is running and alters iterators of the main RWAnalyzer attributes.

Takes command-line arguments (sys.argv).

class tramway.analyzer.env.environments.Tars(**kwargs)¶

Bases: tramway.analyzer.env.environments.SingularitySlurm

Designed for server tars.pasteur.fr.

The server is closed.

class tramway.analyzer.env.environments.GPULab(**kwargs)¶

Bases: tramway.analyzer.env.environments.SingularitySlurm

Designed for server adm.inception.hubbioit.pasteur.fr.

class tramway.analyzer.env.environments.Maestro(**kwargs)¶

Bases: tramway.analyzer.env.environments.SingularitySlurm

Designed for server maestro.pasteur.fr.

tramway.analyzer.browser package¶

class tramway.analyzer.browser.Browser(analyzer)¶

Bases: tramway.analyzer.attribute.AnalyzerNode

browser attribute of an RWAnalyzer object.

Rendering is based on bokeh and is performed in a web browser tab. An optional side panel with experimental export features is shown if argument side_panel=True is passed to show_maps() or argument webdriver is defined:

from tramway.analyzer import *

a = RWAnalyzer()

a.spt_data.from_rwa_files('*.rwa')

from selenium import webdriver

a.browser.show_maps(webdriver=webdriver.Firefox)

Defining a webdriver is required for exporting figures. Supported file formats are .png and .svg. Note that package selenium is required.

The above example can be explicitly run with bokeh serve, or else it can be run with the standard Python interpreter or in a Jupyter notebook as long as the script attribute is defined:

from tramway.analyzer import *

a = RWAnalyzer()

a.spt_data.from_rwa_files('*.rwa')

try:
    a.script = __file__
except NameError: # in a notebook
    a.script = 'MyNotebook.ipynb' # this notebook's name; please adapt

from selenium import webdriver

a.browser.show_maps(webdriver=webdriver.Firefox)

The later example will call bokeh serve --show on the file specified in the script attribute.

The showed parameter values can also be exported with the side panel. Note that all features are exported together with the spatial bin center coordinates.

clim¶

Color lower and upper values (dict values) for each feature (dict keys)

Type:	dict of 2-element array-like

colormap¶

Colormap for inferred parameter maps.