{"id":22886611,"url":"https://github.com/zenodeapp/pairwise-alignments","last_synced_at":"2025-05-07T10:30:46.024Z","repository":{"id":61303772,"uuid":"548487719","full_name":"zenodeapp/pairwise-alignments","owner":"zenodeapp","description":"Solidity implementations of well-known pairwise alignment methods such as Needleman-Wunsch's global sequence alignment and the Smith-Waterman local sequence alignment algorithm.","archived":false,"fork":false,"pushed_at":"2023-12-07T20:05:11.000Z","size":150,"stargazers_count":2,"open_issues_count":0,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2023-12-07T21:22:16.819Z","etag":null,"topics":["algorithm","alignment","amino-acids","contracts","dna","needleman-wunsch","nucleotides","proteins","smith-waterman","solidity","substitution-matrices"],"latest_commit_sha":null,"homepage":"","language":"Solidity","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zenodeapp.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2022-10-09T17:12:45.000Z","updated_at":"2023-07-19T05:36:10.000Z","dependencies_parsed_at":"2023-01-29T02:16:03.125Z","dependency_job_id":null,"html_url":"https://github.com/zenodeapp/pairwise-alignments","commit_stats":null,"previous_names":[],"tags_count":0,"template":null,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zenodeapp%2Fpairwise-alignments","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zenodeapp%2Fpairwise-alignments/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zenodeapp%2Fpairwise-alignments/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zenodeapp%2Fpairwise-alignments/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zenodeapp","download_url":"https://codeload.github.com/zenodeapp/pairwise-alignments/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":229609269,"owners_count":18098159,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["algorithm","alignment","amino-acids","contracts","dna","needleman-wunsch","nucleotides","proteins","smith-waterman","solidity","substitution-matrices"],"created_at":"2024-12-13T20:19:29.958Z","updated_at":"2024-12-13T20:19:30.585Z","avatar_url":"https://github.com/zenodeapp.png","language":"Solidity","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Pairwise Alignments\n\nSolidity implementations of well-known pairwise alignment methods such as Needleman-Wunsch's global sequence alignment and the Smith-Waterman local sequence alignment algorithm.\n\nThis has been built by ZENODE within the Hardhat environment and is licensed under the MIT-license (see [LICENSE.md](./LICENSE.md)).\n\nA fully functioning dApp can be found here: https://pairwize.zenode.app.\n\n## Overview\n\n### Dependencies\n\n- `hardhat` (npm module)\n- Uses the [`substitution-matrices`](/submodules) repository, which is automatically included as a Git submodule.\n- Uses the [`zenode-contracts`](/submodules) repository, which is automatically included as a Git submodule.\n\n### Features\n\n- Expandable; similar pairwise alignment methods could inherit functionality from the [\\_PairwiseAlignment](contracts/_PairwiseAlignment.sol)-contract.\n- Modular; loose coupling and high cohesion promote easy implementation into other contracts.\n- Re-usable; deploy only once and use in multiple contracts.\n  - An idea: use these contracts as building blocks for a [\u003ci\u003eMultiple Sequence Alignment\u003c/i\u003e](https://en.wikipedia.org/wiki/Multiple_sequence_alignment)-contract (links to Wikipedia).\n- Ownership; access control and administrative privilege management.\n\n### Algorithms\n\n- [Needleman-Wunsch](contracts/NeedlemanWunsch.sol)'s \u003ci\u003eglobal\u003c/i\u003e sequence alignment algorithm.\n- [Smith-Waterman](contracts/SmithWaterman.sol)'s \u003ci\u003elocal\u003c/i\u003e sequence alignment algorithm.\n\n### Hardhat\n\n- Scripts\n  - deployment/needlemanWunsch.js - deploys the Needleman-Wunsch contract to the configured network.\n  - deployment/smithWaterman.js - deploys the Smith-Waterman contract to the configured network.\n- Tasks for contract interaction (see [7. Interaction](#7-interaction)).\n\n## Getting Started\n\n### TL;DR\n\n\u003e [`0. Clone`](#0-clone) \u003ci\u003e--use the --recursive flag.\u003c/i\u003e\n\u003e\n\u003e ```\n\u003e git clone --recursive https://github.com/zenodeapp/pairwise-alignments.git \u003cdestination_folder\u003e\n\u003e ```\n\u003e\n\u003e [`1. Installation`](#1-installation) \u003ci\u003e--use npm, yarn or any other package manager.\u003c/i\u003e\n\u003e\n\u003e ```\n\u003e npm install\n\u003e ```\n\u003e\n\u003e ```\n\u003e yarn install\n\u003e ```\n\u003e\n\u003e [`2. Run the test node`](#2-configure-and-run-your-test-node) \u003ci\u003e--do this in a separate terminal!\u003c/i\u003e\n\u003e\n\u003e ```script\n\u003e npx hardhat node\n\u003e ```\n\u003e\n\u003e [`3. Substitution Matrices (Intermezzo)`](#3-substitution-matrices-intermezzo) \u003ci\u003e--skip if you've already deployed the SubstitutionMatrices-contract!\u003c/i\u003e\n\u003e\n\u003e ```script\n\u003e cd submodules/substitution-matrices\n\u003e ```\n\u003e\n\u003e ```javascript\n\u003e // Follow step 1 to 5, excluding step 2, in the TL;DR of submodules/substitution-matrices/README.md\n\u003e ```\n\u003e\n\u003e ```script\n\u003e cd ../..\n\u003e ```\n\u003e\n\u003e [`4. Pre-configuration`](#4-pre-configuration) \u003ci\u003e--add the SubstitutionMatrices address to [zenode.config.js](zenode.config.js).\u003c/i\u003e\n\u003e\n\u003e ```javascript\n\u003e   contracts: {\n\u003e     needlemanWunsch: {\n\u003e       name: \"NeedlemanWunsch\",\n\u003e       address: \"\",\n\u003e       parameters: {\n\u003e         _matricesAddress: \"ADD_SUBSTITUTION_MATRICES_ADDRESS_HERE\",\n\u003e       },\n\u003e     },\n\u003e     ...\n\u003e   }\n\u003e ```\n\u003e\n\u003e \u003e Repeat for any other algorithm you wish to deploy.\n\u003e\n\u003e [`5. Deployment`](#5-deployment)\n\u003e\n\u003e ```\n\u003e npx hardhat run scripts/deployment/needlemanWunsch.js\n\u003e ```\n\u003e\n\u003e ```\n\u003e npx hardhat run scripts/deployment/smithWaterman.js\n\u003e ```\n\u003e\n\u003e \u003e Only deploy the one(s) you pre-configured, see [scripts/deployment](scripts/deployment) for all possible algorithms.\n\u003e\n\u003e [`6. Configuration`](#6-configuration) \u003ci\u003e--add the algorithm's contract address to [zenode.config.js](zenode.config.js).\u003c/i\u003e\n\u003e\n\u003e ```javascript\n\u003e   contracts: {\n\u003e     needlemanWunsch: {\n\u003e       name: \"NeedlemanWunsch\",\n\u003e       address: \"ADD_NW_ALGORITHM_ADDRESS_HERE\",\n\u003e       ...\n\u003e     },\n\u003e     ...\n\u003e   },\n\u003e ```\n\u003e\n\u003e \u003e Repeat for any other algorithm you deployed.\n\u003e\n\u003e [`7. Interaction`](#7-interaction) \u003ci\u003e--use the scripts provided in the [Interaction](#7-interaction) phase.\u003c/i\u003e\n\n### 0. Clone\n\nTo get started, clone the repository with the `--recursive` flag:\n\n```\ngit clone --recursive https://github.com/zenodeapp/pairwise-alignments.git \u003cdestination_folder\u003e\n```\n\n\u003e This repository includes submodules and should thus contain the `--recursive` flag.\n\n\u003cbr\u003e\n\nIf you've already downloaded, forked or cloned this repository without including the `--recursive` flag, then run this command from the root folder:\n\n```\ngit submodule update --init --recursive\n```\n\n\u003e Read more on how to work with `submodules` in the [zenode-contracts](https://github.com/zenodeapp/zenode-contracts) repository.\n\n### 1. Installation\n\nInstall all dependencies using a package manager of your choosing:\n\n```\nnpm install\n```\n\n```\nyarn install\n```\n\n### 2. Configure and run your (test) node\n\nAfter having installed all dependencies, use:\n\n```script\nnpx hardhat node\n```\n\n\u003e Make sure to do this in a separate terminal!\n\n\u003cbr\u003e\n\nThis will create a test environment where we can deploy our contract(s) to. By default, this repository is configured to Hardhat's local test node, but can be changed in the [hardhat.config.js](/hardhat.config.js) file. For more information on how to do this, see [Hardhat's documentation](https://hardhat.org/hardhat-runner/docs/config).\n\n### 3. Substitution Matrices (Intermezzo)\n\n\u003e `This step can be skipped if you've already deployed and populated a SubstitutionMatrices-contract.`\n\nOur alignment contracts depend on the SubstitutionMatrices-contract as it's required for calculating alignment scores. Thus, before continuing, we'll first have to deploy and populate a SubstitutionMatrices-contract.\n\n1. `cd` into the submodule's folder:\n\n   ```\n   cd submodules/substitution-matrices\n   ```\n\n2. Now, head over to the README.md file found in the [submodules/substitution-matrices](/submodules) folder and continue from step 1 to 5 (exclude step 2).\n\n   \u003e TIP: follow the TL;DR for a quick setup!\n\n   \u003e CAUTION: be sure to remain inside the submodule's folder while following the guideline!\n\n3. Once you've got the SubstitutionMatrices-contract set up, `cd` back into the `pairwise-alignments`' root folder:\n\n   ```\n   cd ../..\n   ```\n\n### 4. Pre-configuration\n\nBefore we can deploy any alignment algorithm, it's necessary to state which matrices' contract we'll use.\n\nTo do this, open the [zenode.config.js](zenode.config.js) file and add the `SubstitutionMatrices address` (from [3. Substitution Matrices](#3-substitution-matrices-intermezzo)) to `parameters._matricesAddress`:\n\n```javascript\n  contracts: {\n    needlemanWunsch: {\n      name: \"NeedlemanWunsch\",\n      address: \"\",\n      parameters: {\n        _matricesAddress: \"ADD_SUBSTITUTION_MATRICES_ADDRESS_HERE\",\n      },\n    },\n    ...\n  }\n```\n\n\u003e Repeat this step for any other algorithm you would like to deploy.\n\n### 5. Deployment\n\nNow that we've pre-configured [zenode.config.js](zenode.config.js), we can deploy our algorithm(s) using:\n\n\u003cb\u003eNeedleman-Wunsch\u003c/b\u003e\n\n```\nnpx hardhat run scripts/deployment/needlemanWunsch.js\n```\n\n\u003cb\u003eSmith-Waterman\u003c/b\u003e\n\n```\nnpx hardhat run scripts/deployment/smithWaterman.js\n```\n\n\u003e Only deploy the one(s) you pre-configured, see the [scripts/deployment](scripts/deployment) folder for all possible algorithms.\n\n### 6. Configuration\n\nNow head back to [zenode.config.js](zenode.config.js) and add the addresses for all the algorithms we deployed to the `contracts` object; so it knows which contracts it's supposed to [interact](#7-interaction) with.\n\n```javascript\n  contracts: {\n    needlemanWunsch: {\n      name: \"NeedlemanWunsch\",\n      address: \"ADD_NW_ALGORITHM_ADDRESS_HERE\",\n      ...\n    },\n    ...\n  },\n```\n\n\u003e Same as before; repeat for any other algorithm you've deployed.\n\n### 7. Interaction\n\nWe're all set!\n\n\u003cbr\u003e\n\nHere are a few Hardhat tasks (written in [hardhat.config.js](/hardhat.config.js)) to test our contracts with:\n\n\u003cul\u003e\n\u003cli\u003e\n\n\u003cb\u003eneedlemanWunsch\u003c/b\u003e\n\nExecutes the Needleman-Wunsch \u003ci\u003eglobal\u003c/i\u003e sequence alignment on the given string pair.\n\n- `input:` `--matrix string` `--a string` `--b string`\n\n- `input (optional):` `--gap int` \u003ci\u003e[default: \"-1\"]\u003c/i\u003e `--limit uint` \u003ci\u003e[default: \"0\"]\u003c/i\u003e\n\n- `output:` `struct AlignmentOutput` \u003ci\u003e--see [contracts/\\_PairwiseAlignment.sol](/contracts/_PairwiseAlignment.sol)\u003c/i\u003e\n\n\u003e `--gap` is the [gap penalty](https://en.wikipedia.org/wiki/Gap_penalty) (links to Wikipedia).\n\u003e\n\u003e `--limit \"0\"` will default to the limit configured in the contract itself (see `defaultLimit` in [contracts/\\_PairwiseAlignment.sol](/contracts/_PairwiseAlignment.sol)).\n\u003e\n\u003e Valid `MATRIX_ID`s depend on which matrices were inserted in the [Substitution Matrices](#3-substitution-matrices-intermezzo) phase.\n\n```\nnpx hardhat needlemanWunsch --matrix \"MATRIX_ID\" --a \"SEQ_A\" --b \"SEQ_B\" --gap \"-1\" --limit \"0\"\n```\n\n\u003c/li\u003e\n\n\u003cli\u003e\n\n\u003cb\u003esmithWaterman\u003c/b\u003e\n\nExecutes the Smith-Waterman \u003ci\u003elocal\u003c/i\u003e sequence alignment on the given string pair.\n\n- `input:` `--matrix string` `--a string` `--b string`\n\n- `input (optional):` `--gap int` \u003ci\u003e[default: \"-1\"]\u003c/i\u003e `--limit uint` \u003ci\u003e[default: \"0\"]\u003c/i\u003e\n\n- `output:` `struct AlignmentOutput` \u003ci\u003e--see [contracts/\\_PairwiseAlignment.sol](/contracts/_PairwiseAlignment.sol)\u003c/i\u003e\n\n\u003e see \u003cb\u003eneedlemanWunsch\u003c/b\u003e's annotations.\n\n```\nnpx hardhat smithWaterman --matrix \"MATRIX_ID\" --a \"SEQ_A\" --b \"SEQ_B\" --gap \"-1\" --limit \"0\"\n```\n\n\u003c/li\u003e\n\n\u003cli\u003e\n\n\u003cb\u003elinkNWToMatricesAddress\u003c/b\u003e\n\nThis changes the SubstitutionMatrices-address for the Needleman-Wunsch algorithm.\n\n- `input (optional):` `--address hex_address` \u003ci\u003e[default: [contracts.needlemanWunsch.parameters.\\_matricesAddress](zenode.config.js)]\u003c/i\u003e\n\n- `output:` `void`\n\n\u003e IMPORTANT: run this command every time the `alphabets` in the SubstitutionMatrices-contract get updated! \u003ci\u003e(rarely happens)\u003c/i\u003e\n\u003e\n\u003e \u003e Why?\n\u003e \u003e\n\u003e \u003e Every time a SubstitionMatrices-contract gets linked to an algorithm (which happens once during the [Deployment](#5-deployment) phase), all known `alphabets` get copied over to the algorithm's storage. So whenever an update to the alphabets inside of the matrices' contract occurs, all algorithms that were deployed before the change will have outdated alphabets; relinking the matrices' address remedies such inconsistencies.\n\n```\nnpx hardhat linkNWToMatricesAddress --address \"hex_address\"\n```\n\n\u003c/li\u003e\n\n\u003cli\u003e\n\n\u003cb\u003elinkSWToMatricesAddress\u003c/b\u003e\n\nThis changes the SubstitutionMatrices-address for the Smith-Waterman algorithm.\n\n- `input (optional):` `--address hex_address` \u003ci\u003e[default: [contracts.smithWaterman.parameters.\\_matricesAddress](zenode.config.js)]\u003c/i\u003e\n\n- `output:` `void`\n\n\u003e see \u003cb\u003elinkNWToMatricesAddress\u003c/b\u003e' annotations.\n\n```\nnpx hardhat linkSWToMatricesAddress --address \"hex_address\"\n```\n\n\u003c/li\u003e\n\u003c/ul\u003e\n\n## Appendix\n\n### A. [zenode.config.js](/zenode.config.js)\n\nThis is where most of the \u003ci\u003epersonalization\u003c/i\u003e for contract deployment takes place.\n\nIn the case of the `pairwise-alignments` repository this includes:\n\n- Configuring which SubstitutionMatrices-contract we'll link our algorithms to.\n- Configuring which contract we'll interact with in the [Interaction](#7-interaction) phase.\n- Expanding (or shrinking for that matter) the list of known pairwise alignment algorithms.\n\n## Credits\n\n- Hardhat's infrastructure! (https://hardhat.org/)\n- M (for requesting the creation of this project, sharing resourceful information and expertise; https://github.com/alpha-omega-labs)\n\n## Sources of inspiration\n\n- A tool by Greg Tucker-Kellogg demonstrating how pairwise alignment works (https://gtuckerkellogg.github.io/pairwise/demo/)\n- Another inspiring tool (http://rna.informatik.uni-freiburg.de/Teaching/index.jsp?toolName=Needleman-Wunsch)\n- Bioinformatics Course at the University of Melbourne by Vladimir Likić, Ph.D. (https://www.cs.sjsu.edu/~aid/cs152/NeedlemanWunsch.pdf)\n\n\u003c/br\u003e\n\n\u003cp align=\"right\"\u003e— ZEN\u003c/p\u003e\n\u003cp align=\"right\"\u003eCopyright (c) 2022 ZENODE\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzenodeapp%2Fpairwise-alignments","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzenodeapp%2Fpairwise-alignments","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzenodeapp%2Fpairwise-alignments/lists"}