Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
MDAnalysis.analysis user interface
All analysis tools should have a common philosophy and share a common set of options, as discussed in Issue #719. It makes for a better overall user experience if users are able to use different analysis tools "out of the box" once they have a basic understanding of how analysis works in MDAnalysis.
From the developer side, it promotes code re-use and modularization with subsequent improvements in testing coverage and code reliability.
Analysis classes in MDAnalysis.analysis are supposed to follow the "Bauhaus model":
- Use MDAnalysis.analysis.base.AnalysisBase as base class.
__init__has to accept a
Atomgroupobject to define on which atoms the analysis should be done
- follow example in the MDAnalysis.analysis.base.AnalysisBase docs for starting a new analysis.
_single_frame()must be defined. It is called after the trajectory is moved to a new frame. It computes a quantity from a single trajectory frame.
_prepare()may be defined. It is called before iteration on the trajectory has begun. It should be used to set up data structures or values that are used in
_conclude()may be defined. It is called after iteration through the trajectory is complete. It should be used to perform data reduction (e.g., normalisation and averaging of results).
- It is not prescribed how the results of the computation are stored but they must be made available as one or more attributes of the instance for further processing by the user. These can be either one or more simple attributes with an expressive names (e.g.,
RMSD.rmsdfor the RMSD timeseries or see
pca.PCA) or a dictionary
resultswith multiple keys.
- There should be a separate function outside the analysis class that takes as input the minimal data structures needed (e.g., just coordinate arrays), performs the core numerical analysis, and returns calculated data as numpy array or other simple data structure. This function should be used inside
_single_frame(). Making this function available outside the class allows users to write their own analysis code, e.g., using parallel approaches.
plot()function is optional. If it is present then it must
- A method to save results is optional but if present, it must be named
save(). This method should only be used if you have to write custom data formats like xvg to allow the data to be handled by other tools. It should not be used to write a simple numpy array. For a numpy array the user should choose his own preferred method