Map module — FAN-C 0.9.1-beta documentation

# Map module

This module performs iterative mapping of reads in FASTQ files to a reference genome.

The main function is `iterative_mapping()`, which requires an input FASTQ file, an output SAM file, and a suitable mapper. Mapper options are `Bowtie2Mapper` and `BwaMapper` for the time being, but by subclassing `Mapper` a user can easily write their own mapper implementations that can fully leverage the iterative mapping capabilities of FAN-C. Take a look at the code of `Bowtie2Mapper` for an example.

Example usage:

    import fanc
    mapper = fanc.BwaMapper("bwa-index/hg19_chr18_19.fa", min_quality=3)
    fanc.iterative_mapping("SRR4271982_chr18_19_1.fastq.gzip", "SRR4271982_chr18_19_1.bam",
                           mapper, threads=4, restriction_enzyme="HindIII")

class `fanc.map.` `Bowtie2Mapper`(bowtie2_index, min_quality=30, additional_arguments=(), threads=1, _bowtie2_path='bowtie2', **kwargs)

  Bases: `fanc.map.Mapper`

  Bowtie2 Mapper for aligning reads against a reference genome.

  Implements `Mapper` by calling the command line “bowtie2” program.

  `bowtie2_index`

    Path to the bowtie2 index of the reference genome of choice.

  `min_quality`

    Minimum MAPQ of an alignment so that it won’t be resubmitted in iterative mapping.

  `additional_arguments`

    Arguments passed to the “bowtie2” command in addition to -x, -U, –no-unal, –threads, and -S.

  `threads`

    Number of threads for this mapping process.

  `close`()

    Final operations after mapping completes.

  `map`(input_file, output_folder=None)

    Map reads in the given FASTQ file using `_map()` implementation.

    Will internally map the FASTQ reads to a SAM file in a temporary folder (use output_folder to choose a specific folder), split the SAM output into (i) valid alignments according to `_resubmit()` and (ii) invalid alignments that get caught by the resubmission filter. A FASTQ file will be constructed from the invalid alignments, extending the reads by a given step size, which can then be used to iteratively repeat the mapping process until a valid alignment is found or the full length of the read has been restored.

    Parameters

      - input_file – Path to FASTQ file

      - output_folder – (optional) path to temporary folder for SAM output

    Returns

      tuple, path to valid SAM alignments, path to resubmission FASTQ

  `resubmit`(sam_fields)

    Determine if an alignment should be resubmitted.

    Filters unmappable reads by default. Additional criteria can be implemented using the `_resubmit()` method.

    Parameters

      sam_fields – The individual fields in a SAM line (split by tab)

    Returns

      True if read should be extended and aligned to the reference again, False if the read passes the validity criteria.

class `fanc.map.` `BwaMapper`(bwa_index, min_quality=0, additional_arguments=(), threads=1, algorithm='mem', memory_map=False, _bwa_path='bwa')

  Bases: `fanc.map.Mapper`

  BWA Mapper for aligning reads against a reference genome.

  Implements `Mapper` by calling the command line “bwa” program.

  `bwa_index`

    Path to the BWA index of the reference genome of choice.

  `min_quality`

    Minimum MAPQ of an alignment so that it won’t be resubmitted in iterative mapping.

  `additional_arguments`

    Arguments passed to the “bowtie2” command in addition to -t and -o.

  `threads`

    Number of threads for this mapping process.

  `algorithm`

    BWA algorithm to use for mapping. Uses “mem” by default. See http://bio-bwa.sourceforge.net/bwa.shtml for other options.

  `close`()

    Final operations after mapping completes.

  `map`(input_file, output_folder=None)

    Map reads in the given FASTQ file using `_map()` implementation.

    Will internally map the FASTQ reads to a SAM file in a temporary folder (use output_folder to choose a specific folder), split the SAM output into (i) valid alignments according to `_resubmit()` and (ii) invalid alignments that get caught by the resubmission filter. A FASTQ file will be constructed from the invalid alignments, extending the reads by a given step size, which can then be used to iteratively repeat the mapping process until a valid alignment is found or the full length of the read has been restored.

    Parameters

      - input_file – Path to FASTQ file

      - output_folder – (optional) path to temporary folder for SAM output

    Returns

      tuple, path to valid SAM alignments, path to resubmission FASTQ

  `resubmit`(sam_fields)

    Determine if an alignment should be resubmitted.

    Filters unmappable reads by default. Additional criteria can be implemented using the `_resubmit()` method.

    Parameters

      sam_fields – The individual fields in a SAM line (split by tab)

    Returns

      True if read should be extended and aligned to the reference again, False if the read passes the validity criteria.

class `fanc.map.` `SimpleBowtie2Mapper`(bowtie2_index, additional_arguments=(), threads=1, _bowtie2_path='bowtie2')

  Bases: `fanc.map.Bowtie2Mapper`

  Bowtie2 Mapper for aligning reads against a reference genome without resubmission.

  Implements `Mapper` by calling the command line “bowtie2” program. Does not resubmit reads under any circumstance.

  `bowtie2_index`

    Path to the bowtie2 index of the reference genome of choice.

  `additional_arguments`

    Arguments passed to the “bowtie2” command in addition to -x, -U, –no-unal, –threads, and -S.

  `threads`

    Number of threads for this mapping process.

  `close`()

    Final operations after mapping completes.

  `map`(input_file, output_folder=None)

    Map reads in the given FASTQ file using `_map()` implementation.

    Will internally map the FASTQ reads to a SAM file in a temporary folder (use output_folder to choose a specific folder), split the SAM output into (i) valid alignments according to `_resubmit()` and (ii) invalid alignments that get caught by the resubmission filter. A FASTQ file will be constructed from the invalid alignments, extending the reads by a given step size, which can then be used to iteratively repeat the mapping process until a valid alignment is found or the full length of the read has been restored.

    Parameters

      - input_file – Path to FASTQ file

      - output_folder – (optional) path to temporary folder for SAM output

    Returns

      tuple, path to valid SAM alignments, path to resubmission FASTQ

  `resubmit`(sam_fields)

    Determine if an alignment should be resubmitted.

    Filters unmappable reads by default. Additional criteria can be implemented using the `_resubmit()` method.

    Parameters

      sam_fields – The individual fields in a SAM line (split by tab)

    Returns

      True if read should be extended and aligned to the reference again, False if the read passes the validity criteria.

class `fanc.map.` `SimpleBwaMapper`(bwa_index, additional_arguments=(), threads=1, memory_map=False, _bwa_path='bwa')

  Bases: `fanc.map.BwaMapper`

  BWA Mapper for aligning reads against a reference genome without resubmission.

  Implements `Mapper` by calling the command line “bwa” program. Does not resubmit reads under any circumstance, i.e. does not perform iterative mapping.

  `bwa_index`

    Path to the BWA index of the reference genome of choice.

  `min_quality`

    Minimum MAPQ of an alignment so that it won’t be resubmitted in iterative mapping.

  `additional_arguments`

    Arguments passed to the “bowtie2” command in addition to -t and -o.

  `threads`

    Number of threads for this mapping process.

  `algorithm`

    BWA algorithm to use for mapping. Uses “mem” by default. See http://bio-bwa.sourceforge.net/bwa.shtml for other options.

  `close`()

    Final operations after mapping completes.

  `map`(input_file, output_folder=None)

    Map reads in the given FASTQ file using `_map()` implementation.

    Will internally map the FASTQ reads to a SAM file in a temporary folder (use output_folder to choose a specific folder), split the SAM output into (i) valid alignments according to `_resubmit()` and (ii) invalid alignments that get caught by the resubmission filter. A FASTQ file will be constructed from the invalid alignments, extending the reads by a given step size, which can then be used to iteratively repeat the mapping process until a valid alignment is found or the full length of the read has been restored.

    Parameters

      - input_file – Path to FASTQ file

      - output_folder – (optional) path to temporary folder for SAM output

    Returns

      tuple, path to valid SAM alignments, path to resubmission FASTQ

  `resubmit`(sam_fields)

    Determine if an alignment should be resubmitted.

    Filters unmappable reads by default. Additional criteria can be implemented using the `_resubmit()` method.

    Parameters

      sam_fields – The individual fields in a SAM line (split by tab)

    Returns

      True if read should be extended and aligned to the reference again, False if the read passes the validity criteria.

`fanc.map.` `iterative_mapping`(fastq_file, sam_file, mapper, tmp_folder=None, threads=1, min_size=25, step_size=5, batch_size=200000, trim_front=False, restriction_enzyme=None)

  Iteratively map sequencing reads using the provided mapper.

  Will attempt to align a read using mapper. If unsuccessful, will truncate the read by step_size and attempt to align again. This is repeated until a successful alignment is found or the read gets truncated below min_size.

  Parameters

    - fastq_file – An input FASTQ file path with reds to align

    - sam_file – An output file path for sequencing results. If it ends with ‘.bam’ will compress output in bam format.

    - mapper – An instance of `Mapper`, e.g. `Bowtie2Mapper`. Override `Mapper` for creating your own custom mappers.

    - tmp_folder – A temporary folder for outputting subsets of FASTQ files

    - threads – Number of mapper threads to use in parallel.

    - min_size – Minimum length of read for which an alignment is attempted.

    - step_size – Number of base pairs by which to truncate read.

    - batch_size – Maximum number of reads processed in one batch

    - trim_front – Trim bases from front of read instead of back

    - restriction_enzyme – If provided, will calculate the expected ligation junction between reads and split reads accordingly. Both ends will be attempted to map. Can be the name of a restriction enzyme or a restriction pattern (e.g. A^AGCT_T)