[](https://www.python.org/)
[](https://github.com/HuttleyLab/MutationMotif/actions/workflows/testing_develop.yml)
[](https://coveralls.io/github/HuttleyLab/MutationMotif?branch=develop)
[](https://app.codacy.com/gh/HuttleyLab/MutationMotif/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade)
[](https://github.com/astral-sh/ruff)
# Mutation Motif
`mutation_motif` provides capabilities for analysis of point mutation counts data. It includes commands for preparing sequence data, log-linear analyses of the resulting counts and sequence logo style visualisations. Two different analysis approaches are supported:
1. log-linear analysis of neighbourhood base influences on mutation coupled with a sequence logo like representation of influences (illustrated above)
2. log-linear analysis of mutation spectra, the relative proportions of different mutation directions from a starting base. A logo-like visualisation of the latter is also supported.
The description of the models and applications of them are described in [Zhu, Neeman, Yap and Huttley 2017 Statistical methods for identifying sequence motifs affecting point mutations](https://www.ncbi.nlm.nih.gov/pubmed/27974498).
## Installation
You can just do a pip install
```
$ pip install mutation_motif
```
## The commands
The primary tool is installed as a command line executable, `mm`.
### Preparing data for analyses
#### The input sequence file format
At present, `mm` reads in a fasta formatted file where each sequence has identical length. The length is an odd number and where the mutation occurred at the middle base. `mm` assumes each sequence file contains sequences that experienced the same point mutation at this central position, e.g. `seqs-CtoT.fasta` contains only sequences that have experienced a C → T mutation at the central position **and the sequences have a C** at that position. The sequence flanking the mutated base is used to derive a paired "unmutated" reference. The details of this sampling are in Zhu et al.
Two data preparatory subcommands are available: `prep-nbr` and `prep-spectra`.
<details>
<summary>prep-nbr: converts aligned sequences to counts</summary>
`prep-nbr` converts a fasta formatted alignment of equal length sequences to the required counts table format.
<!-- [[[cog
import cog
from mutation_motif.cli import main
from click.testing import CliRunner
runner = CliRunner()
result = runner.invoke(main, ["prep-nbr"])
help = result.output.replace("Usage: main", "Usage: mm")
cog.out(
"```\n{}\n```".format(help)
)
]]] -->
```
Usage: mm prep-nbr [OPTIONS]
Export tab delimited counts table from alignment centred on SNP position.
Output file is written to the same path with just the file suffix changed from
fasta to txt.
Options:
-a, --align_path TEXT fasta aligned file centred on mutated
position. [required]
-o, --output_path TEXT Path to write data. [required]
-f, --flank_size INTEGER Number of bases per side to include.
[required]
--direction [AtoC|AtoG|AtoT|CtoA|CtoG|CtoT|GtoA|GtoC|GtoT|TtoA|TtoC|TtoG]
Mutation direction. [required]
-S, --seed TEXT Seed for random number generator (e.g. 17, or
2015-02-13). Defaults to system time.
-R, --randomise Randomises the observed data, observed and
reference counts distributions should match.
--step [1|2|3] Specifies a "frame" for selecting the random
base. [default: 1]
-D, --dry_run Do a dry run of the analysis without writing
output.
-F, --force_overwrite Overwrite existing files.
--help Show this message and exit.
```
<!-- [[[end]]] -->
</details>
<details>
<summary>prep-spectra: combining mutation counts from multiple files</summary>
This command combines the separate counts tables of `prep-nbr` into a larger table suitable for analyses by `ll-spectra`.
<!-- [[[cog
import cog
from mutation_motif.cli import main
from click.testing import CliRunner
runner = CliRunner()
result = runner.invoke(main, ["prep-spectra"])
help = result.output.replace("Usage: main", "Usage: mm")
cog.out(
"```\n{}\n```".format(help)
)
]]] -->
```
Usage: mm prep-spectra [OPTIONS]
export tab delimited combined counts table by appending the 12 mutation
direction tables, adding a new column ``direction``.
Options:
-c, --counts_pattern TEXT glob pattern uniquely identifying all 12 mutation
counts files.
-o, --output_path TEXT Path to write combined_counts data.
-s, --strand_symmetric produces table suitable for strand symmetry test.
-p, --split_dir TEXT path to write individual direction strand symmetric
tables.
-D, --dry_run Do a dry run of the analysis without writing
output.
-F, --force_overwrite Overwrite existing files.
--help Show this message and exit.
```
<!-- [[[end]]] -->
</details>
#### The output counts table format
The counts table format has a simple structure, illustrated by the following:
| count | pos0 | pos1 | pos2 | pos3 | mut |
|--------| ------| ------| ------| ------| ----- |
| 5663 | C | T | T | T | M |
| 2639 | G | C | A | T | M |
| 2425 | G | C | A | G | M |
| \... | \... | \... | \... | \... | \... |
| 882 | G | G | G | T | R |
| 6932 | A | G | T | G | R |
| 10550 | A | A | A | A | R |
The mutation status **must** be indicated by `R` (reference) and `M` (mutated). In this instance, the flank size is 2 and mutation was between `pos1` and `pos2`. Tables with this format are generated by `prep-nbr`.
### Statistical analyses of mutations
The log-linear analyses requires a counts table from the prep steps. The table contains counts for a specified flank size (maximum of 2 bases, assumed to be either side of the mutated base). It assumes the counts all reflect a specific mutation direction (e.g. AtoG) and that counts from a control distribution are also included.
Two subcommands are available: `ll-nbr` and `ll-spectra`.
<details>
<summary>ll-nbr: for detecting the influence of neighbouring bases on mutation</summary>
The first examines the influence of neighbouring bases up to fourth order interactions.
<!-- [[[cog
import cog
from mutation_motif.cli import main
from click.testing import CliRunner
runner = CliRunner()
result = runner.invoke(main, ["ll-nbr"])
help = result.output.replace("Usage: main", "Usage: mm")
cog.out(
"```\n{}\n```".format(help)
)
]]] -->
```
Usage: mm ll-nbr [OPTIONS]
log-linear analysis of neighbouring base influence on point mutation
Writes estimated statistics, figures and a run log to the specified directory
outpath.
See documentation for count table format requirements.
Options:
-1, --countsfile TEXT tab delimited file of counts.
-o, --outpath TEXT Directory path to write data.
-2, --countsfile2 TEXT second group motif counts file.
--first_order Consider only first order effects. Defaults to
considering up to 4th order interactions.
-s, --strand_symmetry single counts file but second group is strand.
-g, --group_label TEXT second group label.
-r, --group_ref TEXT reference group value for results presentation.
-v, --verbose Display more output.
-D, --dry_run Do a dry run of the analysis without writing output.
--help Show this message and exit.
```
<!-- [[[end]]] -->
</details>
<details>
<summary>ll-spectra: detect differences in mutation spectra between groups</summary>
Contrasts the mutations from specified starting bases between groups.
<!-- [[[cog
import cog
from mutation_motif.cli import main
from click.testing import CliRunner
runner = CliRunner()
result = runner.invoke(main, ["ll-spectra"])
help = result.output.replace("Usage: main", "Usage: mm")
cog.out(
"```\n{}\n```".format(help)
)
]]] -->
```
Usage: mm ll-spectra [OPTIONS]
log-linear analysis of mutation spectra between groups
Options:
-1, --countsfile TEXT tab delimited file of counts.
-o, --outpath TEXT Directory path to write data.
-2, --countsfile2 TEXT second group motif counts file.
-s, --strand_symmetry single counts file but second group is strand.
-F, --force_overwrite Overwrite existing files.
-D, --dry_run Do a dry run of the analysis without writing output.
-v, --verbose Display more output.
--help Show this message and exit.
```
<!-- [[[end]]] -->
</details>
Visualisation of mutation motifs, or mutation spectra, in a grid is provided by the `draw-`
subcommands.
## Evaluating the effect of neighbours on mutation
Sample data files are included as `tests/data/counts-CtoT.txt` and `tests/data/counts-CtoT-ss.txt` with the latter being appropriate for analysis of the occurrence of strand asymmetric neighbour effects.
The simple analysis is invoked as:
```
$ mm ll-nbr -1 path/to/tests/data/counts-CtoT.txt -o path/for/results/
```
This will write 11 files into the results directory. Files such as `1.pdf` and `2.pdf` are the mutation motifs for the first and second order effects from the log-linear models. Files ending in `.json` contain the raw data used to produce these figures and may be used for subsequent analyses, such as generating grids of mutation motifs. The summary files include the full log-linear modelling hierarchy. The `.log` files track the command used to generate these files, including
the input files and the settings used.
Testing for strand symmetry (or asymmetry) is done as:
```
$ mm ll-nbr -1 path/to/tests/data/counts-CtoT.txt -o path/for/results/ --strand_symmetry
```
Similar output to the above is generated. The difference here is that the reference group for display are bases on the `+` strand.
If comparing between groups, such as patient cohorts or chromosomal regions, then there are two separate counts files and the second count file is indicated using a `-2` command line option.
## Testing Full Spectra
Testing for strand symmetry requires the combined counts file, produced using the provided `all_counts` script. A sample such file is included as `tests/data/counts-combined.txt`. In this instance, a test of consistency in mutation spectra between strands is specified.
This analysis is run as:
```
$ mm ll-spectra -1 path/to/tests/data/counts-combined.txt -o another/path/for/results/ --strand_symmetry
```
## Drawing
`mm` provides support for drawing either spectra or neighbour mutation motif logos.
### Interpreting logo\'s
If the plot is derived from a group comparison, the relative entropy terms (which specify the stack height, letter size and orientation) are taken from the mutated class belonging to group 1 (which is the counts file path assigned to the `-1` option). For example, if you specified `-1 file_a.txt -2 file_b.txt`, then large upright letters in the display indicate an excess in the mutated class from `file_a.txt` relative to `file_b.txt`.
Raw data
{
"_id": null,
"home_page": null,
"name": "mutation_motif",
"maintainer": null,
"docs_url": null,
"requires_python": "<3.13,>3.9",
"maintainer_email": null,
"keywords": "biology, genomics, statistics, genetics, evolution, bioinformatics, mutation",
"author": null,
"author_email": "Gavin Huttley <Gavin.Huttley@anu.edu.au>",
"download_url": "https://files.pythonhosted.org/packages/7a/07/77016b485081ed0932cb00803d89de77333bd3f624d2b5cb015a2b14166c/mutation_motif-2024.9.22.tar.gz",
"platform": null,
"description": "[](https://www.python.org/)\n[](https://github.com/HuttleyLab/MutationMotif/actions/workflows/testing_develop.yml)\n[](https://coveralls.io/github/HuttleyLab/MutationMotif?branch=develop)\n[](https://app.codacy.com/gh/HuttleyLab/MutationMotif/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade)\n[](https://github.com/astral-sh/ruff)\n\n\n\n# Mutation Motif\n\n`mutation_motif` provides capabilities for analysis of point mutation counts data. It includes commands for preparing sequence data, log-linear analyses of the resulting counts and sequence logo style visualisations. Two different analysis approaches are supported:\n\n1. log-linear analysis of neighbourhood base influences on mutation coupled with a sequence logo like representation of influences (illustrated above)\n2. log-linear analysis of mutation spectra, the relative proportions of different mutation directions from a starting base. A logo-like visualisation of the latter is also supported.\n\nThe description of the models and applications of them are described in [Zhu, Neeman, Yap and Huttley 2017 Statistical methods for identifying sequence motifs affecting point mutations](https://www.ncbi.nlm.nih.gov/pubmed/27974498).\n\n## Installation\n\nYou can just do a pip install \n\n```\n$ pip install mutation_motif\n```\n\n## The commands\n\nThe primary tool is installed as a command line executable, `mm`.\n\n### Preparing data for analyses\n\n#### The input sequence file format\nAt present, `mm` reads in a fasta formatted file where each sequence has identical length. The length is an odd number and where the mutation occurred at the middle base. `mm` assumes each sequence file contains sequences that experienced the same point mutation at this central position, e.g. `seqs-CtoT.fasta` contains only sequences that have experienced a C \u2192 T mutation at the central position **and the sequences have a C** at that position. The sequence flanking the mutated base is used to derive a paired \"unmutated\" reference. The details of this sampling are in Zhu et al.\n\nTwo data preparatory subcommands are available: `prep-nbr` and `prep-spectra`. \n\n<details>\n<summary>prep-nbr: converts aligned sequences to counts</summary>\n\n`prep-nbr` converts a fasta formatted alignment of equal length sequences to the required counts table format.\n\n<!-- [[[cog\nimport cog\nfrom mutation_motif.cli import main\nfrom click.testing import CliRunner\nrunner = CliRunner()\nresult = runner.invoke(main, [\"prep-nbr\"])\nhelp = result.output.replace(\"Usage: main\", \"Usage: mm\")\ncog.out(\n \"```\\n{}\\n```\".format(help)\n)\n]]] -->\n```\nUsage: mm prep-nbr [OPTIONS]\n\n Export tab delimited counts table from alignment centred on SNP position.\n\n Output file is written to the same path with just the file suffix changed from\n fasta to txt.\n\nOptions:\n -a, --align_path TEXT fasta aligned file centred on mutated\n position. [required]\n -o, --output_path TEXT Path to write data. [required]\n -f, --flank_size INTEGER Number of bases per side to include.\n [required]\n --direction [AtoC|AtoG|AtoT|CtoA|CtoG|CtoT|GtoA|GtoC|GtoT|TtoA|TtoC|TtoG]\n Mutation direction. [required]\n -S, --seed TEXT Seed for random number generator (e.g. 17, or\n 2015-02-13). Defaults to system time.\n -R, --randomise Randomises the observed data, observed and\n reference counts distributions should match.\n --step [1|2|3] Specifies a \"frame\" for selecting the random\n base. [default: 1]\n -D, --dry_run Do a dry run of the analysis without writing\n output.\n -F, --force_overwrite Overwrite existing files.\n --help Show this message and exit.\n\n```\n<!-- [[[end]]] -->\n</details>\n\n<details>\n<summary>prep-spectra: combining mutation counts from multiple files</summary>\n\nThis command combines the separate counts tables of `prep-nbr` into a larger table suitable for analyses by `ll-spectra`.\n\n<!-- [[[cog\nimport cog\nfrom mutation_motif.cli import main\nfrom click.testing import CliRunner\nrunner = CliRunner()\nresult = runner.invoke(main, [\"prep-spectra\"])\nhelp = result.output.replace(\"Usage: main\", \"Usage: mm\")\ncog.out(\n \"```\\n{}\\n```\".format(help)\n)\n]]] -->\n```\nUsage: mm prep-spectra [OPTIONS]\n\n export tab delimited combined counts table by appending the 12 mutation\n direction tables, adding a new column ``direction``.\n\nOptions:\n -c, --counts_pattern TEXT glob pattern uniquely identifying all 12 mutation\n counts files.\n -o, --output_path TEXT Path to write combined_counts data.\n -s, --strand_symmetric produces table suitable for strand symmetry test.\n -p, --split_dir TEXT path to write individual direction strand symmetric\n tables.\n -D, --dry_run Do a dry run of the analysis without writing\n output.\n -F, --force_overwrite Overwrite existing files.\n --help Show this message and exit.\n\n```\n<!-- [[[end]]] -->\n</details>\n\n#### The output counts table format\n\nThe counts table format has a simple structure, illustrated by the following:\n\n | count | pos0 | pos1 | pos2 | pos3 | mut |\n |--------| ------| ------| ------| ------| ----- |\n | 5663 | C | T | T | T | M |\n | 2639 | G | C | A | T | M |\n | 2425 | G | C | A | G | M |\n | \\... | \\... | \\... | \\... | \\... | \\... |\n | 882 | G | G | G | T | R |\n | 6932 | A | G | T | G | R |\n | 10550 | A | A | A | A | R |\n\nThe mutation status **must** be indicated by `R` (reference) and `M` (mutated). In this instance, the flank size is 2 and mutation was between `pos1` and `pos2`. Tables with this format are generated by `prep-nbr`.\n\n### Statistical analyses of mutations\n\nThe log-linear analyses requires a counts table from the prep steps. The table contains counts for a specified flank size (maximum of 2 bases, assumed to be either side of the mutated base). It assumes the counts all reflect a specific mutation direction (e.g. AtoG) and that counts from a control distribution are also included.\n\nTwo subcommands are available: `ll-nbr` and `ll-spectra`. \n\n<details>\n<summary>ll-nbr: for detecting the influence of neighbouring bases on mutation</summary>\n\nThe first examines the influence of neighbouring bases up to fourth order interactions.\n\n<!-- [[[cog\nimport cog\nfrom mutation_motif.cli import main\nfrom click.testing import CliRunner\nrunner = CliRunner()\nresult = runner.invoke(main, [\"ll-nbr\"])\nhelp = result.output.replace(\"Usage: main\", \"Usage: mm\")\ncog.out(\n \"```\\n{}\\n```\".format(help)\n)\n]]] -->\n```\nUsage: mm ll-nbr [OPTIONS]\n\n log-linear analysis of neighbouring base influence on point mutation\n\n Writes estimated statistics, figures and a run log to the specified directory\n outpath.\n\n See documentation for count table format requirements.\n\nOptions:\n -1, --countsfile TEXT tab delimited file of counts.\n -o, --outpath TEXT Directory path to write data.\n -2, --countsfile2 TEXT second group motif counts file.\n --first_order Consider only first order effects. Defaults to\n considering up to 4th order interactions.\n -s, --strand_symmetry single counts file but second group is strand.\n -g, --group_label TEXT second group label.\n -r, --group_ref TEXT reference group value for results presentation.\n -v, --verbose Display more output.\n -D, --dry_run Do a dry run of the analysis without writing output.\n --help Show this message and exit.\n\n```\n<!-- [[[end]]] -->\n</details>\n\n<details>\n<summary>ll-spectra: detect differences in mutation spectra between groups</summary>\n\nContrasts the mutations from specified starting bases between groups.\n\n<!-- [[[cog\nimport cog\nfrom mutation_motif.cli import main\nfrom click.testing import CliRunner\nrunner = CliRunner()\nresult = runner.invoke(main, [\"ll-spectra\"])\nhelp = result.output.replace(\"Usage: main\", \"Usage: mm\")\ncog.out(\n \"```\\n{}\\n```\".format(help)\n)\n]]] -->\n```\nUsage: mm ll-spectra [OPTIONS]\n\n log-linear analysis of mutation spectra between groups\n\nOptions:\n -1, --countsfile TEXT tab delimited file of counts.\n -o, --outpath TEXT Directory path to write data.\n -2, --countsfile2 TEXT second group motif counts file.\n -s, --strand_symmetry single counts file but second group is strand.\n -F, --force_overwrite Overwrite existing files.\n -D, --dry_run Do a dry run of the analysis without writing output.\n -v, --verbose Display more output.\n --help Show this message and exit.\n\n```\n<!-- [[[end]]] -->\n</details>\n\nVisualisation of mutation motifs, or mutation spectra, in a grid is provided by the `draw-`\nsubcommands.\n\n## Evaluating the effect of neighbours on mutation\n\nSample data files are included as `tests/data/counts-CtoT.txt` and `tests/data/counts-CtoT-ss.txt` with the latter being appropriate for analysis of the occurrence of strand asymmetric neighbour effects.\n\nThe simple analysis is invoked as:\n```\n$ mm ll-nbr -1 path/to/tests/data/counts-CtoT.txt -o path/for/results/\n```\n\nThis will write 11 files into the results directory. Files such as `1.pdf` and `2.pdf` are the mutation motifs for the first and second order effects from the log-linear models. Files ending in `.json` contain the raw data used to produce these figures and may be used for subsequent analyses, such as generating grids of mutation motifs. The summary files include the full log-linear modelling hierarchy. The `.log` files track the command used to generate these files, including\nthe input files and the settings used.\n\nTesting for strand symmetry (or asymmetry) is done as:\n```\n$ mm ll-nbr -1 path/to/tests/data/counts-CtoT.txt -o path/for/results/ --strand_symmetry\n```\nSimilar output to the above is generated. The difference here is that the reference group for display are bases on the `+` strand.\n\nIf comparing between groups, such as patient cohorts or chromosomal regions, then there are two separate counts files and the second count file is indicated using a `-2` command line option.\n\n## Testing Full Spectra\n\nTesting for strand symmetry requires the combined counts file, produced using the provided `all_counts` script. A sample such file is included as `tests/data/counts-combined.txt`. In this instance, a test of consistency in mutation spectra between strands is specified.\n\nThis analysis is run as:\n```\n$ mm ll-spectra -1 path/to/tests/data/counts-combined.txt -o another/path/for/results/ --strand_symmetry\n```\n## Drawing\n\n`mm` provides support for drawing either spectra or neighbour mutation motif logos.\n\n### Interpreting logo\\'s\n\nIf the plot is derived from a group comparison, the relative entropy terms (which specify the stack height, letter size and orientation) are taken from the mutated class belonging to group 1 (which is the counts file path assigned to the `-1` option). For example, if you specified `-1 file_a.txt -2 file_b.txt`, then large upright letters in the display indicate an excess in the mutated class from `file_a.txt` relative to `file_b.txt`.\n",
"bugtrack_url": null,
"license": null,
"summary": "mutation_motif, software for naalyses of point mutations, see https://www.ncbi.nlm.nih.gov/pubmed/27974498",
"version": "2024.9.22",
"project_urls": {
"Bug Tracker": "https://github.com/HuttleyLab/MutationMotif/issues",
"Documentation": "https://github.com/HuttleyLab/MutationMotif",
"Source Code": "https://github.com/HuttleyLab/MutationMotif"
},
"split_keywords": [
"biology",
" genomics",
" statistics",
" genetics",
" evolution",
" bioinformatics",
" mutation"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "a75891b24bf952a903bff0fdc19bca77e44a47db4f145abbb5770297ac86946d",
"md5": "9d4dd3f7b33bf7c9c32f1c24db9e4d52",
"sha256": "076bdbf78d8a815aa1239a9f1996bf7544d0772f5d9cb1e800b5c9fa277b53e3"
},
"downloads": -1,
"filename": "mutation_motif-2024.9.22-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9d4dd3f7b33bf7c9c32f1c24db9e4d52",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.13,>3.9",
"size": 37513,
"upload_time": "2024-09-22T02:16:49",
"upload_time_iso_8601": "2024-09-22T02:16:49.074174Z",
"url": "https://files.pythonhosted.org/packages/a7/58/91b24bf952a903bff0fdc19bca77e44a47db4f145abbb5770297ac86946d/mutation_motif-2024.9.22-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "7a0777016b485081ed0932cb00803d89de77333bd3f624d2b5cb015a2b14166c",
"md5": "79cd63126126c101f12d1e36ab3f5876",
"sha256": "9c805b2405d52d2e9ab00bfc4f00093bece50ccc1157d3a046db111efae9375c"
},
"downloads": -1,
"filename": "mutation_motif-2024.9.22.tar.gz",
"has_sig": false,
"md5_digest": "79cd63126126c101f12d1e36ab3f5876",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.13,>3.9",
"size": 402377,
"upload_time": "2024-09-22T02:16:54",
"upload_time_iso_8601": "2024-09-22T02:16:54.005517Z",
"url": "https://files.pythonhosted.org/packages/7a/07/77016b485081ed0932cb00803d89de77333bd3f624d2b5cb015a2b14166c/mutation_motif-2024.9.22.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-22 02:16:54",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "HuttleyLab",
"github_project": "MutationMotif",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "mutation_motif"
}
JSON
