1 /* @include ajdomain **********************************************************
2 **
3 ** AJAX objects for handling protein domain data.
4 ** Scop, Cath and Domain objects.
5 **
6 ** @author: Copyright (C) 2004 Jon Ison (jison@hgmp.mrc.ac.uk)
7 ** @version $Revision: 1.26 $
8 ** @modified $Date: 2012/04/12 20:36:39 $ by $Author: mks $
9 ** @@
10 **
11 ** This library is free software; you can redistribute it and/or
12 ** modify it under the terms of the GNU Lesser General Public
13 ** License as published by the Free Software Foundation; either
14 ** version 2.1 of the License, or (at your option) any later version.
15 **
16 ** This library is distributed in the hope that it will be useful,
17 ** but WITHOUT ANY WARRANTY; without even the implied warranty of
18 ** MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
19 ** Lesser General Public License for more details.
20 **
21 ** You should have received a copy of the GNU Lesser General Public
22 ** License along with this library; if not, write to the Free Software
23 ** Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
24 ** MA  02110-1301,  USA.
25 **
26 ******************************************************************************/
27 
28 #ifndef AJDOMAIN_H
29 #define AJDOMAIN_H
30 
31 /* ========================================================================= */
32 /* ============================= include files ============================= */
33 /* ========================================================================= */
34 
35 #include "ajdefine.h"
36 #include "ajstr.h"
37 #include "ajlist.h"
38 #include "ajfile.h"
39 #include "ajpdb.h"
40 #include "ajreg.h"
41 #include "ajseqwrite.h"
42 
43 AJ_BEGIN_DECLS
44 
45 
46 
47 
48 /* ========================================================================= */
49 /* =============================== constants =============================== */
50 /* ========================================================================= */
51 
52 
53 
54 
55 /* @enum AjEDomainType ********************************************************
56 **
57 ** AJAX Domain Type enumeration
58 **
59 ** @value ajEDomainTypeNULL NULL
60 ** @value ajEDomainTypeCATH CATH
61 ** @value ajEDomainTypeSCOP SCOP
62 ** @@
63 ******************************************************************************/
64 
65 typedef enum AjODomainType
66 {
67     ajEDomainTypeNULL,
68     ajEDomainTypeCATH,
69     ajEDomainTypeSCOP
70 } AjEDomainType;
71 
72 
73 
74 
75 /* ========================================================================= */
76 /* ============================== public data ============================== */
77 /* ========================================================================= */
78 
79 
80 
81 
82 /* @data AjPScop **************************************************************
83 **
84 ** AJAX SCOP object
85 **
86 ** Holds SCOP database data
87 **
88 ** @alias AjSScop
89 ** @alias AjOScop
90 **
91 ** @attr Entry [AjPStr] Domain identifier code
92 ** @attr Pdb [AjPStr] Corresponding pdb identifier code
93 ** @attr Class [AjPStr] SCOP class name as an AjPStr
94 ** @attr Fold [AjPStr] SCOP fold  name as an AjPStr
95 ** @attr Superfamily [AjPStr]  SCOP superfamily name as an AjPStr
96 ** @attr Family [AjPStr] SCOP family name as an AjPStr
97 ** @attr Domain [AjPStr] SCOP domain name as an AjPStr
98 ** @attr Source [AjPStr] SCOP source (species) as an AjPStr
99 ** @attr Chain [char*] Chain identifiers
100 ** @attr Start [AjPStr*] PDB residue number of first residue in domain
101 ** @attr End [AjPStr*] PDB residue number of last residue in domain
102 ** @attr Sse [AjPStr] Secondary structure element map
103 ** @attr Sss [AjPStr] Secondary structure element string
104 ** @attr Number [ajuint] Number of chains from which this domain is comprised
105 ** @attr Sunid_Class [ajint] SCOP sunid for class
106 ** @attr Sunid_Fold [ajint] SCOP sunid for fold
107 ** @attr Sunid_Superfamily [ajint] SCOP sunid for superfamily
108 ** @attr Sunid_Family [ajint] SCOP sunid for family
109 ** @attr Sunid_Domain [ajint] SCOP sunid for domain
110 ** @attr Sunid_Source [ajint] SCOP sunid for species
111 ** @attr Sunid_Domdat [ajint] SCOP sunid for domain data
112 **
113 ** @attr Acc [AjPStr] Accession number of sequence entry
114 ** @attr Spr [AjPStr] Swissprot code of sequence entry
115 ** @attr SeqPdb [AjPStr] Sequence (from PDB) as string
116 ** @attr SeqSpr [AjPStr] Sequence (from swissprot) as string
117 ** @attr Startd [ajint] Start of sequence relative to full
118 ** length swissprot sequence
119 ** @attr Endd [ajint] End of sequence relative to full length
120 ** swissprot sequence
121 ** @attr Score [float] Used by misc. algorithms for scoring the domain
122 ** @attr Padding [char[4]] Padding to alignment boundary
123 **
124 ** @new    ajScopNew Scop default constructor
125 ** @new    ajScopReadNew Scop constructor from reading DCF format file
126 ** @new    ajScopReadCNew Scop constructor from reading DCF format file
127 ** @delete ajScopDel Default Scop destructor
128 ** @assign ajScopCopy Replicates a Scop object
129 ** @use    ajScopMatchSunid Sort Scop objects by Sunid_Family element
130 ** @use    ajScopMatchScopid Sort Scop objects by Entry element
131 ** @use    ajScopMatchPdbId Sort Scop objects by Pdb element
132 ** @use    embScopToPdbid  Read a scop identifier code and writes the
133 **         equivalent PDB identifier code
134 ** @use    embScopToSp  Read a scop identifier code and writes the
135 **         equivalent swissprot identifier code
136 ** @use    embScopToAcc  Read a scop identifier code and writes the
137 **         equivalent accession number
138 ** @use    ajScopArrFindScopid Binary search for Entry element over array
139 **         of Scop objects
140 ** @use    ajScopArrFindSunid Binary search for Sunid_Family element over
141 **         array of Scop objects
142 ** @use    ajScopArrFindPdbid Binary search for Pdb element over array of
143 **         Scop objects
144 ** @new    ajScopReadAllNew Construct list of Scop objects from reading DCF
145 **         format file
146 ** @new  ajScopReadAllRawNew Construct list of Scop objects from reading
147 **         raw SCOP parsable files
148 ** @output ajScopWrite Write Scop object to DCF format file
149 ** @output ajPdbWriteDomain Writes a CCF format file for a SCOP domain
150 ** @output ajPdbWriteDomainRaw Writes a PDB-format file for a SCOP domain
151 ** @output ajPdbWriteDomainRecordRaw Writes lines to a PDB format file for
152 **         a domain
153 ** @@
154 ******************************************************************************/
155 
156 typedef struct AjSScop
157 {
158     AjPStr Entry;
159     AjPStr Pdb;
160     AjPStr Class;
161     AjPStr Fold;
162     AjPStr Superfamily;
163     AjPStr Family;
164     AjPStr Domain;
165     AjPStr Source;
166 
167     char   *Chain;
168     AjPStr *Start;
169     AjPStr *End;
170 
171     AjPStr Sse;
172     AjPStr Sss;
173 
174     ajuint Number;
175 
176     ajint Sunid_Class;
177     ajint Sunid_Fold;
178     ajint Sunid_Superfamily;
179     ajint Sunid_Family;
180     ajint Sunid_Domain;
181     ajint Sunid_Source;
182     ajint Sunid_Domdat;
183 
184     AjPStr Acc;
185     AjPStr Spr;
186     AjPStr SeqPdb;
187     AjPStr SeqSpr;
188     ajint Startd;
189     ajint Endd;
190 
191     float Score;
192     char Padding[4];
193 } AjOScop;
194 
195 #define AjPScop AjOScop*
196 
197 
198 
199 
200 /* @data AjPCath **************************************************************
201 **
202 ** Ajax cath object
203 **
204 ** Holds cath database data
205 **
206 ** AjPScop is implemented as a pointer to a C data structure.
207 **
208 **
209 **
210 ** @alias AjSCath
211 ** @alias AjOCath
212 **
213 **
214 **
215 ** @attr DomainID       [AjPStr]  Domain identifier code
216 ** @attr Pdb            [AjPStr]  Corresponding PDB identifier code
217 ** @attr Class          [AjPStr]  CATH class name as an AjPStr
218 ** @attr Architecture   [AjPStr]  CATH architecture name as an AjPStr
219 ** @attr Topology       [AjPStr]  CATH topology name as an AjPStr
220 ** @attr Superfamily    [AjPStr]  CATH homologous superfamily name as an AjPStr
221 ** @attr Length         [ajint]   No. of residues in domain
222 ** @attr NSegment       [ajuint]  Number of chain segments domain is comprised of
223 ** @attr Start          [AjPStr*] PDB residue number of 1st residue in segment
224 ** @attr End            [AjPStr*] PDB residue number of last residue in segment
225 ** @attr Class_Id       [ajint]   CATH class no. as an ajint
226 ** @attr Arch_Id        [ajint]   CATH architecture no.as an ajint
227 ** @attr Topology_Id    [ajint]   CATH topology no. as an ajint
228 ** @attr Superfamily_Id [ajint]   CATH superfamily no. as an ajint
229 ** @attr Family_Id      [ajint]   CATH family no. as an ajint
230 ** @attr NIFamily_Id    [ajint]   CATH near identical family no. as an ajint
231 **
232 ** @attr Acc                [AjPStr]  Accession number of sequence entry.
233 ** @attr Spr                [AjPStr]  Swissprot code of sequence entry.
234 ** @attr SeqPdb             [AjPStr]  Sequence (from PDB) as string.
235 ** @attr SeqSpr             [AjPStr]  Sequence (from swissprot) as string.
236 ** @attr IFamily_Id     [ajint]   CATH identical family no. as an ajint
237 **
238 ** @attr Startd             [ajint]   Start of sequence relative to full
239 **                                    length swissprot sequence.
240 ** @attr Endd               [ajint]   End of sequence relative to full length
241 **                                    swissprot sequence.
242 ** @attr Chain              [char]    Chain identifier
243 ** @attr Padding            [char[3]] Padding to alignment boundary
244 **
245 **
246 ** @new    ajCathNew Default Cath constructor
247 ** @new    ajCathReadCNew Cath constructor from reading DCF format file.
248 ** @new    ajCathReadNew Cath constructor from reading DCF format file.
249 ** @delete ajCathDel Default Cath destructor
250 ** @assign ajCathCopy Replicates a Scop object.
251 ** @use    ajCathArrFindPdbid Binary search for Pdb element over array of
252 **         Cath objects.
253 ** @use    ajCathMatchPdbId Sort Cath objects by Pdb element.
254 ** @new    ajCathReadAllNew Construct list of Cath objects from reading DCF
255 **         format file.
256 ** @new    ajCathReadAllRawNew Construct list of Cath objects from reading
257 **         raw CATH parsable files.
258 ** @other  ajCathWrite Write Cath object to DCF format file.
259 **
260 ** @@
261 ******************************************************************************/
262 
263 typedef struct AjSCath
264 {
265     AjPStr  DomainID;
266     AjPStr  Pdb;
267     AjPStr  Class;
268     AjPStr  Architecture;
269     AjPStr  Topology;
270     AjPStr  Superfamily;
271 
272     ajint   Length;
273 
274     ajuint  NSegment;
275     AjPStr *Start;
276     AjPStr *End;
277 
278     ajint   Class_Id;
279     ajint   Arch_Id;
280     ajint   Topology_Id;
281     ajint   Superfamily_Id;
282     ajint   Family_Id;
283     ajint   NIFamily_Id;
284 
285     AjPStr Acc;
286     AjPStr Spr;
287     AjPStr SeqPdb;
288     AjPStr SeqSpr;
289     ajint  IFamily_Id;
290     ajint  Startd;
291     ajint  Endd;
292     char   Chain;
293     char   Padding[3];
294 } AjOCath;
295 
296 #define AjPCath AjOCath*
297 
298 
299 
300 
301 /* @data AjPDomain ************************************************************
302 **
303 ** Ajax Domain object.
304 **
305 ** Holds an entry from a DCF file (domain classification file)
306 **
307 ** AjPDomain is implemented as a pointer to a C data structure.
308 **
309 ** @alias AjSDomain
310 ** @alias AjODomain
311 **
312 ** @attr Scop    [AjPScop] Scop object pointer.
313 ** @attr Cath    [AjPCath] Cath object pointer.
314 ** @attr Type    [AjEDomainType] AJAX Domain Type enumeration
315 ** @attr Padding [char[4]] Padding to alignment boundary
316 **
317 ** @new    ajDomainNew Default Domain constructor.
318 ** @new    ajDomainReadNew Domain constructor from reading DCF format file.
319 ** @new    ajDomainReadCNew Domain constructor from reading DCF format file.
320 ** @new    ajDomainReadAllNew Construct list of Domain objects from reading DCF
321 **         format file.
322 ** @delete ajDomainDel Default Domain destructor.
323 ** @output ajDomainWrite Write Domain object to DCF format file.
324 ** @other  ajDomainDCFType Ascertains type of domains (ajEDomainTypeSCOP
325 **         or ajEDomainTypeCATH) in a DCF file.
326 ** @assign ajDomainCopy Replicates a Domain object.
327 ** @cast   ajDomainGetId Returns domain id, either DomainID element
328 **                      (Cath object) or Entry (Scop object).
329 ** @cast   ajDomainGetSeqPdb Returns the PDB sequence from a Domain object.
330 ** @cast   ajDomainGetSeqSpr Returns the swissprot sequence from a
331 **                           Domain object.
332 ** @cast   ajDomainGetPdb Returns the PDB identifier code corresponding to the
333 **                        domain
334 ** @cast   ajDomainGetAcc Returns the accession number corresponding to the
335 **                        domain.
336 ** @cast   ajDomainGetSpr Returns the swissprot code corresponding to the
337 **                        domain.
338 ** @cast   ajDomainGetN  Returns no. chains or chain segments in a domain,
339 ** either NSegment element (Cath domains) or N element (Scop domains).
340 ** @@
341 ******************************************************************************/
342 
343 typedef struct AjSDomain
344 {
345     AjPScop Scop;
346     AjPCath Cath;
347     AjEDomainType Type;
348     char Padding[4];
349 } AjODomain;
350 
351 #define AjPDomain AjODomain*
352 
353 
354 
355 
356 /* ========================================================================= */
357 /* =========================== public functions ============================ */
358 /* ========================================================================= */
359 
360 
361 
362 
363 /*
364 ** Prototype definitions
365 */
366 
367 /* ======================================================================= */
368 /* =========================== Scop object =============================== */
369 /* ======================================================================= */
370 
371 void     ajDomainDummyFunction(void);
372 AjPScop  ajScopNew(ajuint n);
373 void     ajScopDel(AjPScop *Pscop);
374 AjBool   ajScopCopy(AjPScop *Pto, const AjPScop from);
375 
376 ajint    ajScopArrFindScopid(AjPScop const *array, ajint size,
377                              const AjPStr identifier);
378 ajint    ajScopArrFindSunid(AjPScop const *array, ajint size,
379                             ajint identifier);
380 ajint    ajScopArrFindPdbid(AjPScop const *array, ajint size,
381                             const AjPStr identifier);
382 
383 ajint    ajScopMatchScopid(const void *item1, const void *item2);
384 ajint    ajScopMatchPdbId(const void *item1, const void *item2);
385 ajint    ajScopMatchSunid(const void *item1, const void *item2);
386 
387 AjPScop  ajScopReadCNew(AjPFile inf, const char *entry);
388 AjPScop  ajScopReadNew(AjPFile inf, const AjPStr entry);
389 AjPList  ajScopReadAllNew(AjPFile inf);
390 AjPList  ajScopReadAllRawNew(AjPFile claf, AjPFile desf, AjBool omit);
391 AjBool   ajScopWrite(AjPFile outf, const AjPScop scop);
392 
393 AjBool   ajPdbWriteDomain(AjPFile outf, const AjPPdb pdb,
394                           const AjPScop scop, AjPFile errf);
395 
396 
397 
398 
399 /* ======================================================================= */
400 /* =========================== Cath object =============================== */
401 /* ======================================================================= */
402 
403 AjPCath   ajCathNew(ajuint n);
404 void      ajCathDel(AjPCath *Pcath);
405 AjBool    ajCathCopy(AjPCath *Pto, const AjPCath from);
406 
407 ajint     ajCathArrFindPdbid(AjPCath const *array, ajint size,
408                              const AjPStr identifier);
409 ajint     ajCathMatchPdbId(const void *item1, const void *item2);
410 
411 AjPCath   ajCathReadCNew(AjPFile inf, const char *entry);
412 AjPCath   ajCathReadNew(AjPFile inf, const AjPStr entry);
413 AjPList   ajCathReadAllNew(AjPFile inf);
414 AjPList   ajCathReadAllRawNew(AjPFile cathf, AjPFile domf,
415                               AjPFile namesf, AjPFile flog);
416 AjBool    ajCathWrite(AjPFile outf, const AjPCath cath);
417 
418 
419 
420 
421 /* ======================================================================= */
422 /* =========================== Domain object ============================= */
423 /* ======================================================================= */
424 
425 AjPDomain       ajDomainNew(ajuint n, AjEDomainType type);
426 AjPDomain       ajDomainReadNew(AjPFile inf, const AjPStr entry);
427 AjPDomain       ajDomainReadCNew(AjPFile inf, const char *entry,
428                                  AjEDomainType type);
429 AjPList         ajDomainReadAllNew(AjPFile inf);
430 void            ajDomainDel(AjPDomain *Pdomain);
431 AjBool          ajDomainWrite(AjPFile outf, const AjPDomain domain);
432 AjEDomainType   ajDomainDCFType(AjPFile inf);
433 AjBool          ajDomainCopy(AjPDomain *Pto, const AjPDomain from);
434 
435 AjPStr          ajDomainGetId(const AjPDomain domain);
436 AjPStr          ajDomainGetSeqPdb(const AjPDomain domain);
437 AjPStr          ajDomainGetSeqSpr(const AjPDomain domain);
438 AjPStr          ajDomainGetPdb(const AjPDomain domain);
439 AjPStr          ajDomainGetAcc(const AjPDomain domain);
440 AjPStr          ajDomainGetSpr(const AjPDomain domain);
441 ajint           ajDomainGetN(const AjPDomain domain);
442 
443 void ajDomainExit(void);
444 
445 /*
446 ** End of prototype definitions
447 */
448 
449 
450 
451 
452 /******************************************************************************
453  **
454  ** Macros for returning elements from an instance of a
455  **
456  ** Domain object
457  **
458  ******************************************************************************/
459 
460 #define DOMAIN_S_Entry(ptr) ptr->Scop->Entry
461 #define DOMAIN_S_Pdb(ptr) ptr->Scop->Pdb
462 #define DOMAIN_S_Class(ptr) ptr->Scop->Class
463 #define DOMAIN_S_Fold(ptr) ptr->Scop->Fold
464 #define DOMAIN_S_Superfamily(ptr) ptr->Scop->Superfamily
465 #define DOMAIN_S_Family(ptr) ptr->Scop->Family
466 #define DOMAIN_S_Sunid_Class(ptr) ptr->Scop->Sunid_Class
467 #define DOMAIN_S_Sunid_Fold(ptr) ptr->Scop->Sunid_Fold
468 #define DOMAIN_S_Sunid_Superfamily(ptr) ptr->Scop->Sunid_Superfamily
469 #define DOMAIN_S_Sunid_Family(ptr) ptr->Scop->Sunid_Family
470 #define DOMAIN_S_Acc(ptr) ptr->Scop->Acc
471 #define DOMAIN_S_Spr(ptr) ptr->Scop->Spr
472 #define DOMAIN_S_SeqPdb(ptr) ptr->Scop->SeqPdb
473 #define DOMAIN_S_SeqSpr(ptr) ptr->Scop->SeqSpr
474 /* #define DOMAIN_S_(ptr) ptr->Scop-> */
475 
476 
477 
478 
479 AJ_END_DECLS
480 
481 #endif /* !AJDOMAIN_H */
482