Trrack is a library to create and track provenance (history) in web-based apps. Trrack allows you to create and maintain a non-linear provenance graph representing the history of the state of your visualization. Through this graph, you can easily implement complete action recovery, as well as store custom metadata and annotations.
Trrack also allows for easy sharing of a visualization's current state through URL sharing. To share entire session history, Trrack allows for the import and exporting of provenance graphs, as well as has built in integration with firebase to store the graphs.
For full documentation, see http://vdl.sci.utah.edu/trrack-examples/api/trrack
Also check out the paper to learn about the design philosophy.
If you're using Trrack in an academic project, please cite:
Z. T. Cutler, K. Gadhaveand A. Lex, “Trrack: A Library for Provenance Tracking in Web-Based Visualizations”, osf.io preprint. https://doi.org/10.31219/osf.io/wnctb.
Trrack does back-end history management only. If you want to use the history/provenance visualization as well, check out the trrack-vis library, which is designed to provide a customizable front-end for the Trrack library.
Here are some examples showing you how to get started:
Here are example of a few complex system susing Trrack:
npm install --save-dev @visdesignlab/trrack
yarn add @visdesignlab/trrack
To use Trrack, your application has to be explicit about state: any action that you want to track has to be captured as part of a state that you pass to the Trrack library.
Trrack allows instant sharing of state via URL parameter. State sharing is turned on by default, and the only setup required is to call done after you have finished creating observers and loading data, telling trrack it can import the URL state. When turned on, changing the state of your application will automatically update the URL parameter. Pasting the entire URL into a different web browser will import the state automatically.
The graph which Trrack creates and utilizes may be visualized using Trrack-Vis. Trrack-Vis has default icons associated with the event type object, the second generic parameter (S) passed to Trrack. To use Trrack-Vis in a javascript environment, you will need to import and use the ProvVisCreator function. See this simple example for how to set up Trrack-Vis with default functionality. For further documentation and a list of customizable parameters that can be passed to Trrack-Vis, see http://vdl.sci.utah.edu/trrack-examples/api/trrack-vis/interfaces/provvisconfig.html
To integrate FireBase with Trrack, you first need to set up a Firebase project. Once you've done so, navigate to Settings -> Project settings -> general, and you should find a "firebaseConfig" object on that page. That exact object will be passed into initProvenance. Once done, Trrack will automatically store all created nodes to your Firebase project.
To utilize Trrack with other servers, you will use exportProvenanceGraph to export the entire graph json and importProvenanceGraph to import the same json file.
import { initProvenance, Provenance, ProvenanceGraph } from '@visdesignlab/trrack';
// ************************************************
// Setup all the interfaces and types
enum SortByOptions {
PETAL_LENGTH = 'PETAL_LENGTH',
PETAL_WIDTH = 'PETAL_WIDTH',
SEPAL_LENGTH = 'SEPAL_LENGTH',
SEPAL_WIDTH = 'SEPAL_WIDTH'
}
enum SortDirection {
ASCENDING = 'ASCENDING',
DESCENDING = 'DESCENDING'
}
// This is the interface which defines the state of your application. Instance of this interface will be tracked
interface ApplicationState {
irisDatasetPath: string;
sortConfig: {
sortBy: SortByOptions;
sortDirection: SortDirection;
};
}
// The instance of the ApplicationState which will be tracked. This is also the root state in Provenance Graph
const initialState = {
irisDatasetPath: '/path/to/dataset/iris.csv',
sortConfig: {
sortBy: SortByOptions.PETAL_LENGTH,
sortDirection: SortDirection.ASCENDING
}
};
// Initialize provenance tracking by passing root state.
const provenance = initProvenance(initialState);
// Add observers to do something on state change.
provenance.addObserver(['irisDatasetPath'], () => {
// Dataset changed, do something
});
provenance.addObserver(['sortConfig', 'sortDirection'], (state?: ApplicationState) => {
// Sort direction changed, do something
});
provenance.addObserver(['sortConfig', 'sortBy'], (state?: ApplicationState) => {
// Sort by attribute changed, do something
});
// Call this when all the observers are defined.
// This is optional and only used when you want to enable sharing and loading states from URL.
// Refere documentation for advanced usage scenario.
provenance.done();
// Define actions to change various states. This can be as granular or coarse as you wish.
// The state here will be the current state which provenance passes in.
const changeSortDirection: ActionFunction<ApplicationState> = (
state: ApplicationState,
sortDirection: SortDirection
) => {
state.sortConfig.sortDirection = sortDirection;
return state;
};
const changeSortByAttribute: ActionFunction<ApplicationState> = (
state: ApplicationState,
sortBy: SortByOptions
) => {
state.sortConfig.sortBy = sortBy;
return state;
};
const changeDataset: ActionFunction<ApplicationState> = (
state: ApplicationState,
newFilePath: string
) => {
state.irisDatasetPath = newFilePath;
return state;
};
// Then apply the above actions as needed using applyAction method.
// It takes in multiple arguments. The first two are required.
// First is the label describing the event, second is the function. This can be anonymous function.
// Third is optional parameters which will be passed to the function passed as second arguments.
let action = provenance.addAction('Changing dataset', changeDataset);
action
.addArgs(['/path/to/new/dataset'])
.applyAction();
git clone git@github.com:visdesignlab/trrack.git
npm t
: Run test suitenpm start
: Run npm run build
in watch modenpm run test:watch
: Run test suite in interactive watch modenpm run test:prod
: Run linting and generate coveragenpm run build
: Generate bundles and typings, create docsnpm run lint
: Lints codenpm run commit
: Commit using conventional commit style (husky will tell you to use it if you haven't :wink:)Project created using Typescript library starter by alexjoverm
Generated using TypeDoc