examples/biojson-doc/index.html

   1 <!DOCTYPE html>
   2 <!--
   3  * Jalview - A Sequence Alignment Editor and Viewer ($$Version-Rel$$)
   4  * Copyright (C) $$Year-Rel$$ The Jalview Authors
   5  *
   6  * This file is part of Jalview.
   7  *
   8  * Jalview is free software: you can redistribute it and/or
   9  * modify it under the terms of the GNU General Public License
  10  * as published by the Free Software Foundation, either version 3
  11  * of the License, or (at your option) any later version.
  12  *
  13  * Jalview is distributed in the hope that it will be useful, but
  14  * WITHOUT ANY WARRANTY; without even the implied warranty
  15  * of MERCHANTABILITY or FITNESS FOR A PARTICULAR
  16  * PURPOSE.  See the GNU General Public License for more details.
  17  *
  18  * You should have received a copy of the GNU General Public License
  19  * along with Jalview.  If not, see <http://www.gnu.org/licenses/>.
  20  * The Jalview Authors are detailed in the 'AUTHORS' file.
  21  -->
  22 <html>
  23 <head>
  24     <title>BioJSON Format Documentation</title>
  25     <meta charset="utf-8">
  26     <link rel="stylesheet" href="css/docson.css">
  27     <script src="lib/require.js"></script></head>
  28 <body>
  29
  30 <h1>BioJSON Format</h1>
  31 The BioJSON Format was introduced in Jalview 2.9 to serve as a standard format for representing/exchanging Bioinformatics Alignment data in JSON. This is the first version of the specification and we welcome all feedbacks on how to make BioJSON better, sustainable and widely adopted worldwide.
  32
  33 This page describes the data available in BioJSON format, the main content section was created with Docson - a  resource which uses a JSON schema to generate a beautified and an interactive documentation.
  34
  35 <h3>Advantages of JSON/BioJSON</h3>
  36 <ul>
  37    <li>JSON is very popular and available in almost all programming languages</li>
  38    <li>Integrates seamlessly with the HTTP rest architecture</li>
  39    <li>Very light weight, self describing and easy to understand</li>
  40    <li>Handles linked data very efficiently</li>
  41 </ul>
  42
  43 <h3>Navigation Tips</h3>
  44 <ul>
  45 <li>When the mouse is hovered over the elements in the main content section, traversable elements become highlighted and clickable. </li>
  46 <li>Click the “object” button or plus <b>“+”</b> link to expand an object</li>
  47 <li>Click the minus <b>“—”</b> to collapse an object </li>
  48 <li>Click the parenthesis <b>“{}”</b> link to view the JSON schema which provides a more technical description of the data</li>
  49 <li>When you expand an object the following information becomes visible: The variables in the object, their data types and the description of each variable. This exactly corresponds to how it appears in BioJSON</li>
  50 </ul>
  51
  52 <h3>Main Content</h3>
  53 <div id="doc"></div>
  54
  55 <h3>Brief definition of key terms</h3>
  56 <ul>
  57    <li><b>Residue</b> - This is a single unit of a Nucleic acid (RNA, DNA) or Amino acid (Protein).</li>
  58    <li><b>Sequence</b> - A Sequence contains an array of residues with basic details about it (i.e name, start/end positions, database source, etc) </li>
  59    <li><b>Alignment</b> - An alignment consists of an array of individual Sequences organised together, one above each other</li>
  60    <li><b>Group</b> - Sections of an alignment or Sequence can be coupled together to form a group</li>
  61    <li><b>Annotation</b> - Annotation provides various kinds of information for what is known about a sequence(Sequence Annotation), or a collection of sequences in the alignment (Alignment Annotation) </li>
  62    <li><b>Feature</b> - Used to store data of known properties for sections of a sequence or alignment</li>
  63 </ul>
  64 </br>
  65
  66 <h3> BioJSON UML Diagram</h3>
  67 <img src="biojson_uml.png" alt="BioJSON UML">
  68
  69
  70 <script charset="utf-8">
  71     require.config({ baseUrl: ""});
  72     require(["docson", "lib/jquery"], function(docson) {
  73         $(function() {
  74             var schema =
  75             {
  76     "$schema": "http://json-schema.org/draft-04/schema#",
  77     "id": "BioJSON",
  78     "type": "object",
  79     "properties": {
  80         "seqs": {
  81             "id": "seqs",
  82             "type": "array",
  83             "items": {
  84                 "id": "seqs",
  85                 "type": "object",
  86                 "properties": {
  87                     "name": {
  88                         "id": "seqs/name",
  89                         "type": "string",
  90                         "description": "Sequence name"
  91                     },
  92                     "start": {
  93                         "id": "seqs/start",
  94                         "type": "integer",
  95                         "description": "The index of the sequence’s first residue in it’s source database"
  96                     },
  97                     "end": {
  98                         "id": "seqs/end",
  99                         "type": "integer",
 100                         "description": "The index of the sequence’s last residue in it’s source database"
 101                     },
 102                     "order": {
 103                         "id": "seqs/order",
 104                         "type": "integer",
 105                         "description": "The order/position of a sequence in the alignment space"
 106                     },
 107                     "id": {
 108                         "id": "seqs/id",
 109                         "type": "string",
 110                         "description": "Unique identifier for a given Sequence"
 111                     },
 112                     "seq": {
 113                         "id": "seqs/seq",
 114                         "type": "string",
 115                         "description": "Sequence Residues"
 116                     },
 117                     "svid": {
 118                         "id": "seqs/svid",
 119                         "type": "string",
 120                         "description": "Serial version identifier for the <b>seqs</b> object model"
 121                     }
 122                 },
 123                 "required": [
 124                     "name",
 125                     "start",
 126                     "svid",
 127                     "end",
 128                     "id",
 129                     "seq"
 130                 ]
 131             },
 132             "required": [
 133                 "0"
 134             ],
 135             "description": "An array of Sequences which makes up the Alignment",
 136             "minItems": "1",
 137             "maxItems": "*"
 138         },
 139         "seqGroups": {
 140             "id": "seqGroups",
 141             "type": "array",
 142             "items": [
 143                 {
 144                     "id": "seqGroups",
 145                     "type": "object",
 146                     "properties": {
 147                         "groupName": {
 148                             "id": "seqGroups/groupName",
 149                             "type": "string",
 150                             "description": "The name assigned to the seqGroup"
 151                         },
 152                         "startRes": {
 153                             "id": "seqGroups/startRes",
 154                             "type": "integer",
 155                             "description": "The index of the group’s first residue in the alignment space"
 156                         },
 157                         "endRes": {
 158                             "id": "seqGroups/endRes",
 159                             "type": "integer",
 160                             "description": "The index of the group’s last residue in the alignment space"
 161                         },
 162                         "svid": {
 163                             "id": "seqGroups/svid",
 164                             "type": "string",
 165                             "description": "Serial version identifier for the <b>seqGroup</b> object model"
 166                         },
 167                         "colourScheme": {
 168                             "id": "seqGroups/colourScheme",
 169                             "type": "string",
 170                             "description": "The Colour Scheme applied to the Sequence Group"
 171                         },
 172                         "displayBoxes": {
 173                             "id": "seqGroups/displayBoxes",
 174                             "type": "boolean",
 175                             "description": "Determines if the seqGroup border should be visible or not"
 176                         },
 177                         "showNonconserved": {
 178                             "id": "seqGroups/showNonconserved",
 179                             "type": "boolean",
 180                             "description": "Determines if non conserved regions of a group is shown or not"
 181                         },
 182                         "colourText": {
 183                             "id": "seqGroups/colourText",
 184                             "type": "boolean",
 185                             "description": "Determines if the Residues text for the group is coloured"
 186                         },
 187                         "displayText": {
 188                             "id": "seqGroups/displayText",
 189                             "type": "boolean",
 190                             "description": "Determines if the texts of the group is displayed or not"
 191                         },
 192                         "seqsHash": {
 193                             "id": "seqGroups/seqsHash",
 194                             "type": "array",
 195                             "items": [],
 196                             "minItems": "0",
 197                             "maxItems": "*",
 198                             "description": "An array of the unique id's for the sequences belonging to the group"
 199                         }
 200                     }
 201                 }
 202             ],
 203             "description": "Sequence groups in the Alignment",
 204             "minItems": "0",
 205             "maxItems": "*"
 206         },
 207         "alignAnnotation": {
 208             "id": "alignAnnotation",
 209             "type": "array",
 210             "items": {
 211                 "id": "alignAnnotation",
 212                 "type": "object",
 213                 "properties": {
 214                     "svid": {
 215                         "id": "alignAnnotation/svid",
 216                         "type": "string",
 217                         "description": "Serial version id for the <b>alignAnnotation</b> object model"
 218                     },
 219                     "description": {
 220                         "id": "alignAnnotation/description",
 221                         "type": "string",
 222                         "description": "Description for the Alignment Annotation"
 223                     },
 224                     "label": {
 225                         "id": "alignAnnotation/label",
 226                         "type": "string",
 227                         "description": "Label for the Alignment Annotation"
 228                     },
 229                     "annotations": {
 230                         "id": "alignAnnotation/annotations",
 231                         "type": "array",
 232                         "items": [
 233                             {
 234                                 "id": "alignAnnotation/annotations",
 235                                 "type": "object",
 236                                 "properties": {
 237                                     "displayCharacter": {
 238                                         "id": "alignAnnotation/annotations/displayCharacter",
 239                                         "type": "string",
 240                                         "description": "Display character which denotes the given annotation"
 241                                     },
 242                                     "secondaryStructure": {
 243                                         "id": "alignAnnotation/annotations/secondaryStructure",
 244                                         "type": "string",
 245                                         "description": "Secondary structure symbol for the given annotation"
 246                                     },
 247                                     "value": {
 248                                         "id": "alignAnnotation/annotations/value",
 249                                         "type": "integer",
 250                                         "description": "Value of the annotation"
 251                                     }
 252                                 }
 253                             }
 254                         ]
 255                     }
 256                 }
 257             },
 258             "description": "Alignment Annotations",
 259             "minItems": "0",
 260             "maxItems": "*"
 261         },
 262         "seqFeatures": {
 263             "id": "seqFeatures",
 264             "type": "array",
 265             "items": {
 266                 "id": "seqFeatures",
 267                 "type": "object",
 268                 "properties": {
 269                     "type": {
 270                         "id": "seqFeatures/type",
 271                         "type": "string",
 272                         "description": "The name of the SequenceFeature"
 273                     },
 274                     "fillColor": {
 275                         "id": "seqFeatures/fillColor",
 276                         "type": "string",
 277                         "description": "Fill colour"
 278                     },
 279                     "sequenceRef": {
 280                         "id": "seqFeatures/sequenceRef",
 281                         "type": "string",
 282                         "description": "Reference to the Sequence in the alignment (More like a foreign key)"
 283                     },
 284                     "featureGroup": {
 285                         "id": "seqFeatures/featureGroup",
 286                         "type": "string",
 287                         "description": "Feature Group"
 288                     },
 289                     "svid": {
 290                         "id": "seqFeatures/svid",
 291                         "type": "string",
 292                         "description": "Serial version id for the <b>SeqFeature</b> object"
 293                     },
 294                     "description": {
 295                         "id": "seqFeatures/description",
 296                         "type": "string",
 297                         "description": "Description of Feature"
 298                     },
 299                     "xStart": {
 300                         "id": "seqFeatures/xStart",
 301                         "type": "integer",
 302                         "description": "Start residue position for the sequence feature"
 303                     },
 304                     "xEnd": {
 305                         "id": "seqFeatures/xEnd",
 306                         "type": "integer",
 307                         "description": "End residue position for the sequence feature"
 308                     },
 309                     "score": {
 310                         "id": "seqFeatures/score",
 311                         "type": "integer",
 312                         "description": "Score"
 313                     }
 314                 }
 315             },
 316             "minItems": "0",
 317             "maxItems": "*",
 318             "description": "Sequence Features within the alignment"
 319         },
 320         "appSettings": {
 321             "id": "appSettings",
 322             "type": "object",
 323             "properties": {
 324                 "globalColorScheme": {
 325                     "id": "appSettings/globalColorScheme",
 326                     "type": "string",
 327                     "description": "The Global colour scheme applied to all the sequences within the alignment"
 328                 },
 329                 "webStartUrl": {
 330                     "id": "appSettings/webStartUrl",
 331                     "type": "string",
 332                     "description": "Jalview specific setting which points to the url for launching Jalview"
 333                 },
 334                 "application": {
 335                     "id": "appSettings/application",
 336                     "type": "string",
 337                     "description": "The name of the application which generated the Json"
 338                 },
 339                 "showSeqFeatures": {
 340                     "id": "appSettings/showSeqFeatures",
 341                     "type": "string",
 342                     "description": "Determines if sequence features are visible or not"
 343                 },
 344                 "version": {
 345                     "id": "appSettings/version",
 346                     "type": "string",
 347                     "description": "Version of the application which generated the JSON"
 348                 },
 349                 "hiddenCols": {
 350                     "id": "appSettings/hiddenCols",
 351                     "type": "string",
 352                     "description": "The ranges of hidden columns in the alignment in a comma delimited string i.e [2-5, 9-9, 11-12]"
 353                 }
 354             },
 355             "description": "This is for custom application specific settings in a map structure (key/value) pairs. Any application which can generate or consume BioJSON can extend their custom data here. However, it is essential to provide the application name, and version in the map for identification purposes."
 356         },
 357         "svid": {
 358             "id": "svid",
 359             "type": "string",
 360             "description": "Serial version identifier for <b>BioJSON</b> model"
 361         }
 362     },
 363     "required": [
 364         "seqs",
 365         "appSettings",
 366         "seqGroups",
 367         "alignAnnotation",
 368         "svid",
 369         "seqFeatures"
 370     ]
 371 }
 372             docson.templateBaseUrl="templates";
 373             docson.doc("doc", schema);
 374         });
 375     });
 376 </script>
 377 </body>
 378 </html>
 379
 380
 381