ART - general overview of developments (in progress - will add specific references to tickets)

[lpalbou]

This ticket is to reference and keep track of the different developments to create ART, the bulk edit UI of GO-CAMs.

The ART mockup can be find here: https://drive.google.com/file/d/15gIJ85SAHzd6uCO-g7dmpHP-t1yJVt3f/view?usp=sharing

UI part

• [x] build the UI based on the mockup above : follow the sequence of actions and the way the layout are updated after each action
• [x] encourage directional workflow: 1 - activate review mode ; 2 - perform a search to retrieve models of interest ; 3a - selecting/unselecting a model will add it/remove it from the ART panel on the right. any new model selected should be on top of the screen to provide curators of an immediate view of the model and help them decide if it should be part of the models to bulk edit ; 3b - whenever the ART panel is shown, hide the search panel on the left to give a better sense of the unidirectional workflow and help the curators concentrate on the next steps ; 4 - once the models for bulk edit are selected, allow the curators to edit them through both the replace/replaceall functionality and the "edit pen" on each cell of the table. All of those changes are simulated (change the model in memory but not in the store) and should be highlighted to provide a global view of the pending changes that will be either canceled (restore the model from the store and cancel any pending changes on the in memory model) or accepted after showing a summary of all the changes that will take place (stats table)
• [x] highlighting changes in the table : any pending change to models should be highlighted (eg yellow border / background) for quick browsing. A mouse over on any change should show a tooltip to indicate the original value. This original value should be provided by minerva and not kept in the client memory (eg issues if ART closed / reopened)
• [x] summary table of changes : this table should be created by counting the differences based on the "changes functionality" (see in Minerva part). This is an essential step that will provide curators with the ability to get an idea of how many changes will be propagated with their bulk edits
• [x] always show all the models selected by curators : doing a find/replace should not hide the models which don't contain the term/gp/pmid but should just fold them. Models containing the item searched should be unfolded by default to improve visibility
• [x] simple button to fold / unfold all selected models : convenience feature to help curator see only the information they need
• [x] translate shex responses to more user friendly messages : the shex json response usually refers to individuals violating one or more rules. A first level of integration would be to highlight in red any field in the table representation that violates the shex. A second level of integration would be to provide some human readable hints about what was violated. This would probably require 2 ways developments on the UI and minerva side.

Minerva part

• [x] reset functionality: flush the version of a model contained in blazegraph to the permanent in memory version of the model. This is used to cancel any changes done with ART (see Notes below)
• [x] changes functionality: provide a detailed diff of how the in memory version of a model differs from its version in blazegraph. The method would have an optional parameter to detail the diff for a single individual (eg for a goterm node). Another method would call that method for a set of models (while the client could loop through models, this would create separate multiple queries with possible network issues)
• [x] unchanged / up-to-date functionality : simple function returning booleans to indicate if the in memory and blazegraph versions of a set of models are the same (used in UI to warn or prevent users to edit those models with pending modifications)
• [x] selectively access the in memory or the blazegraph version of a model: the get_model() accesses the in memory version of a model, a tag should be added to allow to access the model stored either in memory or in blazegraph (see UI part to highlight changes)
• [ ] update queries stacked over multiple models: currently, the bbop library supports the stacking of multiple queries referring to a single model. However ART will be asking to update multiple models, hence the need to support the stacking of queries referring to multiple models
• [x] work with UI team to improve shex json response : in previous calls, it was unclear on how some shex response could be interpreted; this will be an ongoing ticket as this is a new functionality

Unit tests (not specific to this project, but to be encouraged)

• [ ] set of permanent models on minerva/dev
• [ ] set of queries to modify those models on minerva/dev
• [x] test that all modifications were actually performed
• [x] test the cancel / reset for a single model, or for a list of models

Optional developments (probably for future road maps)

• [ ] restrict curators to only edit the models from their group but not all models : we will probably try to get this done before the end of the year. The simplest solution would be to check on the client side if the curator belongs to the same group as the curator who created the model. For better security and avoid errors, a better or additional solution would be to do the check on server side (eg accept edit of a model only if coming from a curator belonging to the same group or being a "super curator" - a tag could be added in the users.yaml to define such "super curator")
• [ ] locking mechanism: prevent multiple users to alter the same model at the same time. The "undo" mechanism could then be used more safely and would prevent possible errors arising from the simultaneous edit of a same model. As a reminder all edits are saved in a permanent in memory version of the model, including those coming from two users or two different UIs
• [ ] autocomplete: this is a larger task with implications in multiple UIs and with work required also on the back end side / GOLr. However, any development from now on should encourage the creation and use of reusable web components. The behavior of the web component could be the same as the current autocomplete used in NoctuaForm/ART, but the separation as a different library will help this part of the code to evolve and consistently solve issues over time

Notes

• This will be an iterative development, so items can be added / removed over time to these lists
• All changes started with ART must be simulated changes to enable curators to either validate all of their changes or to cancel all of their changes. This ability to simulated changes will be supported by the permanent in memory version of a model vs the version of the model contained in the triplestore
• Currently, any modification done with the bbop library to a gocam with "save" is written to the permanent in memory version of a model. When the "store" command is called, it flushes that memory version of the model to the store
• Due to the lack of locking mechanism when editing a model, the "undo" method can not really be used to cancel and reset the changes done in ART. Hence the task to create a "reset" at the minerva level, to restore the in memory version of the model to its version contained in blazegraph
• As a note, it would be good if any call to "save" could return a unique ID for the transaction / stacked queries, so this specific action could be undo. I don't think this is feasible at the time as it would require a much more advanced "undo" mechanism able to revert changes in a non sequential orders with potential conflits (like in GH)
• To prevent a model that was already changed in memory or to at least warn a user, the "changes" method should be implemented on minerva side to reflect how the in memory model and the store model differs
• A number of models will not pass the shex, either when opening them in ART or when a curator will start its bulk edit.

[vanaukenk]

@ukemi and I reviewed the UI and workflow. It looks good, but we have a few comments and questions to discuss on the 2020-08-28 call:

Encourage directional workflow

• We anticipate that steps 1 and 2 would actually be reversed, i.e. curators would perform their search first and then activate review mode.
• We’re not sure that automatically closing the left search panel is always desirable in that curators may want to have a visual of what their original search criteria were. If keeping the left search panel open takes up too much real estate, would it instead be possible to list the exact search terms/values at the top of the models table rather than just the type and count?

Highlighting changes in the table

• It would be nice to highlight matched search terms with one color and actual changed values with another color.

Other details to confirm

• Find and replace fields will always be restricted to the same value type, e.g. CC term can only ever be replaced with another CC term?
• List of editable fields (note that this is distinct from what is searchable from the landing page and still requires compliance to the form’s structure): — Genes/gene products — Relations — GO terms — ECO codes — References — Annotation extension relations — Annotation extension values
• Reset wipes out all changes implemented up to that point?
• Would it be possible to have reset functionality on each individual box as well?
• In the Review Decisions window, what exactly does clicking on Cancel do, i.e. just return the user to the editing table or return the user to the editing table AND undo all changes?

Minor UI things

• Let’s label the ‘Review’ button to ‘Annotation Review’ to try to be even clearer on what this functionality is
• The ‘REVIEW MODE’ banner is really nice as a visual, but can we make it even more apparent to curators that they’re in review mode by, for example, changing the background color of the models table on the landing page?
• What does the box with the T mean in the ‘Find and Replace’ window?

[lpalbou]

Following our discussion today:

• No issue in doing step 1 -> step 2 or step 2 -> step 1. The "Annotation review" button will be here and can be triggered either way

• closing left search panel: we reached the conclusion that as long as we are showing the actual search parameters in the bar of the landing page, we'll be fine. The concern was to keep an eye on what was the original query

• agreed on having different colors: 1) for matching 2) when the curator has changed a field 3) if any error is encountered. We'll try to apply different shadings (@ukemi if you have good examples to refer to, it would be appreciated)

• restriction to term: I think it should be ok for GO, but what of other ontologies ? If we edit a Uberon term, do we only want Uberon term ? Seems like this could be too restrictive @vanaukenk

• editable fields: start with gene products, go terms, references. Later on, implement relation, eco codes, annotation extension (relation, value). As a note, changing relationship should probably be done in another UI representing for instance an activity centric view of the model. A table representation is not very suited to change relationships between objects

• Reset: it will wipes any pending changes. Essentially, it will restore the model to its last saved version in the store, removing anything that was changed. As a note, @tmushayahama is right that anyone editing the models before or at the same time will cause technical issues. We'll have to tackle with a "locking mechanism" later on. For now, we can indicate which models have pending changes and encourage curators not to edit models with pending changes, unless they know what they are doing.

• Reset in individual box: we can have a reset at a model level, but at a field/box level, it will depends of the technical strategy we use. How critical is this ? @vanaukenk essentially if you want it to work properly, the best way would be to handle more changes on the client side (which I wouldn't recommend). Minerva / server is not able to undo changes in an unordered way, so if it was the last change, you could undo it, but if in the meantime you did other changes, then you would have to undo all of those changes before reaching the step where you were changing that field.

• Review decision window: cancel = we agreed on a "go back" button where you would go back to the ART form. In that ART form, you would have the possibility to either "review" again or "reset". Reset will remove any pending changes to the selected models

• Review button renamed to "Annotation Review": ok

• Review mode: we'll do some tests for changing the background colors of the lines representing models. I think this may be too colorful, but we can try

• T box: show the list of editable fields (in a first iteration, go term, gene product, reference). I don't know yet how much other fields we will be able to fit for a replace all in V1

[vanaukenk]

@lpalbou @ukemi

David and I discussed the specific points above and here are our thoughts:

1) For the different colors, David suggests just trying some contrasting colors of your choosing in the prototype and we'll see how it looks. Maybe something like 'Banana' to 'Tuscany' to 'Fire'? https://graf1x.com/shades-of-yellow-color-palette-chart/

2) For restricting find and replace to the same ontology, we think that, for now, we should impose that restriction. In the future, we may want to allow, say, one anatomy ontology term to be replaced with a term from another anatomy ontology, but I think we should keep it simple for now and add more sophisticated functionality if/when requested by users.

3) For resetting individual boxes, we are both okay with not having that functionality for the first iteration of ART and, again, adding this feature if users request it in the future.

Please let us know if you need clarification on anything.

Thx.