docs: add detailed documentation for Instability Index calculation#15
Merged
Conversation
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: c5658ca6bb
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
Siddharthakhandelwal
approved these changes
Mar 22, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This PR introduces comprehensive documentation demystifying the Instability Index calculation used within Protly's Lab-Readiness Metrics. It provides clear, scientifically backed information on how the metric is computed and why the current architectural approach (using Biopython) is optimal.
Changes Included:
📄 New File: Added
instability_index.md
to the root directory, which covers:
The definition and UI thresholds ("Stable" < 40 vs "Unstable" >= 40) for the Instability Index.
An in-depth look at the Biopython (Bio.SeqUtils.ProtParam) module used for the computation.
The algorithmic logic (dipeptide occurrences) and the 1990 peer-reviewed scientific literature (Guruprasad K. et al.) it is based on.
An explanation of why using an industry-standard library is safer, faster, and more robust than hard-coding the 400 dipeptide weights manually.
External references to the original paper, Biopython documentation, and source code.
📝 README Update: Linked this new documentation directly in the
README.md
under the "Protein Analysis Pipeline" section for easy discovery by users and contributors.
Why is this needed? To ensure transparency and scientific rigor for our users. By documenting the specific library, its validation mechanisms, and the underlying mathematical/scientific basis of the stability score, we increase trust in the platform's analytical results. Furthermore, it aids future developers in understanding why Biopython is utilized instead of custom-built, hard-coded logic.
closes #8