save genome browser session to the web browser storage

[fossilfriend]

Save the "session" to the (global) state, so that when user browsers away from the page or refreshes the page, the current view (location, highlights, selected tracks) is remembered.

User experience:

1. browsing away and back in same tab? --> restore session
2. refreshing page --> restore session
3. closing tab or browser --> do we want to restore session or not? NO
4. reopen (accidentally) closed tab --> can we restore the session?

how best to do this? localStorage vs sessionStorage see: https://www.geeksforgeeks.org/difference-between-local-storage-session-storage-and-cookies/# and: https://www.digitalocean.com/community/tutorials/js-introduction-localstorage-sessionstorage and also: https://blog.logrocket.com/using-localstorage-react-hooks/ and https://usehooks.com/

and then what do we want to store?

• the browser object itself?
• loaded tracks, locus, regions of interest individually? updating local storage as each of those change?

[fossilfriend]

Decided to proceed w/sessionStorage and leverage https://usehooks.com/ Will also leverage sessionJSON object created when user saves (exports) the IGV session as JSON

So, saving & loading sessionJSON (via buttons) is a prerequiste to completing this task

[fossilfriend]

sessionJSON will need to updated when

• [x] locus changes
• [x] track is loaded
• [x] track is removed
• [ ] track settings are modified (e.g., height, colors, etc)
• [ ] region of interest changes (added, removed, description changed)

create a single callback for all the events

onBrowserChange -> regenerates sessionJSON

sessionStorage should then be updated by a useEffect hook dependent on sessionJSON

[fossilfriend]

for adding/loading a new track

• alter loadTracks function

• add a parameter onTrackLoad that expects a callback as a value (so can add .then(onTrackLoad() to the browser.loadTrack() call)

• when loadTrack is called from IGVBrowser component, pass onBrowserChange as the callback value

for removing a track

• this can be handled by an igv event handler.
• add browser.on('trackremoved', function (track: any) { onBrowserChange()}) inside the createBrowser call

[fossilfriend]

for handling changes to region on interests

add a useEffect hook that looks for changes to browser.roiManager.roiSets

[simoncole]

Implemented saving, loading, adding, and removing tracks that persist with the session.

• The strategy used was to have a useSessionStorage sessionJSON state that gets loaded on initial render if there is something in the state. This happens in a useEffect dependent upon the browser, browserIsLoaded and tracks.
• Whenever an event happens that could change the session state, the new state is first converted into session format then set as the new session and automatically saved to session storage by the useSessionStorage hook.
• An example of this happening is when a user adds new tracks using the add tracks button. This also currently occurs when a track is removed.
• The implementation used for loading a new session involves parsing the uploaded JSON file and calling a remove all tracks and load new tracks function from an onClick handler. The aforementioned function is also utilized to remove old and load new tracks upon initial render.

[simoncole]

Saving ROIs

• The initial thought of how to handle saving ROIs was to create a useEffect that would run when browser.roiManager.roiSets would change. Unfortunately this approach doesn't quite work. Making a useEffect dependent upon a property is possible in react, but our issue stems from the fact that roiSets is an array with nested objects as properties.
• React performs a shallow comparison for a useEffect dependency meaning it checks if the reference to the dependency has changed, not the actual contents of the array/object, therefore, in our case when a new ROI set gets pushed to the array, the useEffect doesn't get triggered.
• A few different solutions were attempted here. My initial thought was to utilize JSON.parse and JSON.stringify on browser.roiManager.roiSets to create a new reference and then compare, however this approach doesn't work because JSON.stringify and parse doesn't accurately compare the nested objects roiSets contains and doesn't end up triggering the useEffect.
• After doing some searching online, another thought was to utilize useMemo and memoize the roiSets. However, after doing this the useEffect wouldn't trigger when new sets were added to the array. The issue stems from the fact that the useMemo hook also uses a shallow comparison in its dependency array, so when browser.roiManager.roiSets is passed as a dependency useMemo doesn't realize it changes.
• I also briefly tried creating a custom hook here that utilizes a deep compare with lodash.isequal, but this still didn't work.

Current Implementation

• The implementation I have now works, but is a bit of a hack and seems like bad practice.
• I implemented a solution that utilizes an interval in a useEffect that fetches the current ROIs on the browser and deep compares them to a new reference of browser.roiManager.roiSets every second (Interval can be changed if desired).
• It then updates the session and on initial page load, if there is a session, it loads those ROIs.
• The performance cost of this implementation shouldn't be too significant since all it is doing is fetching the current ROIs and then comparing them to what's in the browser object every second.
• The code for the commit can be found here

[simoncole]

Saving Locus changes to the session

• The first challenge was to create an event and state system that doesn't call the updateSessionLocus function repeatedly while the user is dragging the locus. This was achieved by using the events "trackdrag", "trackdragend", and "onlocuschange" in tandem with a ref isDragging that prevents the updateSessionLocus from being called. My first thought was to make isDragging a state variable however this approach doesn't work because in react the state captured within the event handler function is the state at the time which the function is defined, not when the handler is called. This meant the isDragging state would not update while the user is dragging the locus. The solution here was to use the useRef hook because it captures the current state of isDragging.
• The next challenge came on what happens when the updateSessionLocus function is called. The function is supposed to update the sessionJSON state to accurately reflect changes in the locus. I at first thought this would be simple because I could just call the function from the locus change event handlers and pass the sessionJSON state and its setter but this causes the same problem mentioned previously where the state is not updated with the component so sessionJSON is null when the function is called from inside the handler. The solution I used previously here wouldn't work because sessionJSON needs to be the useSessionStorage hook and thus cannot be a ref. After doing some research, the solution I employed was using the functional form of setSessionJSON because this provides a callback which contains the updated version of sessionJSON. This can be seen here.
• The same issue I mentioned above applied to removing tracks so I modified its handler to also use the functional form of setSessionJSON here
• After the session updating was set up, the solution was to use the IGV browser API function search to change the browser locus whenever there is something stored in the the session JSON here

[simoncole]

Summary

• Implementation outlined in previous comments were altered.
• The IGV.js code was altered to fire an event when a ROI is updated. This event is then caught in the web app and handled accordingly.
• onBrowserChange function was created that acts as a wrapper, for the createSessionObj manager function and is called from a useEffect that gets triggered by a change in the browserChnange state. This was done to handle the null state values in callbacks mentioned in previous comments.
• The createSessionObj function accepts an argument for what was changed in the browser, e.g. "locuschange", "updateuserdefinedroi" etc. Naming for these events was modeled after the naming for IGV.js events. The function then generates and returns a session object which is subsequently set as the sessionJSON state.