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