1# ===========================================================================
2#
3#                            PUBLIC DOMAIN NOTICE
4#               National Center for Biotechnology Information
5#
6#  This software/database is a "United States Government Work" under the
7#  terms of the United States Copyright Act.  It was written as part of
8#  the author's official duties as a United States Government employee and
9#  thus cannot be copyrighted.  This software/database is freely available
10#  to the public for use. The National Library of Medicine and the U.S.
11#  Government have not placed any restriction on its use or reproduction.
12#
13#  Although all reasonable efforts have been taken to ensure the accuracy
14#  and reliability of the software and data, the NLM and the U.S.
15#  Government do not and cannot warrant the performance or results that
16#  may be obtained by using this software or data. The NLM and the U.S.
17#  Government disclaim all warranties, express or implied, including
18#  warranties of performance, merchantability or fitness for any particular
19#  purpose.
20#
21#  Please cite the author in any work or product based on this material.
22#
23# ===========================================================================
24#
25#
26from ctypes import c_char, c_int32, c_uint32, c_int64, c_void_p
27from . import NGS
28
29from .String import getNGSString, getNGSValue
30from .Refcount import Refcount
31
32from .Alignment import Alignment
33
34
35# Represents a single cell of a sparse 2D matrix with Reference coordinates on one axis
36# and stacked Alignments on the other axis
37
38class PileupEvent(Refcount):
39
40    # ----------------------------------------------------------------------
41    # Reference
42
43    def getMappingQuality(self):
44        return getNGSValue(self, NGS.lib_manager.PY_NGS_PileupEventGetMappingQuality, c_int32)
45
46    # ----------------------------------------------------------------------
47    # Alignment
48
49    def getAlignmentId(self):
50        return getNGSString(self, NGS.lib_manager.PY_NGS_PileupEventGetAlignmentId)
51
52    def getAlignmentPosition(self):
53        return getNGSValue(self, NGS.lib_manager.PY_NGS_PileupEventGetAlignmentPosition, c_int64)
54
55    def getFirstAlignmentPosition(self):
56        """
57        :returns: the position of this Alignment's first event in Reference coordinates
58        """
59        return getNGSValue(self, NGS.lib_manager.PY_NGS_PileupEventGetFirstAlignmentPosition, c_int64)
60
61    def getLastAlignmentPosition(self):
62        """
63        :returns: the position of this Alignment's last event in INCLUSIVE Reference coordinates
64        """
65        return getNGSValue(self, NGS.lib_manager.PY_NGS_PileupEventGetLastAlignmentPosition, c_int64)
66
67    # ----------------------------------------------------------------------
68    # event details
69
70    match                       = 0
71    mismatch                    = 1
72    deletion = 2
73
74    # an insertion cannot be represented in reference coordinate
75    # space ( so no insertion event can be directly represented ),
76    # but it can occur before a match or mismatch event.
77    # insertion is represented as a bit
78    insertion                   = 0x08
79
80    # insertions into the reference
81    insertion_before_match      = insertion | match
82    insertion_before_mismatch   = insertion | mismatch
83
84    # simultaneous insertion and deletion,
85    # a.k.a. a replacement
86    insertion_before_deletion   = insertion | deletion
87    replacement                 = insertion_before_deletion
88
89    # additional modifier bits - may be added to any event above
90    alignment_start             = 0x80
91    alignment_stop              = 0x40
92    alignment_minus_strand      = 0x20
93
94
95    def getEventType(self):
96        return getNGSValue(self, NGS.lib_manager.PY_NGS_PileupEventGetEventType, c_uint32)
97
98    def getAlignmentBase(self):
99        """
100        :returns: retrieves base aligned at current Reference position
101        :throws: ErrorMsg if event is an insertion or deletion
102        """
103        return getNGSValue(self, NGS.lib_manager.PY_NGS_PileupEventGetAlignmentBase, c_char).decode("utf-8")
104
105    def getAlignmentQuality(self):
106        """
107        :returns: retrieves base aligned at current Reference position
108        :throws: ErrorMsg if event is an insertion or deletion
109        """
110        return getNGSValue(self, NGS.lib_manager.PY_NGS_PileupEventGetAlignmentQuality, c_char).decode("utf-8")
111
112    def getInsertionBases(self):
113        """
114        :returns: bases corresponding to insertion event
115        """
116        return getNGSString(self, NGS.lib_manager.PY_NGS_PileupEventGetInsertionBases)
117
118    def getInsertionQualities(self):
119        """
120        :returns: qualities corresponding to insertion event
121        """
122        return getNGSString(self, NGS.lib_manager.PY_NGS_PileupEventGetInsertionQualities)
123
124    def getEventRepeatCount(self):
125        """
126        :returns: the number of times this event repeats, i.e. the distance to the first reference position yielding a different event type for this alignment
127        """
128        return getNGSValue(self, NGS.lib_manager.PY_NGS_PileupEventGetEventRepeatCount, c_uint32)
129
130    # EventIndelType
131
132    normal_indel              = 0
133
134    # introns behave like deletions
135    # (i.e. can retrieve deletion count),
136    # "_plus" and "_minus" signify direction
137    # of transcription if known
138    intron_plus               = 1
139    intron_minus              = 2
140    intron_unknown            = 3
141
142    # overlap is reported as an insertion,
143    # but is actually an overlap in the read
144    # inherent in technology like Complete Genomics
145    read_overlap              = 4
146
147    # gap is reported as a deletion,
148    # but is actually a gap in the read
149    # inherent in technology like Complete Genomics
150    read_gap                  = 5
151
152
153    def getEvenIndeltType(self):
154        return getNGSValue(self, NGS.lib_manager.PY_NGS_PileupEventGetEventIndelType, c_uint32)
155
156