gumuslab / clustergrammer

WebGL Clustergrammer JavaScript Library

About

Clustergrammer, Clustergrammer2, and Clustergrammer-GL are packages originally developed by the Human Immune Monitoring Center and Ma'ayan lab at the Icahn School of Medicine at Mount Sinai.

This work is now being continued by Gumus Lab, also at ISMMS, and the code is being updated and maintained so it can be used in genomics project that the Gumus Lab is working on.

The project lead is Kevin Ulrich, who can be contacted here.

The original documentation for Clustergrammer and all its associated projects is located here, though it mainly applies in terms of creating formatted data with Clustergrammer-PY and the desired format for the data for Javascript applications.

Contributions

Contributions are totally welcome -- there are two ways to contribute:

1. Find an issue that you want to tackle and comment on it/submit a PR for it.
2. If you find a bug with Clustergrammer or want to make an enhancement, please write an issue detailing the change and make sure the community is on board, and then submit a PR for the changes.

Setup for Local Development

1. Make sure you have Node 16+ (ideally use LTS) -- see NVM for Node version management
2. Clone the code to your local machine
3. Run yarn to install all required node modules
4. Run yarn start to build the package locally into the example/example-app folder and watch for changes (will rebuild automatically)
5. Open a new terminal tab or window, cd example/example-app, run yarn to install all required node modules and then run yarn start to start the local test app
6. Happy development! Everything should be kept in sync -- it is not quite hot reload though so you will have to refresh the webpage after you make changes to see them reflected.

Let me know if you have any ideas on how to make the Clustergrammer isntances update when the source code updates (right now the sources on the page update fine but it doesn't reflect in the UI)

Licensing

The original license still applies, and the code is MIT-licensed.

clustergrammer's Issues

Investigate DeckGL

https://deck.gl/docs/api-reference/aggregation-layers/grid-layer
https://deck.gl/docs/api-reference/core/orthographic-view
DeckGL might be an easy platform that could help fix some issues. Investigate if we'd have to rewrite or if we could just use it for the cells of the heatmap or something? Also look into performance, Nick said that it wasn't necessarily performant out of the box.

Swipe to pan

Right now the only way to pan the chart when zoomed in is to click and drag, but you should be able to two-finger swipe on a touchpad as well.

Tooltip freezes

Describe the bug
The tooltip freezes sometimes when zooming or changing from one type to another (such as from dendrogram to matrix cell)

Dendrogram slider text doesn't render with multiple CG isntances

If you have more than one Clustergrammer instance, the text of the dendrogram sliders only shows on the first one.

Add label click handler/differentiate onclick

We need to have an onclick handler for labels, currently we only have an onclick handler for matrix cells.

We could also just keep only the current onclick and return different information (consistency would be key if possible) depending on where the cursor is (check state.tooltip.tooltip_type)

Either way we probably want these methods to return an object so the user doesn't have to guess at how many params are returned (could also use ...rest but a ret object seems fine).

Remove unnecessary dependencies

We should remove unnecessary dependencies, such as d3-v6-tip, to reduce bundle size.

Multiple instances of Clustergrammer have duplicate labels

If two Clustergrammer charts are rendered (with different or the same data), the labels from both will render on both, overlapping.

Screenshot:

Zooming in on one chart also causes the labels (though no other elements) of the other chart to zoom/distort

Screenshot:

Since this is only affecting the labels, one would think it might be related to the webworker label rendering added in #3 and #7 , but the webworker should be unused in Firefox since it isn't possible there, and the issues still exist in Firefox. This issue has likely existed for some time therefore, or at least since the initial project refactor.

Zooming in/out past max zoom causes unnecessary re-renders

Problem
If you zoom out, even if fully zoomed out, Clustergrammer will rerender for every zoom action (could be 10+ times if on a trackpad for instance). Most likely the same happens when fully zoomed in (untested)

Solution
Guard either zooming if trying to zoom in/out past max or guard re-rendering based on a zoom action if trying to zoom past max. Make sure you don't accidentally keep a switch from being reset or something like that if going for the second solution.

Label Loading Placeholder

After landing #3, the framework can load and generate labels asynchronously.
Therefore, we need to take care of a placeholder right now.
The proposed solution is:

1. Add a new state/event indicate the loading/generating stage of the label.
2. In this stage, the framework should render or display a placeholder.
3. We might also want to allow a callback/hook to be passed, in case, users need to do customization.

Tooltip only shows on first Clustergrammer instance

If you have more than one Clustergrammer instance, the tooltip only renders on that one.

Matrix cells reset on zoom/reorder

Describe the bug
Matrix cells reset to the original ordering/clustering (clust/clust for row/col) if you zoom after reordering/reclustering.

To Reproduce
Steps to reproduce the behavior:

1. Select a new ordering, such as "sum"
2. After the heatmap finishes reordering, zoom in -- the matrix cells will reset to their original view

Also:

1. Change column ordering to "sum"
2. Change ordering again, say to var
3. The matrix cells will start from a clust/clust ordering instead of the sum/clust ordering.

Chart legend

Add chart legend, which should be a gradient on the right of the chart and should show the min and max values and the color that corresponds to each in a vertical legend.

Should look like:

Add options to set legend placement

Currently the legend is fixed in where it displays. This feature intends to add a parameter to Clustergrammer called legendOptions which would allow the user to change things like whether it's horizontal or vertical, min-max or max-min, and where the legend is positioned. Other options can be planned as comments on this issue.

(originally suggested by @WenheLI here)

Bug: Fix sorting on clicked label

When double clicking a label, it is supposed to order the row/col by its value. Currently this is not the case, as the sorting indices seem to be a little off.

Default (on load):

Current behaviour on label sort:

Wanted behaviour on label sort:

Clicking on Dendrogram slider produces "NaN" value

If you click anywhere on the dendrogram slider instead of using the slider circle, it makes the value "NaN" and the dendrograms segment fully.

Reducers - handle state gracefully

There are a bunch of reducers under src/state/reducers. Whilst they seem to be working fine, they don't seem to align with the redux/react docs entirely.

There are 3 areas where improvement could be done:

1. Remove unnecessary state = * assignment. We shouldn't mutate the state.
2. _.merge mutates the state. It should be merge({}, state, action.payload) (Caution: This is rather expensive. Maybe immutable-ops#deepMerge is an option)
3. Remove unnecessary return state, as the reducer takes care of it. Only in cases where we want action.payload to replace the state we should return action.payload.

Further thoughts:
Maybe, the reducers could be a little more detailed. Just to avoid to have to deal with functionalities like _.merge. If we would know where the change needs to be applied, we could probably get rid of the merge functionality. This would help the state (and any re-render).

Make Clustergrammer work with non 1.0 aspect ratio

Right now Clustergrammer really only works if it's given a square parent container, even though it will resize. It should scale nicely even if the aspect ratio is not exactly 1:1.

Fix upside down x-axis dendrogram slider label

A bit back I flipped the x-axis dendrogram slider so it would match the y-axis one, however now the text is upside down! :D

We need the text to be flipped about the x axis.

Fix label clicking

Right now, if zoomed fully in, the top couple labels do not register via singleClicking, in this screenshot:

The first label you can click on the y-axis is DEF vs GHI

Fix typings for store

In adding namespaced redux store behavior to make multiple instances of Clustergrammer work on the same page, typings were broken. There's a few issues which concern this interface in store.ts

export interface NamespacedStore extends Store {
  actions: any;
  select: (path: string | string[]) => any;
  selectAll: () => Record<SliceNames, any>;
}

Typings for select and selectAll

• selectAll should be easy since right now it's returning Record<SliceNames, any> and we just need to replace any with RootState
• select can probably just replace string with SliceNames? It's unlikely that we can fix string[] and don't really use it anyways. It also needs to return a better type than any, maybe Partial<RootState> or something else that will at least get us going on type hints?

Typings for actions
This is a big one and I'm not exactly sure how to go about it. We'll probably have to rewrite all our slices in this way:

- import { createSlice, PayloadAction } from "@reduxjs/toolkit";
+ import {
+   createSlice,
+   PayloadAction,
+   SliceCaseReducers,
+   ValidateSliceCaseReducers,
+ } from "@reduxjs/toolkit";
import { merge } from "lodash";
+ import { RootState } from "../store/store";

export interface ArrsState {
  opacity_arr: any[];
  position_arr: {
    ini: any[][];
    new: any[][];
  };
}

const initialState: ArrsState = {} as ArrsState;

+ const reducers = {
+  setArrsState: (state: RootState, action: PayloadAction<ArrsState>) => {
+    state = action.payload;
+    return state;
+  },
+  mutateArrsState: (state: RootState, action: PayloadAction<Partial<ArrsState>>) => {
+    state = merge(state, action.payload);
+    return state;
+  },
+};

+ export type ArrsActions = keyof typeof reducers; // THIS IS THE IMPORTANT BIT

export const arrsSlice = (id: string) =>
  createSlice({
    name: `${id}_arrs`,
    initialState,
    // The `reducers` field lets us define reducers and generate associated actions
+   reducers: reducers as ValidateSliceCaseReducers<
+      ArrsState,
+      SliceCaseReducers<ArrsState>
+   >,
-    reducers: {
-      setArrsState: (state, action: PayloadAction<ArrsState>) => {
-        state = action.payload;
-        return state;
-      },
-      mutateArrsState: (state, action: PayloadAction<Partial<ArrsState>>) => {
-        state = merge(state, action.payload);
-        return state;
-      },
-    },
  });

And then doing a union of all the actions types as the type of actions.

Dendrogram slider for x-axis does not rotate on Safari

Dendrogram slider for the x-axis does not rotate, problem seems to occur only in Safari.

Screenshots

Desktop

• OS: Mac OS
• Safari
• Version 16.0