From 43c3bcbd71231b67348a0504d18f45c0dd9ae3fd Mon Sep 17 00:00:00 2001 From: Luis Pedro Coelho Date: Tue, 25 Jun 2019 17:58:54 -0400 Subject: [PATCH] DOC Document backwards compatibility fixes --- docs/sources/backwards.md | 35 +++++++++++++++++++++++++++++++++++ docs/sources/conf.py | 10 +++++----- docs/sources/index.rst | 17 +++++------------ 3 files changed, 45 insertions(+), 17 deletions(-) create mode 100644 docs/sources/backwards.md diff --git a/docs/sources/backwards.md b/docs/sources/backwards.md new file mode 100644 index 00000000..a6f45bd6 --- /dev/null +++ b/docs/sources/backwards.md @@ -0,0 +1,35 @@ +# List of backwards compatibility fixes + +As NGLess uses a version declaration string at the top of script means that +NGLess can change its behaviour depending on the version used in the script. + +## < NGLess 1.1 + +- The way that CIGAR sequence lengths are computed has changed to match + samtools. This implies that the computation of `min_match_size` and + `min_identity_pc` have slightly changed. + +## < NGLess 0.8 + +- Select changes how a corner case is handled. + +## < NGLess 0.6 + +- The `count` function now defaults to `include_minus1` being true. + +## < NGLess 0.5 + +- The `preprocess` function now modifies its argument. Older code using + +```python +preprocess(input) using |r|: + ... +``` +is automatically treated as: + + +```python +input = preprocess(input) using |r|: + ... +``` + diff --git a/docs/sources/conf.py b/docs/sources/conf.py index 5cc95d09..84b3be8b 100644 --- a/docs/sources/conf.py +++ b/docs/sources/conf.py @@ -45,8 +45,8 @@ master_doc = 'index' # General information about the project. -project = u'ngless' -copyright = u'2013-2018, NGLess Authors' +project = u'NGLess' +copyright = u'2013-2019, NGLess Authors' # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the @@ -234,7 +234,7 @@ # One entry per manual page. List of tuples # (source start file, name, description, authors, manual section). man_pages = [ - ('index', 'ngless', u'ngless Documentation', + ('index', 'NGLess', u'NGLess Documentation', [u'NGLess Authors'], 1) ] @@ -248,8 +248,8 @@ # (source start file, target name, title, author, # dir menu entry, description, category) texinfo_documents = [ - ('index', 'ngless', u'ngless Documentation', - u'NGLess Authors', 'ngless', 'One line description of project.', + ('index', 'NGLess', u'NGLess Documentation', + u'NGLess Authors', 'NGLess', 'One line description of project.', 'Miscellaneous'), ] diff --git a/docs/sources/index.rst b/docs/sources/index.rst index 82f7a533..0da8c531 100644 --- a/docs/sources/index.rst +++ b/docs/sources/index.rst @@ -18,14 +18,6 @@ For questions, you can also use the `ngless mailing list Microbiome 2019 7:84; `https://doi.org/10.1186/s40168-019-0684-8 `__ - previously also available as a pre-print at: - - *NG-meta-profiler: fast processing of metagenomes using NGLess, a - domain-specific language* by Luis Pedro Coelho, Renato Alves, Paulo - Monteiro, Jaime Huerta-Cepas, Ana Teresa Freitas, Peer Bork - - bioRxiv 367755; - `https://doi.org/10.1101/367755 `__ - NG-meta-profiler ---------------- @@ -39,7 +31,7 @@ NGLess NGLess is best illustrated by an example:: - ngless "0.11" + ngless "1.0" input = paired('ctrl1.fq', 'ctrl2.fq', singles='ctrl-singles.fq') input = preprocess(input) using |read|: read = read[5:] @@ -112,7 +104,7 @@ This is equivalent to the full script: :: - ngless "0.11" # <- version declaration, optional on the command line + ngless "1.0" # <- version declaration, optional on the command line samcontents = samfile("file.sam") # <- load a SAM/BAM file reads = as_reads(samcontents) # <- just get the reads (w quality scores) write(reads, ofname=STDOUT) # <- write them to STDOUT (default format: FASTQ) @@ -122,7 +114,7 @@ out a single FQ file. Otherwise, you can always do: :: - ngless "0.11" + ngless "1.0" write(as_read(samfile("file.sam")), ofile="output.fq") @@ -144,7 +136,7 @@ This is equivalent to the full script: :: - ngless "0.11" # <- version declaration, optional on the command line + ngless "1.0" # <- version declaration, optional on the command line samcontents = samfile("file.sam") # <- load a SAM/BAM file samcontents = select(samcontents, keep_if=[{mapped}]) # <- select only *mapped* reads reads = as_reads(samcontents) # <- just get the reads (w quality scores) @@ -188,6 +180,7 @@ Authors install ng-meta-profiler whatsnew + backwards tutorial-ocean-metagenomics tutorial-assembly-gp tutorial-gut-metagenomics