File Coverage

lib/BoutrosLab/TSVStream/Format/AnnovarInput/Role.pm
Criterion Covered Total %
statement 63 63 100.0
branch n/a
condition n/a
subroutine 21 21 100.0
pod n/a
total 84 84 100.0


line stmt bran cond sub pod time code
1             # safe Perl
2 5     5   3093 use warnings;
  5         9  
  5         165  
3 5     5   20 use strict;
  5         5  
  5         101  
4 5     5   17 use Carp;
  5         9  
  5         431  
5              
6             =head1 NAME
7              
8             BoutrosLab::TSVStream::Format::AnnovarInput::Role
9              
10             =head1 SYNOPSIS
11              
12             Collection of roles that implement AnnovarInput format capable objects.
13             This role provides the common attributes for AnnovarInput format, but there
14             are sub-roles to specify the various restrictions for the B<chr>
15             attribute.
16              
17             =head1 DESCRIPTION
18              
19             To create a new sub-role (<XXX>), extend the type categories in the
20             BoutrosLab::TSVStream::Format::AnnovarInput::Types module to provide a type
21             that restricts the chr field appropriately, and define a role module
22             that applies that type to the B<chr> attribute.
23              
24             Look at the definition of the Human type in this role.
25              
26             To use one of these roles to define an object B<XXX>:
27              
28             package BoutrosLab::TSVStream::Format::AnnovarInput::<XXX>::Fixed;
29             use Moose;
30              
31             with qw(
32             BoutrosLab::TSVStream::Format::AnnovarInput::Role
33             BoutrosLab::TSVStream::Format::AnnovarInput::Role::<XXX>
34             BoutrosLab::TSVStream::IO::Role::Fixed
35             );
36              
37             (Replace 'Fixed' with 'Dyn' in the package name and in the 'with ...
38             BoutrosLab::TSVStream::IO::Role::Fixed' if you want the object to have
39             a group of dynamic fields in addition to the standard AnnovarInput attributes.)
40              
41             See BoutrosLab::TSVStream::Format::Human::Fixed for an example.
42              
43             =cut
44              
45             package BoutrosLab::TSVStream::Format::AnnovarInput::Role;
46              
47 5     5   1720 use Moose::Role;
  5         12983  
  5         61  
48 5     5   20394 use BoutrosLab::TSVStream::Format::AnnovarInput::Types qw( AI_Ref );
  5         14  
  5         50  
49 5     5   10910 use BoutrosLab::TSVStream::Format::VCF::Types qw( VCF_Alt );
  5         12  
  5         43  
50 5     5   7364 use MooseX::Types::Moose qw( ArrayRef Int );
  5         8  
  5         92  
51 5     5   18407 use MooseX::ClassAttribute;
  5         207898  
  5         24  
52 5     5   768823 use namespace::autoclean;
  5         9  
  5         39  
53              
54             =head1 Class Attributes
55              
56             =head2 _fields
57              
58             The B<_fields> attribute is required by the IO roles to determine
59             which fields are to be read or written. In this case, the fields
60             are C<chr>, C<start>, C<end>, C<ref>, and C<alt>, which are described
61             as attributes below.
62              
63             =cut
64              
65             class_has '_fields' => (
66             is => 'ro',
67             isa => ArrayRef,
68             default => sub { [qw(chr start end ref alt)] }
69             );
70              
71             =head1 Attributes
72              
73             =head2 chr
74              
75             The B<chr> attribute provides the name of the chromosome that is
76             being specified. There are different names used for different
77             species of organism; and for different ways of processing the same
78             organism; so this attribute is provided in a separate role.
79              
80             =head2 start
81              
82             =head2 end
83              
84             The B<start> and B<end> attributes are integers that provide the start
85             and end position within the chromosome that is being described.
86              
87             =cut
88              
89             has 'start' => ( is => 'rw', isa => Int );
90             has 'end' => ( is => 'rw', isa => Int );
91              
92             =head2 ref
93              
94             =head2 alt
95              
96             The B<ref> and B<alt> attributes describe amino acid sequences.
97             They can either contain the string I<'-'>, or a sequence of acids
98             (C<'A'>, C<'C'>, C<'G'>, and C<'T'> of at most 500 acids. (E.G.:
99             CGATCGAT)
100              
101             =cut
102              
103             has 'ref' => ( is => 'rw', isa => AI_Ref );
104             has 'alt' => ( is => 'rw', isa => VCF_Alt );
105              
106             =head1 SUBROLES
107              
108             =head2 BoutrosLab::TSVStream::Format::AnnovarInput::Role::Human
109              
110             =head2 BoutrosLab::TSVStream::Format::AnnovarInput::Role::HumanNoChr
111              
112             These two subroles provide a chr field that has no tag. It will
113             accept valid chr values regardless of whether the provided value
114             has a leading 'chr' or not; the value will get the 'chr' prefix
115             inserted if missing (Human) or removed if present (HumanNoChr).
116             So, you choose the type that you want to end with.
117              
118             For a B<reader>, this happens when reading an input stream - the
119             leading 'chr' will get forced to exist or not based on the type
120             you choose. So, within your program, the values will all appear
121             in a consistant form regardless of what the input file provided.
122              
123             For a B<writer>, this happens upon write - the B<write>
124             method will accept either an object of the configured form
125             (which it writes out directly), or an object of some other type
126             (which it converts into the specified type before writing). So,
127             you can have your program write into the format that is needed
128             by whatever program is going to use the output, regardless of
129             which format is used for internal computation by your program.
130              
131             =head2 BoutrosLab::TSVStream::Format::AnnovarInput::Role::HumanTag
132              
133             =head2 BoutrosLab::TSVStream::Format::AnnovarInput::Role::HumanTagNoChr
134              
135             These two subroles provide a chr field that may have a tag.
136             That allows a standard chr value to have an appended "_NAME"
137             (anything following an underscore). It also allows the tag-only
138             chr value "Un_NAME" (any NAME following 'Un_'.
139              
140             Like the two subroles above, the addition or absense of 'NoChr'
141             in the role name controls whether the value is coerced to have,
142             or not have, a leading 'chr' string. (See the previous section.)
143              
144             =cut
145              
146             package BoutrosLab::TSVStream::Format::AnnovarInput::Role::Human;
147              
148 5     5   814 use Moose::Role;
  5         10  
  5         35  
149 5     5   17421 use BoutrosLab::TSVStream::Format::AnnovarInput::Types qw(AI_ChrHumanWithChr);
  5         7  
  5         40  
150 5     5   8081 use namespace::autoclean;
  5         5  
  5         22  
151              
152             has 'chr' => (
153             is => 'ro',
154             isa => AI_ChrHumanWithChr,
155             coerce => 1,
156             required => 1
157             );
158              
159              
160             package BoutrosLab::TSVStream::Format::AnnovarInput::Role::HumanNoChr;
161              
162 5     5   443 use Moose::Role;
  5         8  
  5         19  
163 5     5   16316 use BoutrosLab::TSVStream::Format::AnnovarInput::Types qw(AI_ChrHumanNoChr);
  5         7  
  5         19  
164 5     5   7351 use namespace::autoclean;
  5         6  
  5         20  
165              
166             has 'chr' => (
167             is => 'ro',
168             isa => AI_ChrHumanNoChr,
169             coerce => 1,
170             required => 1
171             );
172              
173              
174             package BoutrosLab::TSVStream::Format::AnnovarInput::Role::HumanTag;
175              
176 5     5   379 use Moose::Role;
  5         6  
  5         19  
177 5     5   16204 use BoutrosLab::TSVStream::Format::AnnovarInput::Types qw(AI_ChrHumanTagWithChr);
  5         9  
  5         19  
178 5     5   7300 use namespace::autoclean;
  5         7  
  5         21  
179              
180             has 'chr' => (
181             is => 'ro',
182             isa => AI_ChrHumanTagWithChr,
183             coerce => 1,
184             required => 1
185             );
186              
187              
188             package BoutrosLab::TSVStream::Format::AnnovarInput::Role::HumanTagNoChr;
189              
190 5     5   403 use Moose::Role;
  5         6  
  5         19  
191 5     5   16226 use BoutrosLab::TSVStream::Format::AnnovarInput::Types qw(AI_ChrHumanTagNoChr);
  5         8  
  5         21  
192 5     5   7358 use namespace::autoclean;
  5         6  
  5         20  
193              
194             has 'chr' => (
195             is => 'ro',
196             isa => AI_ChrHumanTagNoChr,
197             coerce => 1,
198             required => 1
199             );
200              
201              
202             =head1 SEE ALSO
203              
204             =over
205              
206             =item BoutrosLab::TSVStream::Format
207              
208             This describes how IO-capable objects (such as ones created using
209             a subrole of this role) are defined.
210              
211             =item BoutrosLab::TSVStream::IO
212              
213             This describes of how readers and writers convert objects to or
214             from a text stream.
215              
216             =item - BoutrosLab::TSVStream::Format::AnnovarInput::Human::Fixed
217              
218             =item - BoutrosLab::TSVStream::Format::AnnovarInput::Human::Dyn
219              
220             =item - BoutrosLab::TSVStream::Format::AnnovarInput::HumanNoChr::Fixed
221              
222             =item - BoutrosLab::TSVStream::Format::AnnovarInput::HumanNoChr::Dyn
223              
224             These are the four variants for the object specification for Human
225             objects. Those are the modules that you will typically B<use>
226             in your program.
227              
228             Human/HumanNoChr specifies whether objects will be converted if
229             needed to (no) leading 'chr' prefix in the B<chr> attribute.
230              
231             Fixed/Dyn specifies whether only the standard fields are expected,
232             or if a dynamic list of additional fields may occur.
233              
234             =back
235              
236             =head1 AUTHOR
237              
238             John Macdonald - Boutros Lab
239              
240             =head1 ACKNOWLEDGEMENTS
241              
242             Paul Boutros, Phd, PI - Boutros Lab
243              
244             The Ontario Institute for Cancer Research
245              
246             =cut
247              
248             1;
249