{"action":"created","comment":{"url":"https://api.github.com/repos/MDAnalysis/mdanalysis/pulls/comments/216866463","pull_request_review_id":154393757,"id":216866463,"node_id":"MDI0OlB1bGxSZXF1ZXN0UmV2aWV3Q29tbWVudDIxNjg2NjQ2Mw==","diff_hunk":"@@ -367,75 +362,82 @@ def self_distance_array(reference, box=None, result=None, backend=\"serial\"):\n \n def capped_distance(reference, configuration, max_cutoff, min_cutoff=None,\n                     box=None, method=None, return_distances=True):\n-    \"\"\"Calculates the pairs and distances within a specified distance\n+    \"\"\"Calculates pairs of indices corresponding to entries in the `reference`\n+    and `configuration` arrays which are separated by a distance lying within\n+    the specified cutoff(s). Optionally, these distances can be returned as\n+    well.\n \n-    If a *box* is supplied, then a minimum image convention is used\n-    to evaluate the distances.\n+    If the optional argument `box` is supplied, the minimum image convention is\n+    applied when calculating distances. Either orthogonal or triclinic boxes are\n+    supported.\n \n-    An automatic guessing of optimized method to calculate the distances is\n+    An automatic guessing of the optimal method to calculate the distances is\n     included in the function. An optional keyword for the method is also\n-    provided. Users can override the method with this functionality.\n-    Currently pkdtree and bruteforce are implemented.\n-\n+    provided. Users can enforce a particular method with this functionality.\n+    Currently brute force, grid search, and periodic KDtree methods are\n+    implemented.\n \n     Parameters\n     -----------\n-    reference : array\n-        reference coordinates array with shape ``reference.shape = (3,)``\n-        or ``reference.shape = (len(reference), 3)``\n-    configuration : array\n-        Configuration coordinate array with shape ``reference.shape = (3,)``\n-        or ``reference.shape = (len(reference), 3)``\n+    reference : numpy.ndarray\n+        Reference coordinate array with shape ``(3,)`` or ``(n, 3)``.\n+    configuration : numpy.ndarray\n+        Configuration coordinate array with shape ``(3,)`` or ``(m, 3)``.\n     max_cutoff : float\n-        Maximum cutoff distance between the reference and configuration\n-    min_cutoff : (optional) float\n-        Minimum cutoff distance between reference and configuration [None]\n-    box : (optional) array or None\n-        The dimensions, if provided, must be provided in the same\n-        The unitcell dimesions for this system format as returned\n-        by :attr:`MDAnalysis.coordinates.base.Timestep.dimensions`:\n-        ``[lx,ly, lz, alpha, beta, gamma]``. Minimum image convention\n-        is applied if the box is provided [None]\n-    method : (optional) 'bruteforce' or 'pkdtree' or 'None'\n-        Keyword to override the automatic guessing of method built-in\n-        in the function [None]\n-    return_distances : (optional) 'True'/'False'\n-        Function returns distances if set to 'True'\n+        Maximum cutoff distance between the reference and configuration.\n+    min_cutoff : float, optional\n+        Minimum cutoff distance between reference and configuration.\n+    box : array_like, optional\n+        The unitcell dimensions of the system, which can be orthogonal or\n+        triclinic and must be provided in the same format as returned by\n+        :attr:`MDAnalysis.coordinates.base.Timestep.dimensions`:\\n\n+        ``[lx, ly, lz, alpha, beta, gamma]``.\n+    method : str, optional","path":"package/MDAnalysis/lib/distances.py","position":300,"original_position":300,"commit_id":"63c0a96739fa83c94f25f395880ba482567b93d8","original_commit_id":"63c0a96739fa83c94f25f395880ba482567b93d8","user":{"login":"orbeckst","id":237980,"node_id":"MDQ6VXNlcjIzNzk4MA==","avatar_url":"https://avatars0.githubusercontent.com/u/237980?v=4","gravatar_id":"","url":"https://api.github.com/users/orbeckst","html_url":"https://github.com/orbeckst","followers_url":"https://api.github.com/users/orbeckst/followers","following_url":"https://api.github.com/users/orbeckst/following{/other_user}","gists_url":"https://api.github.com/users/orbeckst/gists{/gist_id}","starred_url":"https://api.github.com/users/orbeckst/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/orbeckst/subscriptions","organizations_url":"https://api.github.com/users/orbeckst/orgs","repos_url":"https://api.github.com/users/orbeckst/repos","events_url":"https://api.github.com/users/orbeckst/events{/privacy}","received_events_url":"https://api.github.com/users/orbeckst/received_events","type":"User","site_admin":false},"body":"You can provide the selection with\r\n```reST\r\nmethod : {\"bruteforce\", \"nsgrid\", \"pkdtree\", None}\r\n     Keyword to override the automatic guessing ofthe employed search method.\r\n     ``None`` chooses an optimal method.\r\n```\r\n(see https://numpydoc.readthedocs.io/en/latest/format.html#sections under _4. Parameters_)","created_at":"2018-09-12T00:37:49Z","updated_at":"2018-09-12T00:57:26Z","html_url":"https://github.com/MDAnalysis/mdanalysis/pull/2070#discussion_r216866463","pull_request_url":"https://api.github.com/repos/MDAnalysis/mdanalysis/pulls/2070","author_association":"MEMBER","_links":{"self":{"href":"https://api.github.com/repos/MDAnalysis/mdanalysis/pulls/comments/216866463"},"html":{"href":"https://github.com/MDAnalysis/mdanalysis/pull/2070#discussion_r216866463"},"pull_request":{"href":"https://api.github.com/repos/MDAnalysis/mdanalysis/pulls/2070"}}},"pull_request":{"url":"https://api.github.com/repos/MDAnalysis/mdanalysis/pulls/2070","id":214702271,"node_id":"MDExOlB1bGxSZXF1ZXN0MjE0NzAyMjcx","html_url":"https://github.com/MDAnalysis/mdanalysis/pull/2070","diff_url":"https://github.com/MDAnalysis/mdanalysis/pull/2070.diff","patch_url":"https://github.com/MDAnalysis/mdanalysis/pull/2070.patch","issue_url":"https://api.github.com/repos/MDAnalysis/mdanalysis/issues/2070","number":2070,"state":"open","locked":false,"title":"improved docstrings in lib/distances.py","user":{"login":"zemanj","id":6999863,"node_id":"MDQ6VXNlcjY5OTk4NjM=","avatar_url":"https://avatars0.githubusercontent.com/u/6999863?v=4","gravatar_id":"","url":"https://api.github.com/users/zemanj","html_url":"https://github.com/zemanj","followers_url":"https://api.github.com/users/zemanj/followers","following_url":"https://api.github.com/users/zemanj/following{/other_user}","gists_url":"https://api.github.com/users/zemanj/gists{/gist_id}","starred_url":"https://api.github.com/users/zemanj/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/zemanj/subscriptions","organizations_url":"https://api.github.com/users/zemanj/orgs","repos_url":"https://api.github.com/users/zemanj/repos","events_url":"https://api.github.com/users/zemanj/events{/privacy}","received_events_url":"https://api.github.com/users/zemanj/received_events","type":"User","site_admin":false},"body":"Fixes (partially) #2046, this is the third of a series of related PRs, following PRs #2048 and #2062.\r\n\r\nChanges made in this Pull Request:\r\n- Improved documentation of all functions in `MDAnalysis.lib.distances`:\r\n  - Ensured that parameters referenced in docstrings correspond to function signatures.\r\n  - Properly formated references to other methods so that links are generated.\r\n  - Now uses logical instead of visual markup.\r\n  - Enforced 80 character lines.\r\n  - Standardized phrasing of repeatedly occurring parameter descriptions.\r\n  - Now uses correct type specifications for parameters and return values.\r\n  - Marked optional parameters by adding *, optional* after the type.\r\n- Removed all `.. autofunction` entries that caused duplicates in the documentation.\r\n- Improved module description to better correspond to its contents.\r\n- `box` parameter of `capped_distance()` and `self_capped_distance()` now also accept `array_like` input (now corresponding to the docs like all other functions accepting box input).\r\n\r\n\r\nPR Checklist\r\n------------\r\n - [ ] Tests?\r\n - [x] Docs?\r\n - [ ] CHANGELOG updated?\r\n - [x] Issue raised/referenced?\r\n","created_at":"2018-09-11T17:06:15Z","updated_at":"2018-09-12T00:57:26Z","closed_at":null,"merged_at":null,"merge_commit_sha":"4ad44001c526cf77c781a1b1d4bbac92b0e29aa6","assignee":null,"assignees":[],"requested_reviewers":[],"requested_teams":[],"labels":[],"milestone":null,"commits_url":"https://api.github.com/repos/MDAnalysis/mdanalysis/pulls/2070/commits","review_comments_url":"https://api.github.com/repos/MDAnalysis/mdanalysis/pulls/2070/comments","review_comment_url":"https://api.github.com/repos/MDAnalysis/mdanalysis/pulls/comments{/number}","comments_url":"https://api.github.com/repos/MDAnalysis/mdanalysis/issues/2070/comments","statuses_url":"https://api.github.com/repos/MDAnalysis/mdanalysis/statuses/63c0a96739fa83c94f25f395880ba482567b93d8","head":{"label":"zemanj:issue-2046-lib-distances-rework","ref":"issue-2046-lib-distances-rework","sha":"63c0a96739fa83c94f25f395880ba482567b93d8","user":{"login":"zemanj","id":6999863,"node_id":"MDQ6VXNlcjY5OTk4NjM=","avatar_url":"https://avatars0.githubusercontent.com/u/6999863?v=4","gravatar_id":"","url":"https://api.github.com/users/zemanj","html_url":"https://github.com/zemanj","followers_url":"https://api.github.com/users/zemanj/followers","following_url":"https://api.github.com/users/zemanj/following{/other_user}","gists_url":"https://api.github.com/users/zemanj/gists{/gist_id}","starred_url":"https://api.github.com/users/zemanj/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/zemanj/subscriptions","organizations_url":"https://api.github.com/users/zemanj/orgs","repos_url":"https://api.github.com/users/zemanj/repos","events_url":"https://api.github.com/users/zemanj/events{/privacy}","received_events_url":"https://api.github.com/users/zemanj/received_events","type":"User","site_admin":false},"repo":{"id":124279541,"node_id":"MDEwOlJlcG9zaXRvcnkxMjQyNzk1NDE=","name":"mdanalysis","full_name":"zemanj/mdanalysis","owner":{"login":"zemanj","id":6999863,"node_id":"MDQ6VXNlcjY5OTk4NjM=","avatar_url":"https://avatars0.githubusercontent.com/u/6999863?v=4","gravatar_id":"","url":"https://api.github.com/users/zemanj","html_url":"https://github.com/zemanj","followers_url":"https://api.github.com/users/zemanj/followers","following_url":"https://api.github.com/users/zemanj/following{/other_user}","gists_url":"https://api.github.com/users/zemanj/gists{/gist_id}","starred_url":"https://api.github.com/users/zemanj/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/zemanj/subscriptions","organizations_url":"https://api.github.com/users/zemanj/orgs","repos_url":"https://api.github.com/users/zemanj/repos","events_url":"https://api.github.com/users/zemanj/events{/privacy}","received_events_url":"https://api.github.com/users/zemanj/received_events","type":"User","site_admin":false},"private":false,"html_url":"https://github.com/zemanj/mdanalysis","description":"MDAnalysis is a Python library to analyze molecular dynamics trajectories.","fork":true,"url":"https://api.github.com/repos/zemanj/mdanalysis","forks_url":"https://api.github.com/repos/zemanj/mdanalysis/forks","keys_url":"https://api.github.com/repos/zemanj/mdanalysis/keys{/key_id}","collaborators_url":"https://api.github.com/repos/zemanj/mdanalysis/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/zemanj/mdanalysis/teams","hooks_url":"https://api.github.com/repos/zemanj/mdanalysis/hooks","issue_events_url":"https://api.github.com/repos/zemanj/mdanalysis/issues/events{/number}","events_url":"https://api.github.com/repos/zemanj/mdanalysis/events","assignees_url":"https://api.github.com/repos/zemanj/mdanalysis/assignees{/user}","branches_url":"https://api.github.com/repos/zemanj/mdanalysis/branches{/branch}","tags_url":"https://api.github.com/repos/zemanj/mdanalysis/tags","blobs_url":"https://api.github.com/repos/zemanj/mdanalysis/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/zemanj/mdanalysis/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/zemanj/mdanalysis/git/refs{/sha}","trees_url":"https://api.github.com/repos/zemanj/mdanalysis/git/trees{/sha}","statuses_url":"https://api.github.com/repos/zemanj/mdanalysis/statuses/{sha}","languages_url":"https://api.github.com/repos/zemanj/mdanalysis/languages","stargazers_url":"https://api.github.com/repos/zemanj/mdanalysis/stargazers","contributors_url":"https://api.github.com/repos/zemanj/mdanalysis/contributors","subscribers_url":"https://api.github.com/repos/zemanj/mdanalysis/subscribers","subscription_url":"https://api.github.com/repos/zemanj/mdanalysis/subscription","commits_url":"https://api.github.com/repos/zemanj/mdanalysis/commits{/sha}","git_commits_url":"https://api.github.com/repos/zemanj/mdanalysis/git/commits{/sha}","comments_url":"https://api.github.com/repos/zemanj/mdanalysis/comments{/number}","issue_comment_url":"https://api.github.com/repos/zemanj/mdanalysis/issues/comments{/number}","contents_url":"https://api.github.com/repos/zemanj/mdanalysis/contents/{+path}","compare_url":"https://api.github.com/repos/zemanj/mdanalysis/compare/{base}...{head}","merges_url":"https://api.github.com/repos/zemanj/mdanalysis/merges","archive_url":"https://api.github.com/repos/zemanj/mdanalysis/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/zemanj/mdanalysis/downloads","issues_url":"https://api.github.com/repos/zemanj/mdanalysis/issues{/number}","pulls_url":"https://api.github.com/repos/zemanj/mdanalysis/pulls{/number}","milestones_url":"https://api.github.com/repos/zemanj/mdanalysis/milestones{/number}","notifications_url":"https://api.github.com/repos/zemanj/mdanalysis/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/zemanj/mdanalysis/labels{/name}","releases_url":"https://api.github.com/repos/zemanj/mdanalysis/releases{/id}","deployments_url":"https://api.github.com/repos/zemanj/mdanalysis/deployments","created_at":"2018-03-07T18:46:58Z","updated_at":"2018-09-03T13:39:59Z","pushed_at":"2018-09-11T16:50:42Z","git_url":"git://github.com/zemanj/mdanalysis.git","ssh_url":"git@github.com:zemanj/mdanalysis.git","clone_url":"https://github.com/zemanj/mdanalysis.git","svn_url":"https://github.com/zemanj/mdanalysis","homepage":"https://mdanalysis.org","size":197324,"stargazers_count":0,"watchers_count":0,"language":"Python","has_issues":false,"has_projects":true,"has_downloads":false,"has_wiki":true,"has_pages":false,"forks_count":0,"mirror_url":null,"archived":false,"open_issues_count":0,"license":{"key":"gpl-2.0","name":"GNU General Public License v2.0","spdx_id":"GPL-2.0","url":"https://api.github.com/licenses/gpl-2.0","node_id":"MDc6TGljZW5zZTg="},"forks":0,"open_issues":0,"watchers":0,"default_branch":"develop"}},"base":{"label":"MDAnalysis:develop","ref":"develop","sha":"e0a2b16c41c443f4f72b14e8af5c2b77051915c0","user":{"login":"MDAnalysis","id":11445951,"node_id":"MDEyOk9yZ2FuaXphdGlvbjExNDQ1OTUx","avatar_url":"https://avatars1.githubusercontent.com/u/11445951?v=4","gravatar_id":"","url":"https://api.github.com/users/MDAnalysis","html_url":"https://github.com/MDAnalysis","followers_url":"https://api.github.com/users/MDAnalysis/followers","following_url":"https://api.github.com/users/MDAnalysis/following{/other_user}","gists_url":"https://api.github.com/users/MDAnalysis/gists{/gist_id}","starred_url":"https://api.github.com/users/MDAnalysis/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/MDAnalysis/subscriptions","organizations_url":"https://api.github.com/users/MDAnalysis/orgs","repos_url":"https://api.github.com/users/MDAnalysis/repos","events_url":"https://api.github.com/users/MDAnalysis/events{/privacy}","received_events_url":"https://api.github.com/users/MDAnalysis/received_events","type":"Organization","site_admin":false},"repo":{"id":33389183,"node_id":"MDEwOlJlcG9zaXRvcnkzMzM4OTE4Mw==","name":"mdanalysis","full_name":"MDAnalysis/mdanalysis","owner":{"login":"MDAnalysis","id":11445951,"node_id":"MDEyOk9yZ2FuaXphdGlvbjExNDQ1OTUx","avatar_url":"https://avatars1.githubusercontent.com/u/11445951?v=4","gravatar_id":"","url":"https://api.github.com/users/MDAnalysis","html_url":"https://github.com/MDAnalysis","followers_url":"https://api.github.com/users/MDAnalysis/followers","following_url":"https://api.github.com/users/MDAnalysis/following{/other_user}","gists_url":"https://api.github.com/users/MDAnalysis/gists{/gist_id}","starred_url":"https://api.github.com/users/MDAnalysis/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/MDAnalysis/subscriptions","organizations_url":"https://api.github.com/users/MDAnalysis/orgs","repos_url":"https://api.github.com/users/MDAnalysis/repos","events_url":"https://api.github.com/users/MDAnalysis/events{/privacy}","received_events_url":"https://api.github.com/users/MDAnalysis/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/MDAnalysis/mdanalysis","description":"MDAnalysis is a Python library to analyze molecular dynamics trajectories.","fork":false,"url":"https://api.github.com/repos/MDAnalysis/mdanalysis","forks_url":"https://api.github.com/repos/MDAnalysis/mdanalysis/forks","keys_url":"https://api.github.com/repos/MDAnalysis/mdanalysis/keys{/key_id}","collaborators_url":"https://api.github.com/repos/MDAnalysis/mdanalysis/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/MDAnalysis/mdanalysis/teams","hooks_url":"https://api.github.com/repos/MDAnalysis/mdanalysis/hooks","issue_events_url":"https://api.github.com/repos/MDAnalysis/mdanalysis/issues/events{/number}","events_url":"https://api.github.com/repos/MDAnalysis/mdanalysis/events","assignees_url":"https://api.github.com/repos/MDAnalysis/mdanalysis/assignees{/user}","branches_url":"https://api.github.com/repos/MDAnalysis/mdanalysis/branches{/branch}","tags_url":"https://api.github.com/repos/MDAnalysis/mdanalysis/tags","blobs_url":"https://api.github.com/repos/MDAnalysis/mdanalysis/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/MDAnalysis/mdanalysis/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/MDAnalysis/mdanalysis/git/refs{/sha}","trees_url":"https://api.github.com/repos/MDAnalysis/mdanalysis/git/trees{/sha}","statuses_url":"https://api.github.com/repos/MDAnalysis/mdanalysis/statuses/{sha}","languages_url":"https://api.github.com/repos/MDAnalysis/mdanalysis/languages","stargazers_url":"https://api.github.com/repos/MDAnalysis/mdanalysis/stargazers","contributors_url":"https://api.github.com/repos/MDAnalysis/mdanalysis/contributors","subscribers_url":"https://api.github.com/repos/MDAnalysis/mdanalysis/subscribers","subscription_url":"https://api.github.com/repos/MDAnalysis/mdanalysis/subscription","commits_url":"https://api.github.com/repos/MDAnalysis/mdanalysis/commits{/sha}","git_commits_url":"https://api.github.com/repos/MDAnalysis/mdanalysis/git/commits{/sha}","comments_url":"https://api.github.com/repos/MDAnalysis/mdanalysis/comments{/number}","issue_comment_url":"https://api.github.com/repos/MDAnalysis/mdanalysis/issues/comments{/number}","contents_url":"https://api.github.com/repos/MDAnalysis/mdanalysis/contents/{+path}","compare_url":"https://api.github.com/repos/MDAnalysis/mdanalysis/compare/{base}...{head}","merges_url":"https://api.github.com/repos/MDAnalysis/mdanalysis/merges","archive_url":"https://api.github.com/repos/MDAnalysis/mdanalysis/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/MDAnalysis/mdanalysis/downloads","issues_url":"https://api.github.com/repos/MDAnalysis/mdanalysis/issues{/number}","pulls_url":"https://api.github.com/repos/MDAnalysis/mdanalysis/pulls{/number}","milestones_url":"https://api.github.com/repos/MDAnalysis/mdanalysis/milestones{/number}","notifications_url":"https://api.github.com/repos/MDAnalysis/mdanalysis/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/MDAnalysis/mdanalysis/labels{/name}","releases_url":"https://api.github.com/repos/MDAnalysis/mdanalysis/releases{/id}","deployments_url":"https://api.github.com/repos/MDAnalysis/mdanalysis/deployments","created_at":"2015-04-04T00:39:41Z","updated_at":"2018-09-11T22:32:09Z","pushed_at":"2018-09-11T23:44:08Z","git_url":"git://github.com/MDAnalysis/mdanalysis.git","ssh_url":"git@github.com:MDAnalysis/mdanalysis.git","clone_url":"https://github.com/MDAnalysis/mdanalysis.git","svn_url":"https://github.com/MDAnalysis/mdanalysis","homepage":"https://mdanalysis.org","size":207606,"stargazers_count":223,"watchers_count":223,"language":"Python","has_issues":true,"has_projects":true,"has_downloads":false,"has_wiki":true,"has_pages":true,"forks_count":137,"mirror_url":null,"archived":false,"open_issues_count":189,"license":{"key":"gpl-2.0","name":"GNU General Public License v2.0","spdx_id":"GPL-2.0","url":"https://api.github.com/licenses/gpl-2.0","node_id":"MDc6TGljZW5zZTg="},"forks":137,"open_issues":189,"watchers":223,"default_branch":"develop"}},"_links":{"self":{"href":"https://api.github.com/repos/MDAnalysis/mdanalysis/pulls/2070"},"html":{"href":"https://github.com/MDAnalysis/mdanalysis/pull/2070"},"issue":{"href":"https://api.github.com/repos/MDAnalysis/mdanalysis/issues/2070"},"comments":{"href":"https://api.github.com/repos/MDAnalysis/mdanalysis/issues/2070/comments"},"review_comments":{"href":"https://api.github.com/repos/MDAnalysis/mdanalysis/pulls/2070/comments"},"review_comment":{"href":"https://api.github.com/repos/MDAnalysis/mdanalysis/pulls/comments{/number}"},"commits":{"href":"https://api.github.com/repos/MDAnalysis/mdanalysis/pulls/2070/commits"},"statuses":{"href":"https://api.github.com/repos/MDAnalysis/mdanalysis/statuses/63c0a96739fa83c94f25f395880ba482567b93d8"}},"author_association":"MEMBER"}}
{"actor":{"display_login":"orbeckst"}}