HELM Requirements Specification – Web-enabled Editor

Document Details Project

HELM

Status / Version

Version 1.0

Document Approval Criteria

Role

Name

Author

Project Manager

Claire Bellamy

Approver

Project Lead

Sergio Rotstein

Approver

Pistoia Alliance Operations Director

Richard Holland

Approver

Technical lead

Tianhong Zhang

Approver

HELM Standard Management Group Lead

Matthias Nolte

HELM Standard Management Group Team Members

Jan Holst-Jensen Roland Knispel, Stefan Klostermann, Sven Neumeyer, Yohann Potier, Thomas Gan, Bernhard Schirm

Approver

Date

Version Control Details Version

Status

Date

Author

Description of Change(s)

1.0

Live

7th January 2016

Claire Bellamy

First Version

Disclaimer If you are reading this document on paper, it is an uncontrolled copy and you may not have the latest version. If you are updating this document, you may not be using the current version. Please refer to the electronic copy available within the HELM Google Drive for the authoritative version.

HELM Web-based Editor Requirements Specification Draft Type: Specification

Table of Contents

Page

1.

INTRODUCTION ........................................................................................... 3

1.1

Definitions ...................................................................................................... 3

1.2

Purpose ......................................................................................................... 3

1.3 1.3.1 1.3.2 1.3.3

Background .................................................................................................... 3 HELM Code – Current Configuration .............................................................. 3 In-Flight Work: HELM 2.0 - Ambiguity ............................................................ 4 Web-enabled Editor Requirements ................................................................ 5

1.4 1.4.1 1.4.2

Scope............................................................................................................. 6 Out of scope................................................................................................... 6 Primary Stakeholders ..................................................................................... 6

1.5 1.5.1 1.5.2

References .................................................................................................... 6 Background Resources .................................................................................. 6 Documentation ............................................................................................... 7

2.

GENERAL DESCRIPTION............................................................................. 7

2.1 2.1.1

Overview ........................................................................................................ 7 Deliverables ................................................................................................... 8

2.2

User Characteristics ....................................................................................... 8

2.3 2.3.1 2.3.2 2.3.3

Design Constraints ......................................................................................... 8 Ambiguous HELM notation............................................................................. 8 Architectural constraints ................................................................................. 8 User Interface Design Constraints .................................................................. 9

2.4

Assumptions and Dependencies .................................................................... 9

3.

OPERATIONAL REQUIREMENTS .............................................................. 10

3.1 3.1.1 3.1.2 3.1.3 3.1.4 3.1.5 3.1.6 3.1.7

Web-Editor Functional Requirements ........................................................... 10 Replicate existing functionality ..................................................................... 10 Additional Editor Input/Output Functions ...................................................... 10 Additional requirements for the creation, display and manipulation of monomers .................................................................................................... 11 Ambiguity specific visualization and functions .............................................. 11 Bulk Molecule Manipulation Tools ................................................................ 12 APIs and dependencies ............................................................................... 12 Documentation ............................................................................................. 12

3.2 3.2.1 3.2.2 3.2.3

Non-Functional requirements ....................................................................... 14 Environment Requirements .......................................................................... 14 Quality Characteristics ................................................................................. 14 Control Function Requirements .................................................................... 15

Page 2/15

HELM Web-based Editor Requirements Specification Draft Type: Specification

1. INTRODUCTION 1.1 Definitions Term

Description

API

Application programming interface

HAbE

HELM Antibody Editor developed by Roche

HELM

Hierarchical Editing Language for Macromolecules

IS

Information system

URS

User Requirements Specification

NFR

Non-functional requirement

1.2 Purpose The purpose of this User Requirements Specification (URS), is to outline the requirements of a webenabled editor to replace the current thick client Java versions of both the HELM Editor and the HAbE. In addition to the transition from one architecture to another, this work will include  Adding the ability to define areas of ambiguity in molecules in accordance with the HELM2 specification.  Adding the HAbE functionality so there is a single editor package.  Expanding the range of small molecule editors by implementing a structure drawing API .

The intended audience of this document are the HELM project team members and groups interested in implementing the requirements.

1.3 Background The Hierarchical Editing Language for Macromolecules (HELM), an emerging notation standard, enables the representation of a wide range of biomolecules (e.g. proteins, nucleotides, antibody drug conjugates) through a hierarchical notation that represents complex macromolecules as polymeric structures with support for unnatural components (e.g. unnatural amino acids) and chemical modifications. Created by Pfizer scientists, the Pistoia Alliance formalized the HELM notation as an open standard in early 2013 and publicly released a modified version of previously proprietary software tools to the Open Source community, which now serve as the reference implementation of the HELM standard.

1.3.1 HELM Code – Current Configuration Two major extensions to the original code have been created and published (figure 1); Page 3/15

HELM Web-based Editor Requirements Specification Draft Type: Specification

 

Exchangeable HELM which enables the user to include the monomer definition with the HELM string thus creating a format that can be used to exchange information between organizations. HAbE (HELM Antibody Editor). Created by Roche HAbE enables the recognition, analysis and display of antibody domains and modules also in complex antibody formats and provides functionality and tools that perform related functions. One example is the automatic creation of all Cys-Cys bonds (within domains and chains and between chains).

The current HELM suite has two dependencies on commercial tools:  

yFiles – a graphing package that supports the graphical representation of HELM structures. A developer licence is required to work with the code. You do not need a licence to distribute your final system. MarvinBeans – a chemical engine and sketcher that is used to perform calculations, interpret extended SMILES strings and sketch monomers. ChemAxon provided a free licence for HELM users of MarvinBeans v5.0 in November 2015, however this remains a commercial tool.

Figure 1: The current HELM suite and its dependencies

1.3.2 In-Flight Work: HELM 2.0 - Ambiguity In summer 2015 the project defined an extension to the HELM definition and issued an RFP to develop:   

The ability to represent ambiguity in macromolecules. Greater flexibility in accessing the functionality The ability to use a wider set of chemical engines.

Architecturally this work can be visualized as shown below:

Page 4/15

HELM Web-based Editor Requirements Specification Draft Type: Specification

Figure 2: The HELM suite roadmap

1.3.3 Web-enabled Editor Requirements This set of requirements is written to complete the transition to a web-based architecture and include the ambiguity and HAbE functionality. The existing editor and HAbE will be retained on GitHub, but will not be developed further. The new editor will not be dependent on yFiles.

Page 5/15

HELM Web-based Editor Requirements Specification Draft Type: Specification

1.4 Scope The work defined in this specification consists of the following changes to the HELM Editor: 1. To redevelop and port the functionality of the editor as a web-based application preferably written in Javascript. The following must be included a. Current HELM editor functionality b. Current HAbE functionality c. A means to define ambiguity and add annotations as defined in the HELM ambiguity line notation design. 2. To remove the dependency on the commercial tool yFiles and replace with a free open-source tool. 3. To create a plugin API that allow access to a variety of structure drawing editors. 4. To document the functions of the new web editor so that it can be used by other applications.

1.4.1 Out of scope Out of scope activities are: 1. Development of a registration system or registration API. 2. Development of a monomer database backend infrastructure. The HELM editor should be able to access monomer information, create new monomers and make changes to existing monomers, however the nature and implementation of a repository for those monomers is out of scope.

1.4.2 Primary Stakeholders The primary stakeholders are     

The HELM notation management group who have the responsibility for managing the HELM notation. The HELM open source ‘dictator’ who approves all code merges to the main trunk. The wider Pistoia Alliance HELM project team and steering committee. HELM adopters particularly in-house IS teams responsible for implementing and managing HELM based systems and vendors supplying HELM compliant systems. The end users of HELM compliant systems (typically scientists) who use the systems.

1.5 References 1.5.1 Background Resources [1] Zhang, T., et. al., (2012), ‘HELM: A Hierarchical Notation Language for Complex Biomolecule Structure Representation’, J. Chem. Inf. Model., vol 52,pp 2796−2806 http://pubs.acs.org/doi/full/10.1021/ci3001925 [2] HELM website www.OpenHELM.org [3] HELM resource centre (contains documentation and links to the code)

Page 6/15

HELM Web-based Editor Requirements Specification Draft Type: Specification

https://pistoiaalliance.atlassian.net/wiki/display/PUB/HELM+Resources [4] Github repository for HELM code https://github.com/PistoiaHELM. [5] HabE User guide https://drive.google.com/file/d/0BybDwk56P1wFMFBZdjRNV0lkNmc/view?usp=sharing [6] HELM Editor User Guide https://drive.google.com/file/d/0BybDwk56P1wFQXQyUUlvUGZoVEU/view?usp=sharing

1.5.2 Documentation [1] HELM notation specification v1.1 https://drive.google.com/file/d/0BybDwk56P1wFZnprdVlDWjI4QzQ/view?usp=sharing [2] Ambiguous HELM line notation design Ambiguous HELM Line Notation Design.doc [2] Web-based editor Wireframes HELM Web-based Editor Conceptual Wireframes.pdf HELM Monomer Editor Conceptual Wireframes.pdf

2. GENERAL DESCRIPTION 2.1 Overview HELM is a notation: The definition and specification of standard is documented in the HELM notation specification V1.1, which will be superseded by HELM 2.0 once the current development work is complete. Supporting the notation is the HELM software suite which consists of the following components which are all written in Java. 

The HELM Toolkit: The HELM Toolkit contains the core functionality needed to implement a HELM-based system, enabling reading, analysis, and manipulation of HELM objects, as well as some monomer management.



The HELM Editor: The HELM Editor is a tool that enables the user to visualize and edit HELM molecules. It is dependent on the HELM toolkit.



HAbE (HELM Antibody Editor): A tool that analyses and assembles antibody structures, displays them at a domain level and allows specific actions to be taken such as connecting free Cys residues. Page 7/15

HELM Web-based Editor Requirements Specification Draft Type: Specification

Currently all components are available as open source code on GitHub and the HELM Editor and HAbE have also been compiled for interested parties to try out. All code is available from https://github.com/PistoiaHELM.

2.1.1 Deliverables The output of this work shall consist of the following: 1. Replacement of the current HELM editor with a web-based version. This editor must contain: 1.1. All the current HELM editor functionality. 1.2. New code to replicate the functionality currently available in HAbE. 1.3. The ability to specify areas of ambiguity in molecules in accordance with the HELM specification 2. Develop a structure drawing plugin API for small molecules (monomers) and at least one implementation, preferably an open source drawing package.

3. Develop code to call HELM2 toolkit functions via web services. 4. A user guide Word document in a similar style to the current HELM user guide. 5. A document specifying the chemical sketcher API and a guide to integrating alternative chemical sketchers. 6. Release notes (it is acceptable for these to be generated from the code).

2.2 User Characteristics End users will be scientists using the editor embedded in their internal systems. As there is a wide variety of internal systems and scientists that use them, it is not possible to detail all of them here.

2.3 Design Constraints 2.3.1 Ambiguous HELM notation The representation of ambiguity has been discussed extensively within the HELM standard management group. A line notation which incorporates these ideas has been designed and is available in Ambiguous HELM Line Notation Design.doc. This design should be referenced during any implementation. Although changes may still be made while toolkit development is underway, we expect these to be limited.

2.3.2 Architectural constraints

Page 8/15

HELM Web-based Editor Requirements Specification Draft Type: Specification

The following technologies are recommended for the frontend:      

Babel.js and ES6 React.js & (Reflux || Redux) Web Components Postman

Gulp Yeoman

The final solution shall contain no dependencies on third party tools that require paid licences. The current yFiles dependency should be replaced by an open source graphing package. Both HELM1.1 and HELM2 shall be supported.

2.3.3 User Interface Design Constraints The HELM team have created some wireframes which illustrate the design principles preferred by the team. At present the design is incomplete, however it should be taken into consideration.

2.4 Assumptions and Dependencies The HELM editor is dependent on the toolkit. When work starts on the editor it is assumed that the HELM2.0 toolkit will be live and will be used for this work. HELM is a live standard and, as such, any changes will affect its current users and should be made backwardly compatible as far as possible. HELM is an open standard and it is not possible for the project to be aware of the details of every group’s use of HELM, and so there will be unknown dependencies. All development should aim to minimize disruption to existing users.

Page 9/15

HELM Web-based Editor Requirements Specification Draft Type: Specification

3. OPERATIONAL REQUIREMENTS 3.1 Web-Editor Functional Requirements Key to priorities… E = Essential. The system must fulfil this requirement or it fails in a fundamental way and cannot be deployed. H = High. A requirement of high importance M = Medium. A requirement of medium importance L= Low. A requirement of low importance

3.1.1 Replicate existing functionality Req #

Requirement

Priority (E,H,M,L)

Create a Javascript HELM editor which has: FRS 100



All the functionality in the existing HELM editor



All the functionality in HAbE

E

3.1.2 Additional Editor Input/Output Functions All these requirements add features in addition to those that already exist in the current functionality. Req #

Requirement

Priority (E,H,M,L)

It shall be possible to enter structure information in the following formats: FRS110



HELM(2)



xHELM



FASTA



Genbank

E

It shall be possible to enter structure information in the following chemical formats:  FRS120

FRS130

SMILES

 Molfile If these formats are used the application will assume that the structure is a CHEM monomer. The application shall check whether the structure already exists in the monomer repository. If the monomer does exist then the monomer ID and other stored information shall be associated with that monomer. It shall be possible to load multiple structures for parallel visualisation, assembly and manipulation. Any file used for bulk upload shall be in a single format i.e.upload files may

E

E Page 10/15

HELM Web-based Editor Requirements Specification Draft Type: Specification

contain multiple structures, but the notation used for each structure must be the same. FRS140

It shall be possible to return multiple structures to a calling application that has invoked the HELM editor.

E

3.1.3 Additional requirements for the creation, display and manipulation of monomers Priority (E,H,M,L)

Req #

Requirement

RFS200

It shall be possible for an administrator to choose whether all monomers must be registered before use.

E

FRS210

If the administrator allows, monomers that have been defined but not registered shall still be available for use in the current session. The monomer information in the HELM string of the resulting macromolecule shall be displayed using in-line notation.

E

3.1.4 Ambiguity specific visualization and functions Req #

Requirement

Priority (E,H,M,L)

It shall be possible to specify portions of the sequence where the structure is unknown. The definition given in the HELM specification must be followed:  FRS500  

FRS510

FRS520

The component structure is unknown, but there is one monomer present – ID must equal ‘X’

E

The component structure is unknown, but there may be more than one monomer present – ID must equal ‘*’ (0…n monomers) There may be a missing monomer – ID = ‘_’

It shall be possible to select a single position and define multiple monomers as options to occupy that a single position and the ratio of each. It shall also be possible to define whether this relates to 

a mixture



a single compound whose composition could be either one or more alternatives.

It shall be possible to define a repeating monomer unit and the number of times it repeats either exactly or as a range.

E

E

It shall be possible to define an unknown sequence as a simple polymer (BLOB) FRS530

FRS540



where the type of simple polymer is not specified



where the type of simple polymer is specified

It shall be possible to specify a list of alternative possible connection points for a bond. These connection points could be at a monomer, simple polymer or domain level or a combination of any of these.

E

E

Page 11/15

HELM Web-based Editor Requirements Specification Draft Type: Specification

It shall be possible to specify relative ratios for connected simple polymers. FRS550

FRS560



As a mixture



As alternative polymers where one or other can be present but not both. The probability of each is specified in the ratio.

It shall be possible to add an annotation at a monomer, simple polymer, domain or complex polymer level or to add annotations to connections.

E

E

3.1.5 Bulk Molecule Manipulation Tools Req #

Requirement

Priority (E,H,M,L)

It shall be possible for the user to predefine a rule that describes a change to all, a section or moiety of one or more molecules: FRS100

FRS100



Insert one or more monomers (append)



Edit one or more monomers (replace)



Delete one or more monomers

It shall be possible to perform a global search and replace for a specific monomer

E

E

3.1.6 APIs and dependencies

Req #

Requirement

FRS100

HELM toolkit 2.0 web-services shall be used to access toolkit functionality.

Priority (E,H,M,L) E

A new API shall be developed that allows the web-editor to: FRS100

FRS100



Invoke a chemical sketcher optionally passing through a SMILES structure.



Retrieve a structure from the drawing package as extended SMILES string (i.e. a structure containing R groups may be returned).

The implementation shall be completed for at least one open source web-based chemical drawing package.

E

E

3.1.7 Documentation The following documents shall be created: Page 12/15

HELM Web-based Editor Requirements Specification Draft Type: Specification

Priority (E,H,M,L)

Req #

Requirement

FRS100

A user guide as Word and PDF documents. The style must follow that of the current HELM Editor User Guide.

H

FRS100

A document specifying the chemical sketcher API and a guide to integrating alternative chemical sketchers.

H

Page 13/15

HELM Web-based Editor Requirements Specification Draft Type: Specification

3.2 Non-Functional requirements 3.2.1 Environment Requirements Req #

Requirement

NFR100

The following technologies are recommended for the frontend: • Babel.js and ES6 • React.js & (Reflux || Redux) • Web Components • Postman • Gulp • Yeoman

NFR110

The final code shall be delivered as a ‘pull request’ which includes the new code as a fork from the HELM master branch in Github.

NFR120

It is desirable that Github is used as a code repository during development.

NFR130

The final solution shall contain no additional dependencies on third party tools that require paid licences for commercial usage.

Priority (E,H,M,L)

E

E

L

E

3.2.2 Quality Characteristics Req #

Requirement

NFR200

The proposed architecture must pass a review with the HELM project team before coding starts.

NFR210

Code should be written in accordance with normal good practice and developers should write their own internal unit tests.

NFR220

All code must pass regular code reviews with the HELM project team for good software engineering practice. A minimum of two reviews will be held, the first will be conducted at a time not later than one third of the way through the planned development period.

NFR230

Code must be self-documented through appropriate use of comments. Comments must be sufficient to create Java doc reports that are self-explanatory.

NFR 240

The product must be of acceptable quality, as defined by agreed maximum acceptable number of open defects of each severity categorisation (Critical, High, Medium, Low) at close of UAT. The following definitions will be used for these

Priority (E,H,M,L) E

E

E

E

E Page 14/15

HELM Web-based Editor Requirements Specification Draft Type: Specification

categories: Critical – prevents any use of the editor or prevents use of fundamental parts of the toolkit. High – a defect that is frequently encountered by normal use of the software and which prevents use of that functionality Medium - a defect that is encountered by normal use of the software and which prevents use of an aspect of that functionality Low – a defect that is rarely encountered, or does not prevent normal use of the software. NFR250

There must be a mechanism by which the project can automatically execute and validate test cases and report success/failure.

E

3.2.3 Control Function Requirements Req #

Requirement

NFR300

All error messages must be easily understandable and consist of language that a non-IS/IT scientist can understand, and must also accurately indicate the nature of the problem. For example, low-level system error codes and messages should not be displayed to a user. An error log should be created that enables root cause analysis to be carried out.

Priority (E,H,M,L)

H

Page 15/15

HELM Web-based Editor Requirements Specification V1_0.pdf ...

HELM Web-based Editor Requirements Specification V1_0.pdf. HELM Web-based Editor Requirements Specification V1_0.pdf. Open. Extract. Open with.

538KB Sizes 0 Downloads 224 Views

Recommend Documents

HELM Web-based Editor Requirements Specification V1_0.pdf ...
3.1 Web-Editor Functional Requirements. ... 3.2 Non-Functional requirements . ... Page 3 of 15. HELM Web-based Editor Requirements Specification V1_0.pdf.

Architectural Requirements Specification - GitHub
cumbersome tool to have to port to mobile application clients. 4. Page 7. Description of Components .1 Odin-CLI .1.1 Technologies. The command line interface will be implemented in Python 3, using built-in classes and libraries to provide a usable in

System Requirements Specification - GitHub
This section describes the scope of Project Odin, as well as an overview of the contents of the SRS doc- ument. ... .1 Purpose. The purpose of this document is to provide a thorough description of the requirements for Project Odin. .... Variables. â€

Architectural Requirements Specification - GitHub
porchetta tri-tip kielbasa kevin chicken hamburger sirloin. Cow pastrami short ribs shank. Sirloin spare ribs jowl, beef ham hock kielbasa ribeye prosciutto cow. Capicola pork chop landjaeger jowl venison beef ribs sirloin tri-tip tenderloin pastrami

System Requirements Specification - GitHub
System Requirements Specification. Project Odin. Kyle Erwin. Joshua Cilliers. Jason van Hattum. Dimpho Mahoko. Keegan Ferrett. Note: This document is constantly under revision due to our chosen methodology, ... This section describes the scope of Pro

Modern Requirements Specification
However, trends in system development have made the numerous problems ... not only enabled better requirements management; they have also enabled the ..... requirements methods, and better-standardized content for our requirements.

Software Requirements Specification
and Defect are entities that implement create, read, update and delete actions, but .... public String createDomain(String domainName) – Method creates a new.

Software Requirements Specification
THE DEVELOPMENT MANAGER (ALSO KNOWN AS SOFTWARE ..... The PM is responsible to the application management activities which include planning ...

Software Requirements Specification versi 2.pdf
There was a problem loading this page. Retrying... Whoops! There was a problem previewing this document. Retrying... Download. Connect more apps... Try one of the apps below to open or edit this item. Main menu. Whoops! There was a problem previewing

Pistoia Alliance HELM Web-based Editor RFI V1_0.pdf
There was a problem previewing this document. Retrying... Download. Connect more apps... Try one of the apps below to open or edit this item. Pistoia Alliance ...

Specification - cs164
Fri. 2/3. Proposal. 2/6. Design Doc, Style Guide. 2/10. Beta. 2/24. Release ... or otherwise exposed) or lifting material from a book, website, or other ... Help is available throughout the week at http://help.cs164.net/, and we'll do our best to res

Specification - cs164
need a Mac for the course until Mon 3/19, but Xcode comes with iOS Simulator, which might prove handy for testing in the short term. If you do have a Mac, know ...

Specification - cs164
Computer Science 164: Mobile Software Engineering. Harvard College .... Log into your Bitbucket account and create a new, private repo as follows: □ Select ...

Requirements
Must be pulled high (3.3v). CS. 15. Any free pin. REST. 17. Any free pin. ITDB02 pinout. 1. All boards with pinout like the Arduino Duemilanove / Arduino UNO. 2.

specification - ELECTRONIX.ru
Nov 22, 2007 - BASIC SPECIFICATION. 1.1 Mechanical specifications. Dot Matrix. Module Size (W x H x T). Active Area (W x H). Dot Size (W x H). Dot Pitch (W x H). Driving IC Package. 1.2 Display specification. LCD Type. LCD Mode ..... ON THE POLARIZER

StackMap API Specification - GitHub
domain is the specific StackMap installation for your library. POST Data. The POST ... A node with the name of the library to search for the holding. ▫ Attributes.

specification sheet - AV-iQ
FOR KEYPADS, TOUCH-PANEL CONTROLS AND OTHER HUMAN INTERFACE DEVICES. FOR LUTRON SYSTEMS 75C 300V RISER RATED. CONSTRUCTION: 22 AWG 16 STRAND BARE COPPER 1 PAIR, SHIELDED DATA PAIR PLUS. 18 AWG 41 STRAND BARE COPPER 1 PAIR TWISTED, OVERALL PVC ...

Devicetree Specification - GitHub
Apr 30, 2016 - Companies ... A piece of software may be both a client program and a boot ..... defined by the DTSpec. 2.2. Devicetree Structure and Conventions. 10 ...... dtc-paper.pdf), An overview of the concept of the device tree and device ...

Letter Editor
Editors can be reached via e-mail, fax, telephone, or mail. A ... Telephone: The switchboard is open weekdays 8:30 a.m. to. 5:30 p.m. After 5:30 ... So, I set out to.

Letter Editor
... telephone, or mail. A list of editors and contact information is at ... funding, accreditation and marketing strategies arranged by day; plus important information ...