-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathbody.tex
1449 lines (1140 loc) · 62.9 KB
/
body.tex
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
% -*- TeX-master: "main"; fill-column: 72 -*-
\section{Introduction}
\label{introduction}
The Systems Biology Graphical Notation (SBGN) aims to standardize the graphical/visual representation of biochemical and cellular processes \citep{sbgn:2009, Junker2012, Czauderna2017, Toure2018}. The goal of SBGN is to represent networks of biochemical interactions in a standard, unambiguous way to foster efficient and accurate representation, visualization, storage, exchange, and reuse of various types of biological knowledge (e.g., gene regulation, metabolism, and cellular signaling). SBGN is defined by comprehensive sets of symbols with precise semantics, together with detailed syntactic rules defining their use and interpretation. Overall, SBGN is made up of three complementary visual languages.
\begin{itemize}
\item The SBGN Process Description (PD) language \citep{Rougny2019} visualizes the temporal courses of the molecular processes and interactions taking place between biochemical entities in a particular system. This type of diagram depicts how entities transition from one form to another as a result of different influences to describe the temporal aspects of a biological system. Nodes describe entity pools (e.g., metabolites, proteins, and complexes) and processes (e.g., associations and influences). The edges describe relationships between the nodes (e.g., consumption and stimulation).
\item The SBGN Entity Relationship (ER) language \citep{Sorokin2015} visualizes the relationships in which a given entity can participate without regard for the temporal aspects. Relationships can be seen as rules describing the influences of entity pool nodes on relationships. Relationships are independent, and this independence is essential in avoiding the combinatorial explosion inherent to process description diagrams. The nodes describe biological entities such as proteins and complexes, and the edges between them describe interactions, relationships and/or influences (e.g., complex formation, stimulation, and inhibition).
\item The SBGN Activity Flow (AF) language \citep{Mi2015} visualizes the influences between the activities displayed by molecular entities, rather than the entities themselves. Nodes in SBGN AF diagrams describe the biological activities of the entities such as protein kinase activity or binding activity. The edges describe influences between the activities (e.g., positive influence and negative influence).
\end{itemize}
Formal specification describing the visual languages of SBGN, as well as other materials and software, are available from the SBGN project web site, \url{http://sbgn.org}. The SBGN project seeks a standardized intermediate format---a \emph{lingua franca}---enabling communication of the essential aspects of the visual representations of networks of biochemical interactions.
SBGN is defined neutrally concerning programming languages and software encoding; however, it is oriented primarily towards allowing models to be encoded using XML, the eXtensible Markup Language~\citep{bray:2004}. This document contains specifications of how SBGN maps should be serialized in XML. Note that this specification is related to all three SBGN languages, with classes such as Glyph and Arc having the same definition and attributes across all languages. Unlike SBGN, SBGNML does not deal with biological meaning, but, instead, focuses on the computational representation of SBGN graphics, so it is comparable with graphical exchange standards like GraphML\footnote{\url{http://graphml.graphdrawing.org/}} and SVG\footnote{\url{https://www.w3.org/Graphics/SVG/}}.
This document describes Milestone 3 (known as Version 0.3) of SBGNML. The previous version of this work (SBGNML Milestone 2) was released in 2011 \citep{Iersel2012}. Below is a list of major changes from previous work:
\begin{itemize}
\item The ability to store multiple SBGN maps within a single file. An ``id'' attribute has added as an identifier for individual SBGN maps to disambiguate them.
\item The ``language'' attribute has been deprecated to add a ``version'' attribute. The value for this attribute is a URI identifier that gives metadata information about the SBGN language, level, and version of the map.
\item Complete support for submaps has been implemented with the inclusion of two attributes: ``mapRef'' and ``tagRef''.
\item The SBGN AF ``perturbation'' glyph, which was an activity node, has been deprecated and is now a unit of information.
\item The support of colors and other annotations through extensions enables the storage of rendering information and biological annotations (e.g., database identifiers).
\end{itemize}
The definition of the model description language presented here does not specify \emph{how} programs should communicate or read/write SBGN. We assume that for diagram editing software to communicate a model encoded in SBGN, the program will have to translate its internal data structures to and from SBGNML, use a suitable transmission medium and protocol, and to provide any further necessary infrastructure. However, these issues are outside the scope of this document. The software library libSBGN \citep{Iersel2012} was developed for reading, writing, and manipulating SBGN maps stored in SBGNML format. A broad set of software tools support SBGNML, including modeling software CellDesigner \citep{Balaur2020}, SBGN editors Newt \citep{Sari2015}, Krayon for SBGN\footnote{\url{https://github.com/draeger-lab/krayon4sbgn}}, and SBGN-ED \citep{Czauderna2010}. STON \citep{Toure2016} and ySBGN\footnote{\url{https://github.com/sbgn/ySBGN}} provide conversion between SBNGML and GraphML/Neo4j, respectively. The software EscherConverter provides an SBGN viewer and a bidirectional converter for metabolic maps in JSON format and SBGNML \citep{King2015a}. Numerous databases (Reactome \citep{Croft2011}, Panther Pathways \citep{Mi2017}, Pathways Commons \citep{Rodchenkov2020}, PathWhiz \citep{Pon2015}, Path2Models \citep{Buechel2013b}, MetaCrop \citep{Schreiber2012} and Atlas of Cancer Signaling Networks \citep{Kuperstein2015}) provide SBGNML export.
\section{Package syntax and semantics}
\subsection{Document conventions} \label{conventions}
We use Unified Modeling Language (UML) version 2.0 (\citealt{dennis:2015}) class diagram notation to
define the constructs provided by this package. We first provide an overall view of the various data types and constructs along with their relationships, followed by a more local view of the constructs and their relationships in associated sections.
In this section, we define the syntax and semantics of the
\SystemsBiologyGraphicalNotationMarkupLanguagePackage. We expound on the various data types and constructs
defined in this package, then in \sec{examples}; we provide complete
examples of using the constructs in sample SBGN models.
\subsection{Namespace URI and other declarations necessary for using this package}
\label{xml-namespace}
SBGNML is identified uniquely by an XML namespace URI. An SBGN document must declare the following is the namespace URI for this version of the
\SystemsBiologyGraphicalNotationMarkupLanguagePackage for SBGNML version~0.3:
\begin{center}
\uri{http://sbgn.org/libsbgn/0.3}
\end{center}
\begin{figure}[ht!]
\centering
\includegraphics[width=\textwidth]{figures/sbgnml_version_0_complete.pdf}\\
\caption{A UML representation of the \SbgnmlPackage. See
\ref{conventions} for conventions related to this figure. }
\label{fig:sbgnml_version_0_complete}
\end{figure}
\subsection{Primitive data types}
\label{primitive-types}
Section~3.1 of the SBML Level~3 specification \citep{Hucka2019} defines several
primitive data types and also uses XML Schema 1.0 data types
\citep{biron:2000}. We assume and use some of them in the rest of this
specification, particularly \primtype{float}, \primtype{ID},
\primtype{IDREF}, and \primtype{string}. The
\SystemsBiologyGraphicalNotationMarkupLanguagePackage defines other
primitive types as described below.
\subsubsection{Type \fixttspace\primtypeNC{Language}}
\begin{figure}[ht!]
\centering
\includegraphics[scale=0.7]{figures/sbgnml_type_enum_language_uml.pdf}\\
\caption{A UML representation of the \Language type for the
\SbgnmlPackage. See \ref{conventions} for conventions related to this
figure. }
\label{fig:sbgnml_type_enum_language_uml}
\end{figure}
The \primtype{Language} is an enumeration of values used to specify which SBGN Language is encoded on the \Map element.
The possible values are \const{process description}, \const{entity relationship}, and \const{activity flow}.
\subsubsection{Type \fixttspace\primtypeNC{Class}}
\begin{figure}[ht!]
\centering
\includegraphics[scale=0.7]{figures/sbgnml_type_enum_class_uml.pdf}\\
\caption{A UML representation of the \Class type for the \SbgnmlPackage.
See \ref{conventions} for conventions related to this figure. }
\label{fig:sbgnml_type_enum_class_uml}
\end{figure}
The \primtype{Class} is an enumeration of values used to specify what type a \Glyph is encoding.
The possible values are \const{unspecified entity}, \const{simple
chemical}, \const{macromolecule}, \const{nucleic acid feature},
\const{simple chemical multimer}, \const{macromolecule multimer},
\const{nucleic acid feature multimer}, \const{complex}, \\ \const{complex multimer}, \const{source and sink}, \const{perturbation},
\const{biological activity}, \const{perturbing agent}, \\
\const{compartment}, \const{submap}, \const{tag}, \const{terminal},
\const{process}, \const{omitted process}, \const{uncertain process},
\const{association}, \const{dissociation}, \const{phenotype},
\const{and}, \const{or}, \const{not}, \const{equivalence}, \const{state variable},
\const{unit of information}, \const{entity}, \const{outcome},
\const{interaction}, \const{influence target}, \const{annotation},
\const{variable value}, \const{implicit xor}, \const{delay}, \\ \const{existence}, \const{location}, \const{cardinality}, and
\const{observable}.
\subsubsection{Type \fixttspace\primtypeNC{Orientation}}
\begin{figure}[ht!]
\centering
\includegraphics[scale=0.7]{figures/sbgnml_type_enum_orientation_uml.pdf}\\
\caption{A UML representation of the \Orientation type for the
\SbgnmlPackage. See \ref{conventions} for conventions related to this
figure. }
\label{fig:sbgnml_type_enum_orientation_uml}
\end{figure}
The \primtype{Orientation} is an enumeration of values used to express how to draw asymmetric glyphs.
The orientation of Process Nodes is either ``horizontal'' or ``vertical''. It refers to an (imaginary) line connecting the two in/out sides of the PN.
The possible values are \const{horizontal}, \const{vertical},
\const{left}, \const{right}, \const{up}, and \const{down}.
The value refers to the direction at which the arrow side of the glyph is pointing.
\subsubsection{Type \fixttspace\primtypeNC{EntityType}}
\begin{figure}[ht!]
\centering
\includegraphics[scale=0.7]{figures/sbgnml_type_enum_entitytype_uml.pdf}\\
\caption{A UML representation of the \EntityType type for the
\SbgnmlPackage. See \ref{conventions} for conventions related to this
figure. }
\label{fig:sbgnml_type_enum_entitytype_uml}
\end{figure}
The \primtype{EntityType} is an enumeration of values used for Activity Flow maps
that specifies the auxiliary unit to display.
The possible values are \const{unspecified entity}, \const{simple
chemical}, \const{macromolecule}, \const{nucleic acid feature}, and
\const{complex}.
\subsubsection{Type \fixttspace\primtypeNC{ArcGroupType}}
\begin{figure}[ht!]
\centering
\includegraphics[scale=0.7]{figures/sbgnml_type_enum_arcgrouptype_uml.pdf}\\
\caption{A UML representation of the \ArcGroupType type for the
\SbgnmlPackage. See \ref{conventions} for conventions related to this
figure. }
\label{fig:sbgnml_type_enum_arcgrouptype_uml}
\end{figure}
The \primtype{ArcGroupType} is an enumeration of values used to define the semantic of an \ArcGroup.
The only possible value is \const{interaction}.
\subsubsection{Type \fixttspace\primtypeNC{ArcClass}}
\begin{figure}[ht!]
\centering
\includegraphics[scale=0.7]{figures/sbgnml_type_enum_arcclass_uml.pdf}\\
\caption{A UML representation of the \ArcClass type for the
\SbgnmlPackage. See \ref{conventions} for conventions related to this
figure. }
\label{fig:sbgnml_type_enum_arcclass_uml}
\end{figure}
The \primtype{ArcClass} is an enumeration of values used to define the semantic of an \Arc.
The possible values are \const{production}, \const{consumption},
\const{catalysis}, \const{modulation}, \const{stimulation},
\const{inhibition}, \const{assignment}, \const{absolute inhibition},
\const{absolute stimulation}, \const{positive influence},
\const{negative influence}, \const{unknown influence},
\const{equivalence arc}, \const{necessary stimulation}, and \const{logic
arc}.
% ---------------------------------------------------------
\subsection{The \class{SBGN} class}
\label{document-class}
\begin{figure}[ht!]
\centering
\includegraphics[scale=1.0]{figures/sbgnml_document_uml.pdf}\\
\caption{A UML representation of the \Document class for the
\SbgnmlPackage. See \ref{conventions} for conventions related to this
figure. }
\label{fig:sbgnml_document_uml}
\end{figure}
The \Document object shown in \ref{fig:sbgnml_document_uml} corresponds to the XML element \token{sbgn}.
The \token{sbgn} element is the root of any SBGNML document.
The \Document object derives from the \SbgnBase class and thus inherits all attributes and elements that are present for this class.
A \Document contains one or more \Map elements.
\paragraph{Example}
The following example shows an \token{sbgn} element definition.
\begin{example}
<sbgn ...>
...
</sbgn>\end{example}
% ---------------------------------------------------------
\subsection{The \class{Map} class}
\label{map-class}
\begin{figure}[ht!]
\centering
\includegraphics[scale=1.0]{figures/sbgnml_map_uml.pdf}\\
\caption{A UML representation of the \Map class for the \SbgnmlPackage.
See \ref{conventions} for conventions related to this figure. }
\label{fig:sbgnml_map_uml}
\end{figure}
The \token{map} element describes a single SBGN map.
The \Map object derives from the \SbgnBase class and thus inherits all
attributes and elements that are present for this class.
A \Map contains exactly one \BBox element.
A \Map may contain one or more:
\begin{itemize}
\item \Glyph elements.
\item \Arc elements.
\item \ArcGroup elements.
\end{itemize}
In addition, the \Map object has the following attributes.
\paragraph{The \fixttspace\token{id} attribute}
A \Map has an optional attribute \token{id} of type \primtype{ID}.
\paragraph{The \fixttspace\token{language} attribute}
A \Map has an optional attribute \token{language} of type
string. While the type is of \primtype{string}, the values should be one of the ones defined in \primtype{Language}, i.e., one of the following:
\begin{itemize}
\item \token{process description}
\item \token{entity relationship}
\item \token{activity flow}
\end{itemize}
The \token{language} attribute has been deprecated as of Version~0.3, in favor of the \token{version} attribute. One of the attributes has to be defined on a map element.
\paragraph{The \fixttspace\token{version} attribute}
A \Map has an optional attribute \token{version} of type
\primtype{URI} with the URL to the SBGN language and version it is referring to. The attribute can take one of the following values:
\begin{itemize}
\item \url{http://identifiers.org/combine.specifications/sbgn.pd.level-1.version-2.0}
\item \url{http://identifiers.org/combine.specifications/sbgn.pd.level-1.version-1.3}
\item \url{http://identifiers.org/combine.specifications/sbgn.pd.level-1.version-1.2}
\item \url{http://identifiers.org/combine.specifications/sbgn.pd.level-1.version-1.1}
\item \url{http://identifiers.org/combine.specifications/sbgn.pd.level-1.version-1.0}
\item \url{http://identifiers.org/combine.specifications/sbgn.pd.level-1.version-1}
\item \url{http://identifiers.org/combine.specifications/sbgn.er.level-1.version-2}
\item \url{http://identifiers.org/combine.specifications/sbgn.er.level-1.version-1.2}
\item \url{http://identifiers.org/combine.specifications/sbgn.er.level-1.version-1.1}
\item \url{http://identifiers.org/combine.specifications/sbgn.er.level-1.version-1.0}
\item \url{http://identifiers.org/combine.specifications/sbgn.er.level-1.version-1}
\item \url{http://identifiers.org/combine.specifications/sbgn.af.level-1.version-1.2}
\item \url{http://identifiers.org/combine.specifications/sbgn.af.level-1.version-1.0}
\item \url{http://identifiers.org/combine.specifications/sbgn.af.level-1.version-1}
\end{itemize}
The \token{version} attribute should be used in favor of the \token{language} attribute. One of the attributes has to be defined on a map element.
\paragraph{Example}
The following example shows an abbreviated SBGN \Map definition within an sbgn element definition. The example shows a \Map with a \token{version} attribute.
\begin{example}
<sbgn ...>
...
<map id="m1" version="http://identifiers.org/combine.specifications/sbgn.pd.level-1.version-1.3">
...
</map>
...
</sbgn>
\end{example}
% ---------------------------------------------------------
\subsection{The \class{Point} class}
\label{point-class}
\begin{figure}[ht!]
\centering
\includegraphics[scale=1.0]{figures/sbgnml_point_uml.pdf}\\
\caption{A UML representation of the \Point class for the
\SbgnmlPackage. See \ref{conventions} for conventions related to this
figure. }
\label{fig:sbgnml_point_uml}
\end{figure}
The \Point object encodes \token{x} and \token{y} coordinates.
The origin is located in the top-left corner of the map.
There is no unit: proportions must be preserved, but the maps can be drawn at any scale. In the example test files, to obtain a drawing similar to the reference \value{*.png} file, values in the corresponding \value{*.sbgn} file should be read as pixels.
Additionally, it may contain zero, one, or two child \Point objects, which can be used to encode quadratic or cubic B\'{e}zier points.
The \Point object derives from the \SbgnBase class and thus inherits all
attributes and elements that are present for this class.
In addition, the \Point object has the following attributes.
\paragraph{The \fixttspace\token{x} attribute}
A \Point has a required attribute \token{x} of type \primtype{double}. It represents the Cartesian \token{x} coordinate horizontally, increasing from left to right.
\paragraph{The \fixttspace\token{y} attribute}
A \Point has a required attribute \token{y} of type \primtype{double}. It represents the Cartesian \token{y} coordinate vertically, increasing from top to bottom.
\paragraph{Example}
The following example shows a \Point definition within an abbreviated SBGN map definition. The example shows a \Point on a \Callout.
\begin{example}
<map ...>
...
<glyph ...>
...
<callout ...>
<point x="100.0" y="200.0"/>
</callout>
...
</glyph>
...
</map>
\end{example}
% ---------------------------------------------------------
\subsection{The \class{BBox} class}
\label{bbox-class}
\begin{figure}[ht!]
\centering
\includegraphics[scale=1.0]{figures/sbgnml_bbox_uml.pdf}\\
\caption{A UML representation of the \BBox class for the \SbgnmlPackage.
See \ref{conventions} for conventions related to this figure. }
\label{fig:sbgnml_bbox_uml}
\end{figure}
\BBox encodes the bounding box of its parent element.
The \BBox object derives from the \SbgnBase class and thus inherits all
attributes and elements that are present for this class.
In addition, the \BBox object has the following attributes.
\paragraph{The \fixttspace\token{x} attribute}
A \BBox has a required attribute \token{x} of type \primtype{double}. It represents the Cartesian \token{x} coordinate horizontally, increasing from left to right.
\paragraph{The \fixttspace\token{y} attribute}
A \BBox has a required attribute \token{y} of type \primtype{double}. It represents the Cartesian \token{y} coordinate vertically, increasing from top to bottom.
\paragraph{The \fixttspace\token{w} attribute}
A \BBox has a required attribute \token{w} of type
\primtype{double}. It encodes the width of the bounding box.
\paragraph{The \fixttspace\token{h} attribute}
A \BBox has a required attribute \token{h} of type
\primtype{double}. It encodes the height of the bounding box.
\paragraph{Example}
The following example shows a \BBox definition within an abbreviated SBGN map definition. The example shows the \BBox on a \Glyph.
\begin{example}
<map ...>
...
<glyph ...>
...
<bbox x="10.0" y="10.0" w="100.0" h="50.0"/>
...
</glyph>
...
</map>
\end{example}
% ---------------------------------------------------------
\subsection{The \class{Label} class}
\label{label-class}
\begin{figure}[ht!]
\centering
\includegraphics[scale=1.0]{figures/sbgnml_label_uml.pdf}\\
\caption{A UML representation of the \Label class for the
\SbgnmlPackage. See \ref{conventions} for conventions related to this
figure. }
\label{fig:sbgnml_label_uml}
\end{figure}
The \Label element describes the text accompanying a glyph.
The \Label object derives from the \SbgnBase class and thus inherits all
attributes and elements that are present for this class.
A \Label may contain exactly one \BBox element.
In addition, the \Label object has the following attributes.
\paragraph{The \fixttspace\token{id} attribute}
A \Label has an optional attribute \token{id} of type \primtype{ID}.
\paragraph{The \fixttspace\token{text} attribute}
A \Label has a required attribute \token{text} of type
\primtype{string}. The text element is a simple string. Multi-line labels are allowed. Line breaks are encoded as \token{\&\#xA;} as specified by the XML standard.
\paragraph{The \BBox element of a \Label}
The \token{bbox} element of a label is optional. When no bounding box is defined, the bounding box of the parent glyph is inherited. The label should be drawn centered horizontally and vertically in the bounding box.
When the bounding box is inherited, the label may spill outside (just like it can spill outside its parent glyph).
An explicit \token{bbox} provides more definite information regarding what surface the label should cover. It defines an upper boundary outside of which the label should (ideally) not spill. It also represents a preferred size: the surface covered by the label can be smaller, but should ideally be as close as possible to the bounding box.
In most glyph classes (EPNs, unit of information, etc.), the label is supposed to be centered, so the bounding box is usually omitted (unless there is a specific hint to be shared concerning the area the label should ideally cover).
However, the label of a compartment or a complex can be drawn anywhere inside the glyph, so these should preferably have an explicit bounding box.
\paragraph{Example}
The following example shows a \Label definition within an abbreviated SBGN map definition. The example shows the \Label without a \token{bbox} element on a \Glyph.
\begin{example}
<map ...>
...
<glyph ...>
...
<label text="label"/>
...
</glyph>
...
</map>
\end{example}
% ---------------------------------------------------------
\subsection{The \class{Glyph} class}
\label{glyph-class}
\begin{figure}[ht!]
\centering
\includegraphics[scale=1.0]{figures/sbgnml_glyph_uml.pdf}\\
\caption{A UML representation of the \Glyph class for the
\SbgnmlPackage. See \ref{conventions} for conventions related to this
figure. }
\label{fig:sbgnml_glyph_uml}
\end{figure}
The glyph element is:
\begin{itemize}
\item {either a stand-alone, high-level SBGN node (an EPN, PN, compartment, etc.)}
\item {or a sub-node (state variable, unit of information, inside of a complex, etc.)}
\end{itemize}
In the first case, it is a child of the map element.
In the second case, it is a child of another glyph element.
The \Glyph object derives from the \SbgnBase class and thus inherits all
attributes and elements that are present for this class.
A \Glyph contains:
\begin{itemize}
\item exactly one \BBox element that describes the bounding box of the glyph.
\end{itemize}
A \Glyph may contain:
\begin{itemize}
\item exactly one \Label element that describes the text accompanying the glyph.
\item exactly one \State element that carries the information of a state variable.
\item exactly one \Glyph element called ``clone'', indicating that the Glyph carries a clone marker. The label element of the child glyph can be used to place text in the clone marker. \ref{fig:glyph_clone_example} shows an example.
\item exactly one \Callout element. The callout element is only used for glyphs of class \const{annotation}. It contains the coordinate of the point where the annotation points to, as well as a reference to the element that is pointed to.
\item exactly one \Entity element. The entity is only used in Activity Flow maps. It can only be used on a unit of information glyph on a biological activity glyph, where it is compulsory. It is used to indicate the shape of this unit of information.
%\item exactly one \Entity element. The entity is only used in Activity Flow maps. It can only be used on a unit of information glyph on a biological activity glyph, where it is compulsory. It is used to indicate the shape of this unit of information.
\item zero or more child \Glyph elements. These will be, for example, used by glyphs of class \const{complex} and hold the individual components.
\item zero or more child \Port elements describing the anchor points for this glyph.
\end{itemize}
%A \Glyph contains:
%\begin{itemize}
% \item exactly one \Glyph element called ``clone'', when it is set, it indicates that the Glyph carries a clone marker. The label element of the child glyph can be used to place text in the clone marker.
% \item exactly one \BBox element that describes the bounding box of the glyph.
%\end{itemize}
%A \Glyph can contain:
%\begin{itemize}
% \item zero or more child \Glyph elements. This will be for example used by glyphs of class \const{complex} and hold the individual components.
% \item zero or more child \Port elements describing the anchor points for this glyph.
%\end{itemize}
In addition, the \Glyph object has the following attributes.
\paragraph{The \fixttspace\token{id} attribute}
A \Glyph has a required attribute \token{id} of type \primtype{ID}. The \token{id} attribute (\token{xsd:ID}) of a glyph can be referred to, e.g., as a source by arc elements, a target by arc elements or callout elements, by other glyphs if the glyph is of the class \const{compartment}.
The \token{xsd:ID} type is an alphanumeric identifier, starting with a letter.
It is recommended to generate meaningless IDs (e.g., ``\token{glyph1234}'') and avoid IDs with meaning (e.g., ``\token{epn\_ethanol}'')
\paragraph{The \fixttspace\token{class} attribute}
A \Glyph has a required attribute \token{class} of type
\primtype{string}. While the type is of \primtype{string}, the values should be one of the ones defined in \primtype{Class}.
\paragraph{The \fixttspace\token{compartmentRef} attribute}
A \Glyph has an optional attribute \token{compartmentRef} of type
\primtype{IDREF}.
The \token{compartmentRef} is a reference to the ID of the compartment that this glyph is part of. It should only be used if there is at least one explicit compartment present on the map. Compartments are only used in PD and AF, and thus this attribute as well. For PD, this should be used only for EPNs.
In case there are no compartments, entities that can have a location, such as EPNs, are implicit members of an invisible compartment that encompasses the whole map. In that case, this attribute must be omitted.
\paragraph{The \fixttspace\token{compartmentOrder} attribute}
A \Glyph has an optional attribute \token{compartmentOrder} of type
\primtype{double}.
The \token{compartmentOrder} attribute can be used to define a drawing order for compartments. It enables tools to draw compartments in the correct order, especially in the case of overlapping compartments. Compartments are only used in PD and AF, and, thus, this attribute as well.
The attribute is of type \token{float}, and the attribute value has not to be unique.
Compartments with higher \token{compartmentOrder} are drawn on top. The attribute is optional and should only be used for compartments.
\paragraph{The \fixttspace\token{orientation} attribute}
A \Glyph has an optional attribute \token{orientation} of type string. While the type is of \primtype{string}, the values should be one of the ones defined in \primtype{Orientation}. The \token{orientation} attribute is used to express how to draw asymmetric glyphs.
The orientation of Process Nodes is either \token{horizontal} or \token{vertical}. It refers to an (imaginary) line connecting the two in/out sides of the PN.
The orientation of Tags can be \token{left}, \token{right}, \token{up}, or \token{down}. It refers to the direction at which the arrow side of the glyph is pointing.
\paragraph{Example}
The following example shows a \Glyph definition within an abbreviated SBGN map definition. The example shows a \Glyph of class \const{macromolecule} with an optional attribute \token{compartmentRef}. \ref{fig:glyph_example} shows the corresponding visual representation.
\begin{example}
<map ...>
...
<glyph id="glyph1" class="macromolecule" compartmentRef="glyphcomp1">
<label text="Glucose"/>
<bbox x="10.0" y="10.0" w="100.0" h="50.0"/>
</glyph>
...
</map>
\end{example}
\begin{figure}[!ht]
\centering
\includegraphics[scale=0.9]{figures/glyph_example.pdf}
\caption{Visual representation of a \Glyph of the class \const{macromolecule}.}
\label{fig:glyph_example}
\end{figure}
\paragraph{Example Clone Marker}
The following example shows a \Glyph definition within an abbreviated SBGN map definition. The example shows a \Glyph of class \const{macromolecule} with an optional attribute \token{compartmentRef} and a clone marker. \ref{fig:glyph_clone_example} shows the corresponding visual representation.
\begin{example}
<map ...>
...
<glyph id="glyph1" class="macromolecule" compartmentRef="glyphcomp1">
<clone>
<label text="marker">
<bbox x="10.0" y="47.5" w="100.0" h="12.5"/>
</label>
</clone>
<label text="Glucose"/>
<bbox x="10.0" y="10.0" w="100.0" h="50.0"/>
</glyph>
...
</map>
\end{example}
\begin{figure}[!ht]
\centering
\includegraphics[scale=0.9]{figures/glyph_clone_example.pdf}
\caption{Visual representation of a \Glyph of the class \const{macromolecule} with a clone marker.}
\label{fig:glyph_clone_example}
\end{figure}
% ---------------------------------------------------------
\subsection{The \class{Port} class}
\label{port-class}
\begin{figure}[ht!]
\centering
\includegraphics[scale=1.0]{figures/sbgnml_port_uml.pdf}\\
\caption{A UML representation of the \Port class for the \SbgnmlPackage.
See \ref{conventions} for conventions related to this figure. }
\label{fig:sbgnml_port_uml}
\end{figure}
A port element describes an anchor point, which arc elements can refer to as a source or target. It consists of absolute 2D Cartesian coordinates and a unique id attribute.
Two port elements are required for process nodes and logical operators (\const{and}, \const{or}, \const{not}, and \const{equivalence}). They represent the extremity of the two ``arms'' which protrude on both sides of the core of the glyph (= square or circle shape).
The \Port object derives from the \SbgnBase class and, thus, inherits all
attributes and elements that are present for this class.
In addition, the \Port object has the following attributes.
\paragraph{The \fixttspace\token{id} attribute}
A \Port has a required attribute \token{id} of type \primtype{ID}.
\paragraph{The \fixttspace\token{x} attribute}
A \Point has a required attribute \token{x} of type \primtype{double}. It represents the Cartesian \token{x} coordinate horizontally, increasing from left to right.
\paragraph{The \fixttspace\token{y} attribute}
A \Point has a required attribute \token{y} of type \primtype{double}. It represents the Cartesian \token{y} coordinate vertically, increasing from top to bottom.
\paragraph{Example}
The following example shows a \Port definition within an abbreviated SBGN map definition. The example shows two \Port{}s on a \Glyph.
\begin{example}
<map ...>
...
<glyph id="glyph1" ...>
...
<port id="glyph1.1" x="100.0" y="100.0"/>
<port id="glyph1.2" x="120.0" y="100.0"/>
...
</glyph>
...
</map>
\end{example}
% ---------------------------------------------------------
\subsection{The \class{State} class}
\label{state-class}
\begin{figure}[ht!]
\centering
\includegraphics[scale=1.0]{figures/sbgnml_state_uml.pdf}\\
\caption{A UML representation of the \State class for the
\SbgnmlPackage. See \ref{conventions} for conventions related to this
figure. }
\label{fig:sbgnml_state_uml}
\end{figure}
The state element should only be used for state variables. It replaces the label element used for other glyphs. It describes the text to be drawn inside the state variable.
The \State object derives from the \SbgnBase class and thus inherits all
attributes and elements that are present for this class.
In addition, the \State object has the following attributes.
\paragraph{The \fixttspace\token{variable} attribute}
A \State has an optional attribute \token{variable} of type
\primtype{string}.
It describes the site where the modification described by the value attribute occurs. It is:
\begin{itemize}
\item optional when there is only one state variable on the parent EPN
\item required when there is more than one state variable on the parent EPN
\end{itemize}
\paragraph{The \fixttspace\token{value} attribute}
A \State has an optional attribute \token{value} of type
\primtype{string}. It represents the state of the variable. It can be:
\begin{itemize}
\item either from a predefined set of strings (e.g., ``P'', ``S'', etc.) which correspond to specific SBO terms (cf. SBGN specifications)
\item or any arbitrary \primtype{string}.
\end{itemize}
\paragraph{Example}
The following example shows a \State definition within an abbreviated SBGN map definition. The example depicts two \State{}s on a \Glyph of the class \const{macromolecule}, one \State with a \token{value} attribute and a \token{variable} attribute and one \State with a \token{variable} attribute only.
\vref{fig:state_example} shows the corresponding visual representation.
\begin{example}
<map ...>
...
<glyph id="glyph1" class="entity">
<label text="CaMKII"/>
<bbox x="10.0" y="20.0" w="140.0" h="50.0"/>
<glyph id="glyph1a" class="state variable">
<state variable="T286" value="P"/>
<bbox x="13.5" y="11.0" w="63.0" h="18.0"/>
</glyph>
<glyph id="glyph1b" class="state variable">
<state variable="T306"/>
<bbox x="93.5" y="11.0" w="43.0" h="18.0"/>
</glyph>
</glyph>
...
</map>
\end{example}
\begin{figure}[!ht]
\centering
\includegraphics[scale=0.9]{figures/state_example.pdf}
\caption{Visual representation of two \State{}s on a \Glyph of the class \const{macromolecule}.}
\label{fig:state_example}
\end{figure}
% ---------------------------------------------------------
\subsection{The \class{Callout} class}
\label{callout-class}
\begin{figure}[ht!]
\centering
\includegraphics[scale=1.0]{figures/sbgnml_callout_uml.pdf}\\
\caption{A UML representation of the \Callout class for the
\SbgnmlPackage. See \ref{conventions} for conventions related to this
figure. }
\label{fig:sbgnml_callout_uml}
\end{figure}
Callouts are used in the case of glyphs of class \const{annotation}. The callout is always optional. It can be used to show which element the callout points to.
The \Callout object derives from the \SbgnBase class and thus inherits all
attributes and elements that are present for this class.
A \Callout contains at most one \Point element.
In addition, the \Callout object has the following attributes.
\paragraph{The \fixttspace\token{target} attribute}
A \Callout has an optional attribute \token{target} of type
\primtype{IDREF}. If specified, it references either a \Glyph or an \Arc in the \Map.
\paragraph{Example}
The following example shows a \Callout definition within an abbreviated SBGN map definition. The example depicts a \Callout on a \Glyph of class \const{annotation}, pointing to a \Glyph of the class \const{macromolecule}. \ref{fig:callout_example} contains the corresponding visual representation.
\begin{example}
<map ...>
...
<glyph id="g1" class="macromolecule">
<label text="label"/>
<bbox x="10.0" y="95.0" w="100.0" h="50.0"/>
</glyph>
<glyph id="g2" class="annotation">
<callout target="g1">
<point x="95.0" y="110.0"/>
</callout>
<label text="annotation"/>
<bbox x="95.0" y="10.0" w="100.0" h="100.0"/>
</glyph>
...
</map>
\end{example}
\begin{figure}[!ht]
\centering
\includegraphics[scale=0.9]{figures/callout_example.pdf}
\caption{Visual representation of a \Callout on a \Glyph of class \const{annotation} pointing to a \Glyph of the class \const{macromolecule}.}
\label{fig:callout_example}
\end{figure}
% ---------------------------------------------------------
\subsection{The \class{Entity} class}
\label{entity-class}
\begin{figure}[ht!]
\centering
\includegraphics[scale=1.0]{figures/sbgnml_entity_uml.pdf}\\
\caption{A UML representation of the \Entity class for the
\SbgnmlPackage. See \ref{conventions} for conventions related to this
figure. }
\label{fig:sbgnml_entity_uml}
\end{figure}
An entity is only used in Activity Flow maps. It should be placed on a unit of information subglyph of an activity glyph and is used to indicate the entity that performs the activity.
The \Entity object derives from the \SbgnBase class and thus inherits all
attributes and elements that are present for this class.
In addition, the \Entity object has the following attributes.
\paragraph{The \fixttspace\token{name} attribute}
An \Entity has a required attribute \token{name} of type
\primtype{string}. %An entity is only used in Activity Flow maps. It should be placed on a sub-glyph of an activity glyph, and is used to indicate the entity that performs the activity.
\paragraph{Example}
The following example shows an \Entity definition within an abbreviated SBGN map definition. The example shows an \Entity with the \token{name} ``macromolecule'' placed on a \Glyph of class \const{biological activity}. \ref{fig:entity_example} shows the corresponding visual representation.
\begin{example}
<map ...>
...
<glyph id="glyph1" class="biological activity">
<label text="Activity"/>
<bbox x="10.0" y="20.0" w="100.0" h="50.0"/>
<glyph id="glyph1a" class="unit of information">
<label text="Entity"/>
<entity name="macromolecule"/>
<bbox x="13.0" y="11.0" w="44.0" h="18.0"/>
</glyph>
</glyph>
...
</map>
\end{example}
\begin{figure}[!ht]
\centering
\includegraphics[scale=0.9]{figures/entity_example.pdf}
\caption{Visual representation of an \Entity on a \Glyph of the class \const{biological activity}.}
\label{fig:entity_example}
\end{figure}
% ---------------------------------------------------------
\subsection{The \class{Arc} class}
\label{arc-class}
\begin{figure}[ht!]
\centering
%\includegraphics[scale=0.7]{figures/sbgnml_arc_uml.pdf}\\
\includegraphics[width=\textwidth]{figures/sbgnml_arc_uml.pdf}\\
\caption{A UML representation of the \Arc class for the \SbgnmlPackage.
See \ref{conventions} for conventions related to this figure. }
\label{fig:sbgnml_arc_uml}
\end{figure}
The arc element describes an SBGN arc between two SBGN nodes. It contains:
\begin{itemize}
\item{For PD maps: an optional stoichiometry marker,}
\item {For ER maps: an optional cardinality marker (e.g., ``cis'' or ``trans''), zero or more ports (influence targets), and zero or more outcomes,}
\item {a mandatory source and target (glyph or port),}
\item {a geometric description of its whole path from start to end. This path can involve any number of straight lines or quadratic/cubic B\'{e}zier curves.}
\end{itemize}
The \Arc object derives from the \SbgnBase class and thus inherits all
attributes and elements that are present for this class.
An \Arc can contain zero or more child \Glyph elements. These can be a stoichiometry marker (PD maps), a cardinality marker (ER maps), or outcome glyphs (ER maps).
An \Arc contains at the very least one \Point element with an element named \token{start} that represents the start point of the arc, and another \Point element with element name \token{end} as the endpoint. Additionally, it may contain any number of \Point elements with element name \token{next} that represent bend points along the way from start to end.
An \Arc may also contain any number of \Port elements.
In addition, the \Arc object has the following attributes.
\paragraph{The \fixttspace\token{id} attribute}
An \Arc has a required attribute \token{id} of type \primtype{ID}.
\paragraph{The \fixttspace\token{class} attribute}
An \Arc has a required attribute \token{class} of type
\primtype{string}. It describes what kind of an \Arc this element represents. While the data type is of \primtype{string}, the values ought to be from the \primtype{ArcClass} enumeration.
\paragraph{The \fixttspace\token{source} attribute}
An \Arc has a required attribute \token{source} of type
\primtype{IDREF}. It specifies the source element for this arc.
\paragraph{The \fixttspace\token{target} attribute}
An \Arc has a required attribute \token{target} of type
\primtype{IDREF}. It specifies the target element for this arc.
\paragraph{Example}
The following example shows an \Arc definition within an abbreviated SBGN map definition. The example shows one \Arc of class \const{consumption} and one \Arc of class \const{production}. \ref{fig:arc_example} shows the corresponding visual representation.
\begin{example}
<map ...>
...
<arc id="arc1" class="consumption" source="glyph1" target="glyph2.1">
<start x="50.0" y="25.0"/>
<end x="100.0" y="25.0"/>
</arc>
...
<arc id="arc2" class="production" source="glyph2.2" target="glyph3">
<start x="140.0" y="25.0"/>
<end x="190.0" y="25.0"/>
</arc>
...
</map>
\end{example}
\begin{figure}[!ht]
\centering
\includegraphics[scale=0.9]{figures/arc_example.pdf}
\caption{Visual representation of an \Arc of class \const{consumption} (left) and an \Arc of class \const{production} (right).}
\label{fig:arc_example}
\end{figure}
% ---------------------------------------------------------
\subsection{The \class{ArcGroup} class}
\label{arcgroup-class}
\begin{figure}[ht!]
\centering
\includegraphics[scale=1.0]{figures/sbgnml_arcgroup_uml.pdf}\\
\caption{A UML representation of the \ArcGroup class for the
\SbgnmlPackage. See \ref{conventions} for conventions related to this
figure. }
\label{fig:sbgnml_arcgroup_uml}
\end{figure}
The arc group describes a set of arcs and glyphs that have a relation together, for example, in ER arcs of class \const{interaction} around a glyph of class \const{interaction}.
Note that, despite the name, an arc group contains both arcs and glyphs.
The \ArcGroup object derives from the \SbgnBase class and thus inherits all
attributes and elements that are present for this class.
An \ArcGroup can contain:
\begin{itemize}
\item zero or more child \Glyph elements,
\item zero or more child \Arc elements.
\end{itemize}
In addition, the \ArcGroup object has the following attributes.
\paragraph{The \fixttspace\token{class} attribute}
An \ArcGroup has a required attribute \token{class} of type
\primtype{string}. While the type is of \primtype{string}, the values should be one of the ones defined in \primtype{ArcGroupType}.
\paragraph{The \Glyph element of an \ArcGroup}
An \ArcGroup can contain \Glyph{}s. For example, an \ArcGroup of class \const{interaction} must contain one \Glyph of class \const{interaction} representing the circle of an $n$-ary interaction. The glyph itself can contain one or more child \Glyph{}s of the class \const{outcome}. Please note, the specification for the Entity Relationship language does not define a \Glyph node of class \const{interaction}. It is only introduced here to represent the circle mentioned above.
\paragraph{The \Arc element of an \ArcGroup}
An \ArcGroup can have multiple \Arc{}s. They are all assumed to form a single hyperarc-like structure.