feature: separate max edge distance from interaction radius throughout

[DaniBodor]

I think this one is also best reviewed one commit at a time, even though it's only 3 commits.
The final commit is not really part of this issue, but I went through the entire code and fixed/simplified/added type hinting throughout the code base. I can move it to a separate PR if you think it's better, but I had done it in between this one and #506, which builds on this. That is why it is currently here.

Changes:

• Clarify distance_cutoff vs radius across different Query classes (see here)
  • Rename the parameters to avoid confusion
    • radius becomes influence_radius = the distance from the structure of interest (variant residue or any interface residue) to look for residues to include
    • cutoff becomes max_edge_length = the maximum distance between two nodes to include an edge between them.
  • Add interaction_radius parameter for PPI; previously only SRVs were using separate paramenters, while PPI was using cutoff to mean both things.
  • Remove edge_distance_cutoff as a Graph attribute, because it serves no purpose.
• Decided against allowing for setting these to 0 to mean infinity/include all
  • It's quite a bit of effort, especially with adding tests (which would also be slow).
  • It's very rare that someone should want to do this, so we should not make it "easy" to do so for users who don't know what they're doing.
  • If someone really wants to include everything, they can just be set to an extremely high value and it will do the same.

closes #460

[github-actions]

This PR is stale because it has been open for 14 days with no activity.

[gcroci2]

I've asked @cbaakman's review as well, only to verify that this PR doesn't break some logic that was meant for the old cutoffs. No need to go through the code in-depth, a conceptual confirmation would be more than enough :)

[gcroci2]

I'd suggest max_nodes_distance (maximum distance between nodes for having an edge) or max_distance_edge (same but making nodes implicit) to avoid confusion from the naming

[DaniBodor]

I agree that edge distance is not the correct terminology. How about something relating to edge length instead? Like max_edge_length or edge_length_cutoff or cutoff_edge_length?

[DaniBodor]

it's a bit tough because "length" and "distance" both have a different meaning than this in graph theory

[gcroci2]

max_edge_length

[gcroci2]

since edges represent interactions, then isn't interaction_radius conceptually the same thing as max_edge_distance? Maybe the radius doesn't have to be necessarily about interactions (thus could be radius only), while edges should always be about interactions. Otherwise, what's the conceptual difference between these two variables?

[DaniBodor]

Edges don't necessarily equate to interactions. I think mostly this will be the case, and by default I would use the same value (and we do), but there could be situations where interaction_radius is higher than max_edge_distance. This could be the case 1) purely to decrease computational power/time, or 2) e.g. because the "secondary" interactions can be relevant. Even if two nodes don't have an edge between them, an intermediate node could be affected by both edges.
I can't off the top of my head think of a situation where max_edge_distance would be larger than interaction_radius, and am not sure that would even make sense to do. Maybe we can create a waning/error/cap in case the user sets cutoff > radius. What do you think?

Note that in interaction_radius I am not necessarily talking about protein-protein-interactions (trans interactions), but could also be cis-interactions (so residues of the same protein interacting with each other). So also in a variant, if residues are too far away, they would not interact with/affect the variant residue so don't need to be considered.

I agree that the terminology is confusing, though. At the same time, I find radius too generic, it doesn't really describe what the parameter is either. Let's see if we can come up with another nomenclature. Maybe something along the lines of sphere_of_influence, although that sounds too fuzzy to me as well. Maybe influence_radius?

[DaniBodor]

as above, "radius" also has a specific meaning in graph theory.

[gcroci2]

influence_radius

[gcroci2]

Nice work, almost there :) I left few comments we need to reflect on before proceeding with the merging. Let me know what do you think about them

[DaniBodor]

So we just need to agree on a nomenclature here, and then I can merge this PR.

My newest suggestions are influence_radius and either max_edge_length or edge_length_cutoff (see below for they represent). What do you think?

radius becomes interaction_radius = the distance from the structure of interest (variant residue or interface) to look for residues to include
cutoff becomes max_edge_distance = the maximum distance between two nodes to include an edge between them.

[gcroci2]

So we just need to agree on a nomenclature here, and then I can merge this PR.

My newest suggestions are influence_radius and either max_edge_length or edge_length_cutoff (see below for they represent). What do you think?

radius becomes interaction_radius = the distance from the structure of interest (variant residue or interface) to look for residues to include
cutoff becomes max_edge_distance = the maximum distance between two nodes to include an edge between them.

Indeed, so as agreed I'd go for max_edge_length and influence_radius