1.. Contains the formatted docstrings for the transformations located in 'mdanalysis/MDAnalysis/transformations' 2.. _transformations: 3 4************************** 5Trajectory transformations 6************************** 7 8.. module:: MDAnalysis.transformations 9 10The transformations submodule :mod:`MDAnalysis.transformations` contains a 11collection of functions to modify the trajectory. Coordinate transformations, 12such as PBC corrections and molecule fitting are often required for some 13analyses and visualization, and the functions in this module allow 14transformations to be applied on-the-fly. These transformation functions 15(``transformation_1`` and ``transformation_2`` in the following example) can be 16called by the user for any given :class:`Timestep` of the trajectory, 17 18.. code-block:: python 19 20 u = MDAnalysis.Universe(topology, trajectory) 21 22 for ts in u.trajectory: 23 ts = transformation_2(transformation_1(ts)) 24 25where they change the coordinates of the timestep ``ts`` in place. However, it 26is much more convenient to associate a whole workflow of transformations with a 27trajectory and have the transformations be called automatically. One can add a 28workflow (a sequence of transformations) using the 29:meth:`Universe.trajectory.add_transformations 30<MDAnalysis.coordinates.base.ReaderBase.add_transformations>` method of a 31trajectory, 32 33.. code-block:: python 34 35 workflow = [transformation_1, transformation_2] 36 u.trajectory.add_transformations(*workflow) 37 38or upon :class:`Universe <MDAnalysis.core.universe.Universe>` 39creation using the keyword argument `transformations`: 40 41.. code-block:: python 42 43 u = MDAnalysis.Universe(topology, trajectory, transformations=workflow) 44 45Note that in the two latter cases, the workflow cannot be changed after having 46being added. 47 48A simple transformation that takes no other arguments but a :class:`Timestep` can be defined 49as the following example: 50 51.. code-block:: python 52 53 def up_by_2(ts): 54 """ 55 Translate all coordinates by 2 angstroms up along the Z dimension. 56 """ 57 ts.positions = ts.positions + np.array([0, 0, 2], dtype=np.float32) 58 return ts 59 60 61If the transformation requires other arguments besides the :class:`Timestep`, the transformation 62takes these arguments, while a wrapped function takes the :class:`Timestep` object as 63argument. 64So, a transformation can be roughly defined as follows: 65 66.. code-block:: python 67 68 def up_by_x(distance): 69 """ 70 Creates a transformation that will translate all coordinates by a given amount along the Z dimension. 71 """ 72 def wrapped(ts): 73 ts.positions = ts.positions + np.array([0, 0, distance], dtype=np.float32) 74 return ts 75 return wrapped 76 77 78An alternative to using a wrapped function is using partials from :mod:`functools`. The 79above function can be written as: 80 81.. code-block:: python 82 83 import functools 84 85 def up_by_x(ts, distance): 86 ts.positions = ts.positions + np.array([0, 0, distance], dtype=np.float32) 87 return ts 88 89 up_by_2 = functools.partial(up_by_x, distance=2) 90 91 92See :func:`MDAnalysis.transformations.translate` for a simple example. 93 94 95.. rubric:: Examples 96 97Translating the coordinates of a frame: 98 99.. code-block:: python 100 101 u = MDAnalysis.Universe(topology, trajectory) 102 new_ts = MDAnalysis.transformations.translate([1,1,1])(u.trajectory.ts) 103 104e.g. create a workflow and adding it to the trajectory: 105 106.. code-block:: python 107 108 u = MDAnalysis.Universe(topology, trajectory) 109 workflow = [MDAnalysis.transformations.translate([1,1,1]), 110 MDAnalysis.transformations.translate([1,2,3])] 111 u.trajectory.add_transformations(*workflow) 112 113e.g. giving a workflow as a keyword argument when defining the universe: 114 115.. code-block:: python 116 117 workflow = [MDAnalysis.transformations.translate([1,1,1]), 118 MDAnalysis.transformations.translate([1,2,3])] 119 u = MDAnalysis.Universe(topology, trajectory, transformations=workflow) 120 121 122.. rubric:: Currently implemented transformations 123 124.. toctree:: 125 126 ./transformations/translate 127 ./transformations/rotate 128