User Guide for MDAnalysis
Home Page: https://userguide.mdanalysis.org
MDAnalysis is a Python toolkit to analyse molecular dynamics files and trajectories in many popular formats. MDAnalysis can write most of these formats, too, together with atom selections for use in visualisation tools or other analysis programs. It provides a fast framework for complex analysis tasks, as well as flexible tooling to construct your own analyses.
This repository contains the user guide for MDAnalysis. The user guide originated as a project for Google Season of Docs 2019-2020 .
Is your feature request related to a problem? Please describe.
A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
Un/wrapping is probably the most commonly desired transformation, this would help
Describe the solution you'd like
A clear and concise description of what you want to see in the user guide. e.g. a new page of information? A short Jupyter notebook example? An extended tutorial?
Describe alternatives you've considered
A clear and concise description of any alternative solutions or features you've considered.
Additional context
Add any other context or screenshots about the feature request here.
Story: As a user, I want to concatenate selections of trajectories, so that I can use principal component analysis to compare them in a lower dimensional space. [Notebook example]
Story: As a user, I want to build my own Universe from scratch, so that I can generate random molecules as test cases. [Notebook example]
Acceptance criteria:
Story: As a user, I want to write out select representative frames to a PDB file, so that I can mimic an ensemble of NMR structures.
Story: As a GROMACS user, I want to define groups in a GROMACS index file, so that I can use them in further GROMACS analysis.
Acceptance criteria:
The authors of the user guide are hardcoded as Lily Wang, Richard J Gowers, Oliver Beckstein somewhere but @RMeli has now contributed and hopefully others will. I think the MDAnalysis docs sort contributors in alphabetical order but stick @nmichaud first and @orbeckst last -- should there be a similar scheme for the user guide?
Add travis CI to automatically build the user guide.
See MDAnalysisTutorial/.travis.yml.
.travis.ymlThe user guide should then show up as https://www.mdanalysis.org/UserGuide.
The analysis notebooks should link to the classes that they're documenting, and there should be clear links to the API docs in the user guide (maybe in the sidebar?) People are already having issues finding it.
Story: As a molecular dynamics scientist who is familiar with packages such as mdtraj and cpptraj, I want to quickly get information such as atom properties and coordinates, so that I can analyse my data.
Acceptance criteria:
Topology, Trajectory, AtomGroup, and Universe.guess_bonds, all_coordinates, in_memory.Story: As a user, I want to know how whether the analysis I have in mind is already implemented, how to use it, and how to possibly implement it myself, so that I can make contributions to science.
Acceptance criteria:
Actual Behavior
According to User guide if we install MDA using conda environment and say I try to install some dependency using pip without installing it in my conda environment and it might be possible to have pip installed outside a conda environment which causes these module to install in global env.
Expected Behavior
using pip these packages must install in conda environment.
Solution
# if using pip
pip install cython numpy mmtf-python mock six biopython \
networkx cython matplotlib scipy griddataformats \
hypothesis gsd codecov "seaborn>=0.7.0,<=0.9" \
netcdf4 scikit-learn "joblib>=0.12" parmed psutil pytestadd a note at top of this like:
if using pip make sure you have pip installed in your conda environment
Is your feature request related to a problem? Please describe.
The examples in the cookbook are useful but likely out of date.
Describe the solution you'd like
Add Jupyter tutorials with modern code.
Is your feature request related to a problem? Please describe.
Implement parallel analysis in MDAnalysis.
Describe the solution you'd like
a new page of information and tutorials.
Related PR
Is your feature request related to a problem? Please describe.
The user guide uses a number of scripts to make tables, page stubs, and so on. Should these be put in conf.py to get run every time the docs are built, or should they be manually run? If they are automatically executed, how does that work with widgets that require visualisation in the browser first?
Describe the solution you'd like
1. Automatic execution
conf.py and add comments explaining what's going onsphinx-autobuild or it will refresh to infinityor
2. Manual execution
generate_all.shIs your feature request related to a problem? Please describe.
The lib module is important and should be documented.
Describe the solution you'd like
Pages on the lib code, probably in the "Advanced" section.
Is your feature request related to a problem? Please describe.
Describe the solution you'd like
As discussed in issue MDAnalysis/mdanalysis#2905, when accessing AtomGroup atoms created by selection record_type ATOM for a PDB containing both ATOMs and HETATMs, looping through atoms.segments.resnames will return all residues in chains (including HETATM record types, the ones we didn't want).
Similarly, when using another selection, record_type ATOM and not (name H* or name OXT), if one wants to access atoms grouped by residues, the first guess could be to use atoms.residues.names. Surprisingly, this contains hydrogen atoms (H*), whereas atoms.names doesn't, but it isn't grouped by residue.
@lilyminium and @orbeckst explained the logic behind data views.
I'd like to add two examples above to groups_of_atoms.html showing the logic how to correctly access the data in the presented two use cases (getting residues and getting atoms from selected AtomGroup).
I was going to poke one of the Gsoc students to write docs on their feature, but the feature won’t ship for a while. Am I right that the user guide is published instantly? And how much of a hassle would it be to have a dev/master split like we have on the main repo, with dev pushing to a different location? I think @orbeckst had thoughts along these lines too...
@lilyminium probably know something here
Describe the bug
On https://www.mdanalysis.org/UserGuide/contributing_code.html#building-mdanalysis some packages are missing for tests
To Reproduce
Steps to reproduce the behavior:
pip install -e testsuite/: note that additional packages are downloadedExpected behavior
When using conda, no additional packages are automatically installed with pip
Actual behavior
pip install -e testsuite/ tries to download
The code snippets are not syntax highlighted, eg Cell 1 in https://www.mdanalysis.org/UserGuide/quickstart#Quick-start-guide
To install the latest stable version of MDAnalysis via pip, use the following command:
pip install --upgrade MDAnalysisTo upgrade:
pip install --upgrade MDAnalysis
This is repetitive and redundant.
The intersphinx link
Line 187 in 239b2d8
Current documentation
https://www.mdanalysis.org/UserGuide/selections.html#selection-keywords
Problem
I think it would be better for the version "Note" information to be folded into the current dot point, which documents 0.20.1. The grammar could also be better, e.g.
From version 0.21.0 onwards, MDAnalysis supports the use of one wildcard * at the start, middle, or end of strings. u.select_atoms("resname *E") will select all atoms where the atom's residue name ends in E.
Is your feature request related to a problem? Please describe.
It's a bit of a chore to diff notebooks at the moment; GitHub does not have an easy way to do it and it's naturally hard to diff notebooks yourself with nbdime, when they're on different branches
Describe the solution you'd like
Taking suggestions
Describe alternatives you've considered
If we get #68 merged we can manually compare between what's up at userguide.mdanalysis.org/ and the built docs for any PR. Still suboptimal
Additional context
Add any other context or screenshots about the feature request here.
Add:
to the dependencies for installation the development environment.
Describe the bug
Both RTD and Travis segmentation fault when building the user guide here:
reading sources... [ 98%] trajectories/transformations
Segmentation fault (core dumped)
Locally it works.
To Reproduce
Steps to reproduce the behavior:
Symptoms
UserGuide/doc/source/datasets.rst:6: WARNING: Duplicate explicit target name: "mdanalysisdata".
source/examples/analysis/alignment_and_rms/README.rst:18: WARNING: toctree contains reference to nonexisting document 'examples/analysis/alignment_and_rms/aligning_trajectory_to_first_frame'
source/examples/analysis/alignment_and_rms/README.rst:7: WARNING: duplicate label alignment-and-rms, other instance in UserGuide/doc/source/examples/analysis/alignment_and_rms/README.rst
source/examples/analysis/trajectory_similarity/README.rst:6: WARNING: duplicate label trajectory-similarity, other instance in UserGuide/doc/source/examples/analysis/trajectory_similarity/README.rst
UserGuide/doc/source/examples/analysis/alignment_and_rms/README.rst:18: WARNING: toctree contains reference to nonexisting document 'examples/analysis/alignment_and_rms/aligning_trajectory_to_first_frame'
UserGuide/doc/source/examples/analysis/alignment_and_rms/README.rst:7: WARNING: duplicate label alignment-and-rms, other instance in UserGuide/doc/source/examples/analysis/README.rst
UserGuide/doc/source/examples/analysis/trajectory_similarity/README.rst:6: WARNING: duplicate label trajectory-similarity, other instance in UserGuide/doc/source/examples/analysis/README.rst
UserGuide/doc/source/formats/coordinates.rst:4: WARNING: duplicate label coordinate-readers, other instance in UserGuide/doc/source/formats/index.rst
source/formats/coordinates.rst:4: WARNING: duplicate label coordinate-readers, other instance in UserGuide/doc/source/formats/coordinates.rst
UserGuide/doc/source/formats/reference/trj.rst:35: WARNING: Bullet list ends without a blank line; unexpected unindent.
looking for now-outdated files... none found
pickling environment... done
checking consistency... UserGuide/doc/source/examples/analysis/alignment_and_rms/aligning_trajectory_to_frame.ipynb: WARNING: document isn't included in any toctree
done
preparing documents... done
writing output... [ 10%] examples/analysis/alignment_and_rms/aligning_structure_writing output... [ 12%] examples/analysis/alignment_and_rms/aligning_trajectorywriting output... [ 13%] examples/analysis/alignment_and_rms/pairwise_rmsd writing output... [100%] universe le_similarity_similarity
UserGuide/doc/source/contributing_code.rst:7: WARNING: undefined label: https://github.com/mdanalysis/mdanalysis/pulls (if the link has no caption the label must precede a section header)
UserGuide/doc/source/contributing_code.rst:21: WARNING: undefined label: writing new code (if the link has no caption the label must precede a section header)
UserGuide/doc/source/installation.rst:96: WARNING: undefined label: mdanalysisdata (if the link has no caption the label must precede a section header)
Desktop (please complete the following information):
python -c "import MDAnalysis as mda; print(mda.__version__)")python -V)?Smartphone (please complete the following information):
Additional context
Add any other context about the problem here.
Edit: from MDAnalysis/mdanalysis#2644
Describe the bug
I think you need cython and numpy at minimum to build from source, but the installation instructions do not mention either.
To fix
Add dependencies, and possibly a link to the contributing docs.
Document icodes + empty fnmatch ([!?]) in selection strings
Story: As a prospective user, I want to install a working version of MDAnalysis to suit my needs.
Acceptance criteria:
conda and pip packagesStory: As a user, I want to compute domain angles, so that I can track conformational rearrangements of domains.
Acceptance criteria:
Describe the bug
Broken links in the quickstart guide.
Describe the bug
In the Quickstart-RMSD there area few *. Their intent is not clear to me.
To Reproduce
Steps to reproduce the behavior:
Below, the RMSD class is created. (paragraph 4)Expected behavior
I'm not entirely sure what is the intent of * here.
Actual behavior
No * or text formatted differently?
Desktop (please complete the following information):
The search box has a blue outline. Should be black or gray.
With 1.0 released MDAnalysis/mdanalysis#2443 there should also be the 1.0 version of the user guide online. At the moment it is 0.20.1.
Describe the bug
Environment.yml file needs an extra pip dependency.
Expected behavior
Calling conda create -f environment.yml python=3.6 should run fine.
Actual behavior
This gets added at the top of the output: "Warning: you have pip-installed dependencies in your environment file, but you do not list pip itself as one of your conda dependencies. Conda may not use the correct pip to install your packages, and they may end up in the wrong place. Please add an explicit pip dependency. I'm adding one for you, but still nagging you."
Desktop (please complete the following information):
python -V)? 3.7, latest conda install.Version 1.0
Add PDB to list of supported formats for the elements attribute (see PR MDAnalysis/mdanalysis#2627)
Story: As a user, I want to get hydrogens bonded to oxygens that are not water molecules, where the hydrogen within 4 A of a protein domain but not within a certain cylindrical zone.
Story: As a user, I want to get atoms from my Universe by index, so that I can compute the angle defined by the ordered atoms. [Notebook example]
Acceptance criteria:
Add
<script data-goatcounter="https://mdanalysis.goatcounter.com/count"
async src="//gc.zgo.at/count.js"></script></body> tag (better for performance) or anywhere in <head> in all generated pages.to the generated User Guide docs.
Story: As a molecular dynamics user, I want to set up MDAnalysis quickly and easily, so that I can move onto further analysis.
Story: As a molecular dynamics user, I want to convert my AMBER trajectory into a GROMACS format, so that I can use the GROMACS analysis tools on it.
Acceptance criteria:
A survey of recent mdnalysis-discussion group questions found few questions about absolute basic MDAnalysis, although there is general confusion in how to write out trajectory coordinates. This suggests that the current MDAnalysis tutorial is doing a decent job. Many of the analysis-related questions were really asking whether a particular analysis had been implemented, or how to use it, likely because the tutorial only shows RMSD and the current docs can be confusing.
A Jupyter notebook tutorial so that users can follow online or download and modify the resource. This will pull liberally from the existing MDAnalysis tutorial, as an express version without exercises.
Sections:
After MDAnalysis/mdanalysis#2436 we now support fnmatch-based wildcards (see devdocs: Selections. The User Guide's section on selections (for 1.0) should be updated.
This supersedes #37.
Is your feature request related to a problem? Please describe.
As detailed here: MDAnalysis/mdanalysis#2617 (comment) in order for the ProgressBar to work on JupyterLab, an extra install step is required.
Describe the solution you'd like
Probably somewhere in the install instructions, extra steps to get everything working on JupyterLab should be added.
Describe alternatives you've considered
Alternatively we could just not document it, however it might be easier to have at least a link to some ProgressBar/tdqm issue somewhere so that we can send users there.
[This link] (notation) doesn't work. Also, the relative links in the quick start guide should be updated.
match_atoms etc: #73weights_groupselections #75MassWeight option #124Story: As a user, I want to add bfactors to my PDB, so that I can visualise my analysis. [Notebook example]
Story: As a user, I want to populate my Universe with custom atom properties, so that I can generate desired molecules from coordinate arrays.
Acceptance criteria:
Related to #3
Is your feature request related to a problem? Please describe.
We've noted in a few places that a split between the user guide and the developer guide is necessary to
Describe the solution you'd like
A focused developer guide.
Questions
Where should this be? Part of the user guide or in its own repo? I don't immediately know how to store it in this repo but make it available at a different URL / with a different sidebar. Should it be part of the MDAnalysis main repo?
What should it contain? For example, the user guide currently has a Write your own analysis tutorial. I have targeted it at intermediate users who want to do something easy (e.g. radius of gyration) with existing building blocks. Is this for users or developers? @IAlibay has suggested a split between analysis_from_function and AnalysisBase. The entire contributing section should probably go into dev guide. Can we merge the wiki into it, which has many pages that are not immediately obvious?
ping @MDAnalysis/coredevs
Describe the bug
NGLView widgets are showing up twice in the HTML conversions from Jupyter notebooks. This happens on the Travis-deployed user guide so it's not just my local environment.
Expected behavior
It should only show up once, as there is only one widget output in the notebook.
Desktop (please complete the following information):
Additional context
The widgets aren't linked, so they're not two renderings of the same object. Not sure when this started happening, but I don't think the widgets were doubling up when I made the density analysis notebook on February 20. Normal ipywidgets are also created twice. Basic nbconvert to HTML does not result in this issue.
On mobile, the top menu bar is blue but should be black or gray.
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
Django
The Web framework for perfectionists with deadlines.
Laravel
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
Microsoft
Open source projects and samples from Microsoft.
Google
Google ❤️ Open Source for everyone.
Alibaba
Alibaba Open Source for everyone
D3
Data-Driven Documents codes.
Tencent
China tencent open source team.