[EPIC] Functional Groups

[AndreiMazol]

Glossary

• FG - functional group (a set of atoms & bonds that can be considered as one entity)
• Abbreviation - both 1) a shortened textual form of part of a molecule, 2) grouping of atoms and bonds
• Remove Abbreviation - Ungroup, which means removing the inclusion of atoms and bonds in an FG, without removing the atoms and bonds.
• Contract Abbreviation - Show only abbreviation, don't show the FG's atoms and bonds
• Expand Abbreviation - Show the FG's atoms and bonds

1. As a user, I can place an FG on the canvas by importing it from an external file or by writing the FG's textual description.

The feature must be available via the Open Structure window.
Whether the imported FG appears contracted or expanded must be controlled by the SDS parameter in the file. If the SDS parameter has value EXP, the FG must appear expanded. If not, then contracted. If there is no SDS parameter in the textual description of the FG, the FG must appear contracted.

Contracted abbreviation looks as follows:

Expanded abbreviation looks as follows:

The supported file formats for FG import are MOL V2000, MOL V3000, KET.

The behavior of FGs in general

The FG must attach to the molecule via the connection atom(s) specified in the FG textual description.
For instance, PO3 attaches via the phosphorus atom.

FG can only be attached to the atoms. FG can only be attached as a list element.
No actions should happen when trying to attach FG to the bond.

At the moment of placing the FG, the application must calculate the rotation angle of the FG relative to the molecule so that there is no overlap with existing atoms and bonds.
For instance, attaching PO3:

A collapsed abbreviation (i.e. grouping) must be bold. As for an expanded abbreviation (i.e. grouping): when the user hovers over any of its atoms or bond, the whole group must be highlighted and surrounded with a square (similar to s-group).

2. As a user, I can place an FG on the canvas by loading it from Ketcher's library.

A button (named 'Functional Groups') invoking the 'Functional Groups' window must be placed next to the 'Custom Templates' button. Icon design: TO BE DEFINED provided & Implemented
A user can also open the 'Functional Groups' window by pressing the key combination "SHIFT + F"
A user must be able to choose an FG in the window.

The window's UI should be similar to the UI of the 'Custom Templates' window.

The window must contain:

• 'Filter' field
• 'Save to SDF' button: SDF file for the FG should be created as it is created now for the template. Only the [BondID] metadata should be excluded. The file should have all the structures that are used by BIOVIA to create the same SDF file for the FGs.
• 'Cancel' button
• 'OK' button
• Each FG's title (which is also the abbreviation) and image
• No 'Edit' button in this version
• Only the 'Functional Groups' tab in this version No tabs should be presented.
  All Functional groups must be displayed when the window is opened.
  When entering the text to the Filter field the list of Functional groups should be filtered so that only FGs with the name containing the row entered into the field will remain. If there is no FGs satisfying the text entered, the window should be displayed as empty with OK button disabled

The user must be able to add FGs to the library by changing the SDF file.
An FG added from the library must initially appear contracted.

3. As a user, I can expand, contract, and remove an FG abbreviation (i.e. grouping).

3.1. Features for contracting, expanding, removing abbreviations (i.e. groupings) must be available under one group of buttons.

The group of buttons should be similar to the Reactions group of buttons.
Icons design: TO BE DEFINED

The group of buttons must include:

1. Expand / Contract Abbreviation Tool
2. Remove Abbreviation Tool

3.2. The user must be able to expand and contract an abbreviation (i.e. grouping).

The Expand / Contract Abbreviation Tool:
When the user uses the Expand / Contract Abbreviation Tool:

1. Hovering over a contracted abbreviation (i.e. grouping) must highlight it.
2. Hovering over any atom or bond in the expanded group must highlight and surround with a square the group, similar to s-group:

3. Left-clicking a contracted abbreviation (i.e. grouping) must expand it.

4. Left-clicking any atom or bond in the expanded group must contract the group to its abbreviation (i.e. grouping). 

3.3. The user must be able to remove an abbreviation (i.e. ungroup).

The Remove Abbreviation Tool:
When the user uses the Remove Abbreviation Tool:

1. Hovering over a contracted abbreviation (i.e. grouping) must highlight it.

2. Hovering over any atom or bond in the expanded group must highlight and surround with a square the group, similar to s-group:

3. Left-clicking (1) the contracted abbreviation or (2) any atom or bond in the expanded group - must remove the abbreviation (i.e. ungroup). After removing the abbreviation, the FG must become expanded. The Remove Abbreviation Tool does not remove the atoms and bonds. It only removes the inclusion of atoms and bonds in an FG.

4. As a user, I can do certain actions with an FG only after removing abbreviation (i.e. ungrouping).

The interaction of FGs with other Ketcher's features

~~[this is for the future version] ~~Rotate Tool, Horizontal Flip, Vertical Flip, Lasso Selection, Rectangle Selection: allowed to be applied to individual atoms and bonds of the FG.
[for 2.4 ver.] There should not be the ability to flip, rotate or select individual atoms inside FG.] ~~
[for 2.4 ver.]: Any selection tool when applied to an element of the expanded FG should select all the elements in FG.
Rotate Tool, Horizontal Flip, Vertical Flip - should be applied for the expanded FG as they are applied now for the S Groups on the canvas.
(url)

Fragment Selection: the whole FG must get selected.

[this is for the future version] Erase: individual atoms (bonds) and adjacent bonds (atoms) must get removed (similar to templates). Removing one atom or bond from an FG does not remove the whole FG.
[for 2.4 ver.] It should not be able to remove individual atoms, bonds inside FG. Only all FG should be removed.

**[this is for the future version]**Dragging one atom or bond does not cause dragging of the whole FG.
[for 2.4 ver.] It should not be able to drag a single atom or bond inside FG.

Aromatize, Dearomatize, other server operations R-Group Label Tool, R-Group Fragment Tool, Attachment Point Tool, Stereochemistry, S-Group, Data S-Group: TO BE DEFINED
S-Group: selecting the FG only should be forbidden to apply S-group. Should work if FG and something else is selected.
Stereochemistry: should work on the common groups. There is no FG that could be presented in Stereochemistry mode.
Data S-Group, R-Group Label Tool, R-Group Fragment Tool, Attachment Point Tool, Bonds, Chain, organic compound toolbar, chemical elements toolbar, Custom Templates, Charge Plus. Charge Minus: application to an FG must be forbidden. These features must be allowed for the FG's atoms and bonds only after removing abbreviation (i.e. ungrouping). If tool is trying to be applied for the elements of several FGs - all these FGs should be ungrouped after user's confirmation.
Other tools: allowed

When the user tries to apply the forbidden tools to an FG

When the user tries to apply the forbidden tools to an FG, s/he must be given a choice in a modal window to either (1) remove the abbreviation (i.e. ungroup (Remove Functional Group)), or (2) keep the abbreviation.
The window's text: "This tool can not be applied for the Functional Groups. Do you want to remove the abbreviation? It is required for adding atoms and bonds to the group."
The buttons: Yes (default), No.
If selected groups were contracted, in the moment of removing abbreviation the should expands.

5. As a user, I can export an FG to a MOL file.

The supported file formats for the FG export must be MOL V2000, MOL V3000, KET.

[MuratSafarov1]

@AndreiMazol @nseufulina
20 August BA update

1. Glossary: changed to "Remove Abbreviation - Ungroup, which means removing the inclusion of atoms and bonds in an FG, without removing the atoms and bonds."
2. User story 1: changed to "Whether the imported FG appears contracted or expanded must be controlled by the SDS parameter. If SDS parameter has value EXP, the FG must appear expanded. If not, then contracted. If there is no SDS parameter in the textual description of the FG, the FG must appear contracted."
3. User story 1: merged here "The behavior of FGs in general" from the user story 2.
4. Requirement 3.3: added "The Remove Abbreviation Tool does not removes the atoms and bonds. It only removes the inclusion of atoms and bonds in an FG."
5. User story 4: added "The interaction of FGs with other Ketcher's features."
6. Added explanatory images.

[PavelSnadin]

BA Update 29/09/21
User story 1: The description of the ability to open a FG by pressing a combination of hot keys has been added.

[Alena-Guznischeva]

User Story no.2 updated for the FG window requirements:

Only the 'Functional Groups' tab in this version No tabs should be presented.
All Functional groups must be displayed when the window is opened.
When entering the text to the Filter field the list of Functional groups should be filtered so that only FGs with the name containing the row entered into the field will remain. If there is no FGs satisfying the text entered, the window should be displayed as empty with OK button disabled

[Alena-Guznischeva]

US 4 update for forbidden tools: If tool is trying to be applied for the elements of several FGs - all these FGs should be ungrouped after user's confirmation

[Alena-Guznischeva]

UC 4 updated: added sections on future features vs 2.4 ver abilities. Generally, in 2.4 there should be the ability to edit anything inside FG, so selection, dragging, deleting of the single elements inside FG should be forbidden.

[Alena-Guznischeva]

UC 4 updated for Rotation& Flip & Selection tools for 2.4 in accordance with demo feedback received.