New hinge identification method #2179

stoneandbone · 2025-10-09T20:08:09Z

[HZ384] Update: Enhanced Hinge Identification Function

This update refines the hinge site detection algorithm based on the methodology of [HZ384] H. Zhang, M. Gur, I. Bahar (2024), PNAS 121(49): e2414333121.

Summary of changes:

Adaptive mode selection: If a GNM model is provided without specifying n_modes, the number of modes is now automatically determined to achieve 33% cumulative variance. When GNM modes are supplied, all provided modes are used for hinge detection.
Hinge detection: Hinges are identified from crossover points and residues within a defined threshold band in the eigenvector.
Region merging: Overlapping or adjacent hinge regions are merged, with optional user-defined spacing tolerance.
Transient reduction: Transient hinge regions are filtered out to improve robustness.
Terminal trimming: Hinges at N- or C-terminal ends, where loops may be presented, may be trimmed based on user preference.
Output: Returns a list of hinges by mode for downstream analysis.

AnthonyBogetti · 2025-10-10T16:16:14Z

@jamesmkrieger, this is the code from Frank for finding Hinges (PNAS ref in the main block of the PR) that I mentioned before. @stoneandbone very kindly implemented it. Does this overall implementation look okay to you?

prody/dynamics/analysis.py

jamesmkrieger

This looks good to me. I just have a few changes, mainly for efficiency.

I didn’t understand the bits with the bands and merging regions but I imagine they are right.

It would also be good to have some unit tests that verify the type and shape of the output as well as the numerical values and how they are affected by the parameters.

jamesmkrieger · 2025-10-10T16:45:53Z

Thanks very much for making this

AnthonyBogetti · 2025-10-10T16:55:29Z

Thanks @jamesmkrieger! I will work with @stoneandbone to address these.

stoneandbone · 2025-12-02T17:14:19Z

@jamesmkrieger I have addressed all your suggested fixes, and @AnthonyBogetti and I added a unit test. Please review at your convenience! :)

AnthonyBogetti · 2025-12-02T17:57:34Z

The (random) test failures here are due to the pfam tests which should be fixed in #2189 maybe we can merge that one first.

jamesmkrieger · 2025-12-02T23:01:25Z

The (random) test failures here are due to the pfam tests which should be fixed in #2189 maybe we can merge that one first.

I agree

jamesmkrieger · 2025-12-04T07:49:54Z

prody/dynamics/analysis.py

+        6) Return list of hinges by mode.
+    
+    :param modes: GNM model or ModeSet
+    :type modes: GNM or Mode instance


Use the format that sphinx can read like in other doc strings. Also put ModeSet again in type and put a more meaningful description than the types in the bit above, linking to what was said above about selecting modes.

Double check that param is ok too. We usually put arg

A user could also provide vectors as inputs directly

jamesmkrieger · 2025-12-04T07:50:32Z

prody/dynamics/analysis.py

+    :param modes: GNM model or ModeSet
+    :type modes: GNM or Mode instance
+    :param n_modes: Number of modes to consider. Defaults to all.
+    :type n_modes: int or None


Check if or is ok. We usually put a comma. Again remember this should be machine readable as well as human readable

Maybe handle default of None in the bit above as well or instead e.g. defaults to all modes if left as None

jamesmkrieger · 2025-12-04T07:55:25Z

prody/dynamics/analysis.py

+    :param space: spacing between hinges. Defaults to None. Higher space value will minimize the number of local hinges while retaining global hinges.
+    :type space: int or None
+    
+    :param trim: Whether to hinges at the N- or C-terminal ends by Protein length // 20. Defaults to False.


Perhaps there could be a parameter for how much counts as terminal with options for a fraction as a float less than 1 or a number of residues as an int from 1 onwards. Dividing by 20 is huge for some proteins e.g. 1000//20=50 residues.

Having atoms as inputs would also allow you to handle multiple chains, which is currently lacking. At the moment there would be merging across chain boundaries

I’d suggest the default as 5 residues

jamesmkrieger · 2025-12-04T07:57:56Z

prody/dynamics/analysis.py

+            raise TypeError("Input must be a GNM model or ModeSet instance.")
+        else:
+            if gnm._kirchhoff is None:
+                raise ValueError("Kirchhoff matrix not built. Build Kirchhoff matrix before calculating modes.")


Maybe a structure could be provided to build the Kirchhoff internally. Providing a gnm object with the Kirchoff built is a bit counterintuitive

jamesmkrieger · 2025-12-04T08:06:15Z

prody/dynamics/analysis.py

+
+            vecs = gnm[:n_modes].getEigvecs()
+    else:
+        ### Use all provided modes for Hinge detection ###


Ideally simplify the nested if else logic or otherwise document it with a few more comments. It looks like this is the ModeSet case. You could maybe also put this input handling in a helper function so you can return the modes array. It could be easier for readability and could also be a good output to have for diagnostics.

it could also be good to return the calculated and selected gnm modes as an option more globally as well.

also, there seems to be no handling of the case where a gnm object is provided with modes calculated. In that case they should be used directly

jamesmkrieger · 2025-12-04T08:07:27Z

prody/dynamics/analysis.py

+        vecs = gnm.getArray()
+
+
+    def detectHinges(v, threshold):


I’d suggest making this a separate function rather than a nested one so people can run it with their own vectors and threshold. It would also help with readability and maintainability

jamesmkrieger · 2025-12-04T08:27:11Z

prody/dynamics/analysis.py

+        for i in crx:
+            r = [i, i + 1]
+
+            if abs(v[i]) > band and abs(v[i + 1]) > band:


Again simplify nested if else blocks. ChatGPT suggests this. Please check if it makes sense

band = np.sqrt(1 / len(v)) / threshold regs = [] for i in crx: # Start hinge region around the sign change start = i end = i + 1 # Expand left j = start while j >= 0 and abs(v[j]) < band: start = j j -= 1 # Expand right j = end while j < len(v) and abs(v[j]) < band: end = j j += 1 # Store inclusive region regs.append(list(range(start, end + 1)))

jamesmkrieger · 2025-12-04T08:35:59Z

prody/dynamics/analysis.py

+    """
+    [HZ384] H Zhang, M Gur, I Bahar (2024) Global hinge sites of proteins as target sites for drug binding Proc Natl Acad Sci USA 121 (49), e2414333121 
+    Updated hinge identification based on [HZ384]. This will:
+        1) If GNM model is provided without specification of n_modes, number of modes will be determined to achieve 33% cumulative variance.


I guess a different percentage could also be used as a decimal input to the number of modes

jamesmkrieger

It would be good to reorganise for readability and usability. We’d have two step functions outside the main function that could be helpful in their own right (see below)

one for subsetting modes by cumulative variance that could be helpful for PCA and maybe ANM modes too
One for calculating hinges for a single mode

please include better control of termini and multiple chains. Also handle calculation of kirchhoff inside and provided gnm with already calculated mode

the tests would also need cases for multiple chains e.g. 3kg2 that we analysed in Dutta et 2015

I haven’t had the chance to look over the tests or to test it and I don’t think I will be able to. If you and @AnthonyBogetti are happy after these changes, then I am too

AnthonyBogetti · 2025-12-04T15:24:49Z

@stoneandbone Please see and address James' most recent round of comments.

Need to re-review.

James' changes were addressed, and due to lack of time on his end for a re-review, we have dismissed the review.

AnthonyBogetti · 2025-12-19T19:25:13Z

Miraculously, the current tests all passed.

stoneandbone · 2025-12-19T19:28:07Z

[laugh] Kwan, Ming Suet reacted to your message:

…

________________________________ From: Anthony Bogetti ***@***.***> Sent: Friday, December 19, 2025 7:25:35 PM To: prody/ProDy ***@***.***> Cc: stoneandbone ***@***.***>; Mention ***@***.***> Subject: Re: [prody/ProDy] New hinge identification method (PR #2179) CAUTION: This email originated from outside of the organization. Do not click links or open attachments unless you recognize the sender and know the content is safe. [https://avatars.githubusercontent.com/u/34397256?s=20&v=4]AnthonyBogetti left a comment (prody/ProDy#2179)<#2179 (comment)> Miraculously, the current tests all passed. — Reply to this email directly, view it on GitHub<#2179 (comment)>, or unsubscribe<https://github.com/notifications/unsubscribe-auth/BGTWRPRFJSHGLTUIQOXDSRD4CRGK7AVCNFSM6AAAAACIYTTJO6VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZTMNZWGI3DQNRRGA>. You are receiving this because you were mentioned.Message ID: ***@***.***> This e-mail message, including any attachments, is for the sole use of the intended recipient(s) and may contain confidential and privileged information. Any unauthorized review, use, disclosure or distribution is prohibited. If you are not the intended recipient, please contact the sender by e-mail and destroy all copies of the original.

jamesmkrieger · 2025-12-19T23:06:06Z

prody/dynamics/analysis.py

+        return gnm.getArray()
+
+    if not isinstance(gnm, GNMBase):
+        raise TypeError("Input must be a GNM model or ModeSet instance.")


Maybe allow gnm=None if atoms is not None as a new gnm can be instantiated? People are unlikely to input a newly instantiated gnm object themselves

stoneandbone added 2 commits October 9, 2025 15:13

updated hinge identification

186c0e9

updated hinge identification

4d7d4ba

AnthonyBogetti requested review from AnthonyBogetti and jamesmkrieger October 10, 2025 16:14

jamesmkrieger reviewed Oct 10, 2025

View reviewed changes

prody/dynamics/analysis.py Outdated Show resolved Hide resolved

jamesmkrieger reviewed Oct 10, 2025

View reviewed changes

prody/dynamics/analysis.py Outdated Show resolved Hide resolved

jamesmkrieger reviewed Oct 10, 2025

View reviewed changes

prody/dynamics/analysis.py Outdated Show resolved Hide resolved

jamesmkrieger reviewed Oct 10, 2025

View reviewed changes

prody/dynamics/analysis.py Outdated Show resolved Hide resolved

jamesmkrieger requested changes Oct 10, 2025

View reviewed changes

AnthonyBogetti requested a review from vbadwaj October 15, 2025 17:23

AnthonyBogetti assigned vbadwaj Oct 15, 2025

stoneandbone and others added 2 commits December 1, 2025 15:47

Merge branch 'prody:main' into new-hinge

3b9c5b1

fixes and unit test added

2e763ef

stoneandbone requested a review from jamesmkrieger December 2, 2025 17:14

AnthonyBogetti added the Awaiting review label Dec 3, 2025

AnthonyBogetti previously approved these changes Dec 3, 2025

View reviewed changes

AnthonyBogetti added Approved but tests failing and removed Awaiting review labels Dec 3, 2025

AnthonyBogetti assigned AnthonyBogetti and unassigned vbadwaj Dec 3, 2025

AnthonyBogetti removed the request for review from vbadwaj December 3, 2025 20:02

AnthonyBogetti added Awaiting review and removed Approved but tests failing labels Dec 3, 2025

jamesmkrieger reviewed Dec 4, 2025

View reviewed changes

jamesmkrieger previously requested changes Dec 4, 2025

View reviewed changes

AnthonyBogetti added Awaiting changes and removed Awaiting review labels Dec 4, 2025

AnthonyBogetti added the New feature label Dec 15, 2025

Added atom option and subsetting out the helper functions

fad704a

AnthonyBogetti requested review from jamesmkrieger and removed request for jamesmkrieger December 19, 2025 19:24

jamesmkrieger reviewed Dec 19, 2025

View reviewed changes

New hinge identification method #2179

Are you sure you want to change the base?

New hinge identification method #2179

Conversation

stoneandbone commented Oct 9, 2025

Uh oh!

AnthonyBogetti commented Oct 10, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jamesmkrieger left a comment

Choose a reason for hiding this comment

Uh oh!

jamesmkrieger commented Oct 10, 2025

Uh oh!

AnthonyBogetti commented Oct 10, 2025

Uh oh!

stoneandbone commented Dec 2, 2025

Uh oh!

AnthonyBogetti commented Dec 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jamesmkrieger commented Dec 2, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jamesmkrieger left a comment

Choose a reason for hiding this comment

Uh oh!

AnthonyBogetti commented Dec 4, 2025

Uh oh!

AnthonyBogetti commented Dec 19, 2025

Uh oh!

stoneandbone commented Dec 19, 2025 via email

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

AnthonyBogetti commented Dec 2, 2025 •

edited

Loading