New upstream version 0.5.3.1

comment: false

coverage:

  status:

    patch: false

sudo: false

python:

    - 'nightly'

    - '3.6'

    - '3.5'

    - '3.4'

    - '3.3'

    - pip wheel -f wheelhouse coverage biopython cython pysam pyvcf || true

    - pip install -f wheelhouse biopython cython pysam pyfasta coverage pyvcf || true

    - python setup.py install

    - if [ ! -f samtools-1.2 ]; then wget -q -O - https://github.com/samtools/samtools/releases/download/1.2/samtools-1.2.tar.bz2 | tar -xjv; fi

    - if [ ! -f samtools-1.2 ]; then curl -sL https://github.com/samtools/samtools/releases/download/1.2/samtools-1.2.tar.bz2 | tar -xjv; fi

    - cd samtools-1.2

    - make

    - export PATH=$PATH:$PWD

    - cd ..

    - if [ ! -f htslib-1.4 ]; then curl -sL https://github.com/samtools/htslib/releases/download/1.4/htslib-1.4.tar.bz2 | tar -xjv; fi

    - cd htslib-1.4

    - make

    - export PATH=$PATH:$PWD

    - cd ..

before_script:

    - /usr/local/bin/pip install --user biopython

    - /usr/bin/python tests/data/download_gene_fasta.py

    - if [ $(python --version) -gt 2.6 ]; then env pip install biopython; fi

    - env python tests/data/download_gene_fasta.py

script: nosetests --with-coverage --cover-package=pyfaidx

deploy:

  provider: pypi

    secure: MbSaeuitkVTZqxa0PJ3RcR1aMf+B/sMbcx2sWOo9xfLlRFDFpYWJZ0EfXWEhrVu2YWXpBsasgunTDWSi0jNcZMH92MzOC+UTVYr45LO5sy6hm4iSiAgm/DPgYWdjP0SFKr7eL/HWPS+gHvgkXL1upleX21O358bxaezoasuKFvs=

  on:

    all_branches: true

    python: 2.6

    python: 2.7

    tags: true

    repo: mdshw5/pyfaidx

matrix:

  allow_failures:

    - python: 'nightly'

    - python: 'pypy3'

    - python: 'pypy'

  fast_finish: true

cache:

    directories:

        - tests/data

        - samtools-1.2

        - htslib-1.4

        - wheelhouse

after_success:

    - bash <(curl -s https://codecov.io/bash)

# Contributor Covenant Code of Conduct

## Our Pledge

In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation.

## Our Standards

Examples of behavior that contributes to creating a positive environment include:

* Using welcoming and inclusive language

* Being respectful of differing viewpoints and experiences

* Gracefully accepting constructive criticism

* Focusing on what is best for the community

* Showing empathy towards other community members

Examples of unacceptable behavior by participants include:

* The use of sexualized language or imagery and unwelcome sexual attention or advances

* Trolling, insulting/derogatory comments, and personal or political attacks

* Public or private harassment

* Publishing others' private information, such as a physical or electronic address, without explicit permission

* Other conduct which could reasonably be considered inappropriate in a professional setting

## Our Responsibilities

Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior.

Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful.

## Scope

This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers.

## Enforcement

Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at mdshw5@gmail.com. The project team will review and investigate all complaints, and will respond in a way that it deems appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately.

Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership.

## Attribution

This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, available at [http://contributor-covenant.org/version/1/4][version]

[homepage]: http://contributor-covenant.org

[version]: http://contributor-covenant.org/version/1/4/

|Travis| |PyPI| |Landscape| |Coverage| |Depsy| |Appveyor| |Flattr|

|Travis| |PyPI| |Landscape| |Coverage| |Depsy| |Appveyor|

Description

-----------

    python setup.py install

If using ``pip install --user`` make sure to add ``/home/$(whoami)/.local/bin`` to your ``$PATH`` if you want to run the ``faidx`` script.

Usage

-----

    >>> genes['NM_001282543.1'][200:230].end

    230

    >>> genes['NM_001282543.1'][200:230].longname

    >>> genes['NM_001282543.1'][200:230].fancy_name

    'NM_001282543.1:201-230'

    >>> len(genes['NM_001282543.1'])

- Slicing start and end coordinates are 0-based, just like Python sequences.  

Sequence can be buffered in memory using a read-ahead buffer

for fast sequential access:

.. code:: python

    >>> from timeit import timeit

    >>> fetch = "genes['NM_001282543.1'][200:230]"

    >>> read_ahead = "import pyfaidx; genes = pyfaidx.Fasta('tests/data/genes.fasta', read_ahead=10000)"

    >>> no_read_ahead = "import pyfaidx; genes = pyfaidx.Fasta('tests/data/genes.fasta')"

    >>> string_slicing = "genes = {}; genes['NM_001282543.1'] = 'N'*10000"

    >>> timeit(fetch, no_read_ahead, number=10000)

    0.2204863309962093

    >>> timeit(fetch, read_ahead, number=10000)

    0.1121859749982832

    >>> timeit(fetch, string_slicing, number=10000)

    0.0033553699977346696

Read-ahead buffering can reduce runtime by 1/2 for sequential accesses to buffered regions.

Complements and reverse complements just like DNA

.. code:: python

    >NM_001282543.1 (complement):230-201

    CATCCGGTTCCATGGCGGGCGCGGAACGAG

``Fasta`` objects can also be accessed using method calls:

.. code:: python

    >>> genes.get_seq('NM_001282543.1', 201, 210)

    >NM_001282543.1:201-210

    CTCGTTCCGC

    >>> genes.get_seq('NM_001282543.1', 201, 210, rc=True)

    >NM_001282543.1 (complement):210-201

    GCGGAACGAG

Spliced sequences can be retrieved from a list of [start, end] coordinates:

**TODO** update this section

.. code:: python

    # new in v0.5.1

    segments = [[1, 10], [50, 70]]

    >>> genes.get_spliced_seq('NM_001282543.1', segments)

    >gi|543583786|ref|NM_001282543.1|:1-70

    CCCCGCCCCTGGTTTCGAGTCGCTGGCCTGC

.. _keyfn:

Custom key functions provide cleaner access:

.. code:: python

    >NR_104212:1-10

    CCCCGCCCCT

You can specify a character to split names on, which will generate additional entries:

.. code:: python

    >>> from pyfaidx import Fasta

    >>> genes = Fasta('tests/data/genes.fasta', split_char='.', duplicate_action="first") # default duplicate_action="stop"

    >>> genes.keys()

    dict_keys(['.1', 'NR_104212', 'NM_001282543', 'XM_005249644', 'XM_005249645', 'NR_104216', 'XM_005249643', 'NR_104215', 'KF435150', 'AB821309', 'NM_001282549', 'XR_241081', 'KF435149', 'XR_241079', 'NM_000465', 'XM_005265508', 'XR_241080', 'XM_005249642', 'NM_001282545', 'XM_005265507', 'NM_001282548'])

If your `key_function` or `split_char` generates duplicate entries, you can choose what action to take:

.. code:: python

    # new in v0.4.9

    >>> genes = Fasta('tests/data/genes.fasta', split_char="|", duplicate_action="longest")

    >>> genes.keys()

    dict_keys(['gi', '563317589', 'dbj', 'AB821309.1', '', '557361099', 'gb', 'KF435150.1', '557361097', 'KF435149.1', '543583796', 'ref', 'NR_104216.1', '543583795', 'NR_104215.1', '543583794', 'NR_104212.1', '543583788', 'NM_001282545.1', '543583786', 'NM_001282543.1', '543583785', 'NM_000465.3', '543583740', 'NM_001282549.1', '543583738', 'NM_001282548.1', '530384540', 'XM_005249645.1', '530384538', 'XM_005249644.1', '530384536', 'XM_005249643.1', '530384534', 'XM_005249642.1', '530373237','XM_005265508.1', '530373235', 'XM_005265507.1', '530364726', 'XR_241081.1', '530364725', 'XR_241080.1', '530364724', 'XR_241079.1'])

Filter functions (returning True) limit the index:

.. code:: python

    gi|557361097|gb|KF435149.1| Homo sapiens MDM4 protein variant G (MDM4) mRNA, complete cds

    ...

    # new in v0.4.9

    >>> from pyfaidx import Fasta

    >>> genes = Fasta('tests/data/genes.fasta', read_long_names=True)

    >>> for record in genes:

    ...   print(record.name)

    ...

    gi|563317589|dbj|AB821309.1| Homo sapiens FGFR2-AHCYL1 mRNA for FGFR2-AHCYL1 fusion kinase protein, complete cds

    gi|557361099|gb|KF435150.1| Homo sapiens MDM4 protein variant Y (MDM4) mRNA, complete cds, alternatively spliced

    gi|557361097|gb|KF435149.1| Homo sapiens MDM4 protein variant G (MDM4) mRNA, complete cds

Sequence can be buffered in memory using a read-ahead buffer

for fast sequential access:

.. code:: python

    >>> from timeit import timeit

    >>> fetch = "genes['NM_001282543.1'][200:230]"

    >>> read_ahead = "import pyfaidx; genes = pyfaidx.Fasta('tests/data/genes.fasta', read_ahead=10000)"

    >>> no_read_ahead = "import pyfaidx; genes = pyfaidx.Fasta('tests/data/genes.fasta')"

    >>> string_slicing = "genes = {}; genes['NM_001282543.1'] = 'N'*10000"

    >>> timeit(fetch, no_read_ahead, number=10000)

    0.2204863309962093

    >>> timeit(fetch, read_ahead, number=10000)

    0.1121859749982832

    >>> timeit(fetch, string_slicing, number=10000)

    0.0033553699977346696

Read-ahead buffering can reduce runtime by 1/2 for sequential accesses to buffered regions.

.. role:: red

If you want to modify the contents of your FASTA file in-place, you can use the `mutable` argument.

                            default base for missing positions and masking. default: N

      -d DELIMITER, --delimiter DELIMITER

                            delimiter for splitting names to multiple values (duplicate names will be discarded). default: None

      -e HEADER_FUNCTION, --header-function HEADER_FUNCTION

                            python function to modify header lines e.g: "lambda x: x.split("|")[0]". default: lambda x: x.split()[0]

      -u {stop,first,last,longest,shortest}, --duplicates-action {stop,first,last,longest,shortest}

                            entry to take when duplicate sequence names are encountered. default: stop

      -g REGEX, --regex REGEX

                            selected sequences are those matching regular expression. default: .*

      -v, --invert-match    selected sequences are those not matching 'regions' argument. default: False

      -m, --mask-with-default-seq

                            mask the FASTA file using --default-seq default: False

      -M, --mask-by-case    mask the FASTA file by changing to lowercase. default: False

      -e HEADER_FUNCTION, --header-function HEADER_FUNCTION

                            python function to modify header lines e.g: "lambda x: x.split("|")[0]". default: None

      --no-rebuild          do not rebuild the .fai index even if it is out of date. default: False

      --version             print pyfaidx version number

    AGCTTCCCTGTGGTTTCCCGAGGCTTCCTTGCTTCCCGCTCTGCGAGGAGCCTTTCATCCGAAGGCGGGA

    .......

    $ faidx --size-range 5500,6000 -i chromsizes tests/data/genes.fasta

    NM_000465.3	5523

    $ faidx -M --bed regions.bed tests/data/genes.fasta

    ### Modifies tests/data/genes.fasta by masking regions using lowercase characters ###

    $ faidx -e "lambda x: x.split('.')[0]" tests/data/genes.fasta -i bed

    AB821309	1	3510

    KF435150	1	481

    KF435149	1	642

    NR_104216	1	4573

    NR_104215	1	5317

    .......

Similar syntax as ``samtools faidx``

   where "filename.fa" is the original FASTA file.

-  Start and end coordinates are 1-based.

Support for compressed FASTA

----------------------------

``pyfaidx`` can create and read ``.fai`` indices for FASTA files that have

been compressed using the `bgzip <http://www.htslib.org/doc/tabix.html>`_

tool from `samtools <http://www.htslib.org/>`_. ``bgzip`` writes compressed

data in a ``BGZF`` format. ``BGZF`` is ``gzip`` compatible, consisting of

multiple concatenated ``gzip`` blocks, each with an additional ``gzip``

header making it possible to build an index for rapid random access. I.e.,

files compressed with ``bgzip`` are valid ``gzip`` and so can be read by

``gunzip``.  See `this description

<http://pydoc.net/Python/biopython/1.66/Bio.bgzf/>`_ for more details on

``bgzip``.

Changelog

---------

Contributing

------------

Create a new Pull Request with one feauture. If you add a new feature, please

Create a new Pull Request with one feature. If you add a new feature, please

create also the relevant test.

To get test running on your machine:

.. |Appveyor| image:: https://ci.appveyor.com/api/projects/status/80ihlw30a003596w?svg=true

   :target: https://ci.appveyor.com/project/mdshw5/pyfaidx

.. |Flattr| image:: http://button.flattr.com/flattr-badge-large.png

   :target: https://flattr.com/submit/auto?fid=po00kq&url=https%3A%2F%2Fgithub.com%2Fmdshw5%2Fpyfaidx