Skip to content

Commit

Permalink
Update usage notes in Markdown docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@tonyelewis
tonyelewis committed Jan 3, 2018
1 parent be57364 commit 0b73277
Show file tree
Hide file tree
Showing 3 changed files with 105 additions and 57 deletions.
20 changes: 15 additions & 5 deletions docs/tools/cath-map-clusters.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -34,9 +34,10 @@ Miscellaneous:
-v [ --version ] Output version information
Input:
--map-from-clustmemb-file <file> Map numbers from previous clusters specified in <file> to their equivalents in the working clusters where possible
--map-from-clustmemb-file <file> Map numbers from previous clusters specified in <file> to their equivalents in the working clusters where possible and
if all the cluster names in <file>are positive integers, renumber leftover new clusters from one plus the largest
or if not, rename with new_cmc_cluster_1, new_cmc_cluster_2, ...
(of, if unspecified, renumber all working clusters from 1 upwards)
Cluster names in this file must be positive integers
--read-batches-from-input Read batches of work from the input file with lines of format: `batch_id working_clust_memb_file prev_clust_memb_file` where:
* batch_id is a unique label for the batch (with no whitespace)
* prev_clust_memb_file is optional
Expand All @@ -45,18 +46,27 @@ Mapping:
--min_equiv_dom_ol <percent> (=60) Define domain equivalence as: sharing more than <percent>% of residues (over the longest domain)
(where <percent> must be ≥ 50)
--min_equiv_clust_ol <percent> (=60) Define cluster equivalence as: more than <percent>% of the map-from cluster's members having equivalents in the working cluster
(where <percent> must be ≥ 50)
[and them being equivalent to > 20% of the working cluster's entries and > 50% of those that have an equivalence]
(where <percent> must be ≥ 50%)
Output:
--append-batch-id <id> Append batch ID <id> as an extra column in the results output (equivalent to the first column in a --multi-batch-file input file)
--output-to-file <file> Write output to file <file> (or, if unspecified, to stdout)
--summarise-to-file <file> Print a summary of the renumbering to file <file>
--print-entry-results Output the entry (domain)-level mapping results
Detailed help:
--sorting-help Show the criteria for sorting unmapped clusters
The cluster membership file should contain lines like:
The input cluster-membership data should contain lines like:
cluster_name domain_id
...where domain_id is a sequence/protein name, which may optionally be suffixed with notation like '/100-199,350-399' to indicate the domain's segments. The suffixes should be present for all of the domain IDs or for none of them. Domains should be unique and non-overlapping.
...where domain_id is a sequence/protein name, optionally suffixed with the domain's segments in notation like '/100-199,350-399'. The suffixes should be present for all of the domain IDs or for none of them. Domains shouldn't overlap with others in the same cluster-membership data.
Input data doesn't have to be grouped by cluster.
NOTE: When mapping (ie using --map-from-clustmemb-file), the mapping algorithm treats the two cluster membership files differently - see --min_equiv_clust_ol description.
Please tell us your cath-tools bugs/suggestions : https://github.com/UCLOrengoGroup/cath-tools/issues/new
~~~~~
Expand Down
30 changes: 18 additions & 12 deletions docs/tools/cath-ssap.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -42,23 +42,23 @@ Usage
The current usage information is:

~~~~~no-highlight
Usage: cath-ssap [options] <protein1> <protein2>
Usage: cath-ssap [options] <protein1> <protein2>
Run a SSAP pairwise structural alignment
[algorithm devised by C A Orengo and W R Taylor, see --citation-help]
cath-ssap uses two types of structural comparison:
1. Fast SSAP: a quick secondary-structure based SSAP alignment
2. Slow SSAP: residue alignment only
If both structures have more than one SS element, a fast SSAP is run first. If the fast SSAP score isn't good, another fast SSAP is run with looser cutoffs. If the (best) fast SSAP score isn't good, a slow SSAP is run. Only the best of these scores is output. These behaviours can be configured using the parameters below.)
Miscellaneous:
-h [ --help ] Output help message
-v [ --version ] Output version information
Standard SSAP options:
--debug Output debugging information
If both structures have more than one SS element, a fast SSAP is run first. If the fast SSAP score isn't good, another fast SSAP is run with looser cutoffs. If the (best) fast SSAP score isn't good, a slow SSAP is run. Only the best of these scores is output. These behaviours can be configured using the parameters below.)
Miscellaneous:
-h [ --help ] Output help message
-v [ --version ] Output version information
Standard SSAP options:
--debug Output debugging information
-o [ --outfile ] <file> [DEPRECATED] Output scores to <file> rather than to stdout
--clique-file <file> Read clique from <file>
--domin-file <file> Read domin from <file>
Expand All @@ -67,8 +67,8 @@ Standard SSAP options:
--slow-ssap-only Don't try any fast SSAPs; only use slow SSAP
--local-ssap-score [DEPRECATED] Normalise the SSAP score over the length of the smallest domain rather than the largest
--all-scores [DEPRECATED] Output all SSAP scores from fast and slow runs, not just the highest
--prot-src-files <set> (=PDB_DSSP_SEC) Read the protein data from the set of files <set>, of available sets:
PDB_DSSP_SEC, WOLF_SEC
--prot-src-files <set> (=PDB) Read the protein data from the set of files <set>, of available sets:
PDB, PDB_DSSP, PDB_DSSP_SEC, WOLF_SEC
--supdir <dir> [DEPRECATED] Output a superposition to directory <dir>
--aligndir <dir> (=".") Write alignment to directory <dir>
--min-score-for-files <score> (=0) Only output alignment/superposition files if the SSAP score exceeds <score>
Expand All @@ -90,6 +90,12 @@ Conversion between a protein's name and its data files:
--wolf-suffix <suf> (=.wolf) Append the suffix <suf> to a protein's name to form its wolf filename
--sec-suffix <suf> (=.sec) Append the suffix <suf> to a protein's name to form its sec filename
Regions:
--align-regions <regions> Handle region(s) <regions> as the alignment part of the structure.
May be specified multiple times, in correspondence with the structures.
Format is: D[5inwB02]251-348:B,408-416A:B
(Put <regions> in quotes to prevent the square brackets confusing your shell ("No match"))
Detailed help:
--alignment-help Help on alignment format
--citation-help Help on SSAP authorship & how to cite it
Expand Down
112 changes: 72 additions & 40 deletions docs/tools/cath-superpose.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -78,61 +78,93 @@ Usage: cath-superpose alignment_source pdb_file_source [superposition_outputs]
Superpose protein structures using an existing alignment
Please specify:
* one alignment
* at most one superposition JSON or alignment (default: --do-the-ssaps)
* one method of reading PDB files (number to match the alignment)
PyMOL is started if no alignment or superposition output option is specified
Miscellaneous:
-h [ --help ] Output help message
-v [ --version ] Output version information
-h [ --help ] Output help message
-v [ --version ] Output version information
Input:
Alignment source:
--res-name-align Align residues by simply matching their names (numbers+insert)
(for multiple models of the same structure)
--fasta-aln-infile <file> Read FASTA alignment from file <file>
--ssap-aln-infile <file> Read SSAP alignment from file <file>
--cora-aln-infile <file> Read CORA alignment from file <file>
--ssap-scores-infile <file> Read SSAP scores from file <file>
Assumes all .list alignment files in same directory
--res-name-align Align residues by simply matching their names (numbers+insert)
(for multiple models of the same structure)
--fasta-aln-infile <file> Read FASTA alignment from file <file>
--ssap-aln-infile <file> Read SSAP alignment from file <file>
--cora-aln-infile <file> Read CORA alignment from file <file>
--ssap-scores-infile <file> Glue pairwise alignments together using SSAP scores in file <file>
Assumes all .list alignment files in same directory
--do-the-ssaps [=<dir>(="")] Do the required SSAPs in directory <dir>; use results as with --ssap-scores-infile
Use a suitable temp directory if none is specified
Alignment refining:
--align-refining <refn> (=NO) Apply <refn> refining to the alignment, one of available values:
NO - Don't refine the alignment
LIGHT - Refine any alignments with few entries; glue alignments one more entry at a time
HEAVY - Perform heavy (slow) refining on the alignment, including when gluing alignments together
This can change the method of gluing alignments under --ssap-scores-infile and --do-the-ssaps
Superposition source:
--json-sup-infile <file> Read superposition from file <file>
ID options:
--id arg Structure ids
--id arg Structure ids
PDB files source:
--pdb-infile <pdbfile> Read PDB from file <pdbfile> (may be specified multiple times)
--pdbs-from-stdin Read PDBs from stdin (separated by line: "END ")
--pdb-infile <pdbfile> Read PDB from file <pdbfile> (may be specified multiple times)
--pdbs-from-stdin Read PDBs from stdin (separated by line: "END ")
Regions:
--align-regions <regions> Handle region(s) <regions> as the alignment part of the structure.
May be specified multiple times, in correspondence with the structures.
Format is: D[5inwB02]251-348:B,408-416A:B
(Put <regions> in quotes to prevent the square brackets confusing your shell ("No match"))
Output:
Alignment output:
--aln-to-cath-aln-file arg [EXPERIMENTAL] Write the alignment to a CATH alignment file
--aln-to-cath-aln-stdout [EXPERIMENTAL] Print the alignment to stdout in CATH alignment format
--aln-to-fasta-file arg Write the alignment to a FASTA file
--aln-to-fasta-stdout Print the alignment to stdout in FASTA format
--aln-to-ssap-file arg Write the alignment to a SSAP file
--aln-to-ssap-stdout Print the alignment to stdout as SSAP
--aln-to-html-file arg Write the alignment to a HTML file
--aln-to-html-stdout Print the alignment to stdout as HTML
--aln-to-cath-aln-file arg [EXPERIMENTAL] Write the alignment to a CATH alignment file
--aln-to-cath-aln-stdout [EXPERIMENTAL] Print the alignment to stdout in CATH alignment format
--aln-to-fasta-file arg Write the alignment to a FASTA file
--aln-to-fasta-stdout Print the alignment to stdout in FASTA format
--aln-to-ssap-file arg Write the alignment to a SSAP file
--aln-to-ssap-stdout Print the alignment to stdout as SSAP
--aln-to-html-file arg Write the alignment to a HTML file
--aln-to-html-stdout Print the alignment to stdout as HTML
Superposition output:
--sup-to-pdb-file arg Write the superposed structures to a single PDB file arg, separated using faked chain codes
--sup-to-pdb-files-dir arg Write the superposed structures to separate PDB files in directory arg
--sup-to-stdout Print the superposed structures to stdout, separated using faked chain codes
--sup-to-pymol Start up PyMOL for viewing the superposition
--pymol-program arg (="pymol") Use arg as the PyMOL executable for viewing; may optionally include the full path
--sup-to-pymol-file arg Write the superposition to a PyMOL script arg
(Recommended filename extension: .pml)
--sup-to-json-file arg Write the superposition to JSON superposition file
(Recommended filename extension: .sup_json)
--sup-to-pdb-file arg Write the superposed structures to a single PDB file arg, separated using faked chain codes
--sup-to-pdb-files-dir arg Write the superposed structures to separate PDB files in directory arg
--sup-to-stdout Print the superposed structures to stdout, separated using faked chain codes
--sup-to-pymol Start up PyMOL for viewing the superposition
--pymol-program arg (="pymol") Use arg as the PyMOL executable for viewing; may optionally include the full path
--sup-to-pymol-file arg Write the superposition to a PyMOL script arg
(Recommended filename extension: .pml)
--sup-to-json-file arg Write the superposition to JSON superposition file
(Recommended filename extension: .sup_json)
Viewer (eg PyMOL, Jmol etc) options:
--viewer-colours <colrs> Use <colrs> to colour successive entries in the viewer
(format: colon-separated list of comma-separated triples of RGB values between 0 and 1)
(will wrap-around when it runs out of colours)
--gradient-colour-alignment Colour the length of the alignment with a rainbow gradient (blue -> red)
--show-scores-if-present Show the alignment scores
(use with gradient-colour-alignment)
--scores-to-equivs Show the alignment scores to equivalent positions, which increases relative scores where few entries are aligned
(use with --gradient-colour-alignment and --show-scores-if-present)
--normalise-scores When showing scores, normalise them to the highest score in the alignment
(use with --gradient-colour-alignment and --show-scores-if-present)
--viewer-colours <colrs> Use <colrs> to colour successive entries in the viewer
(format: colon-separated list of comma-separated triples of RGB values between 0 and 1)
(will wrap-around when it runs out of colours)
--gradient-colour-alignment Colour the length of the alignment with a rainbow gradient (blue -> red)
--show-scores-if-present Show the alignment scores
(use with gradient-colour-alignment)
--scores-to-equivs Show the alignment scores to equivalent positions, which increases relative scores where few entries are aligned
(use with --gradient-colour-alignment and --show-scores-if-present)
--normalise-scores When showing scores, normalise them to the highest score in the alignment
(use with --gradient-colour-alignment and --show-scores-if-present)
Superposition content:
--regions-context <context> (=alone) Show the alignment regions in the context <context>, one of available options:
alone - alone
in_chain - within the chain(s) in which the regions appear
in_pdb - within the PDB in which the regions appear
--show-dna-within-dist <dist> (=4) Show DNA within <dist>Å of the alignment regions
--show-organic-within-dist <dist> (=10) Show organic molecules within <dist>Å of the alignment regions
Usage examples:
* cath-superpose --ssap-aln-infile 1cukA1bvsA.list --pdb-infile $PDBDIR/1cukA --pdb-infile $PDBDIR/1bvsA --sup-to-pymol
Expand Down

0 comments on commit 0b73277

Please sign in to comment.