diff --git a/docs/charts/01-Overview.md b/docs/charts/01-Overview.md new file mode 100644 index 000000000..782219cc1 --- /dev/null +++ b/docs/charts/01-Overview.md @@ -0,0 +1,23 @@ +# Overview + +**Arranger Charts** is a plugin for Arranger UIs for adding interactive aggregated data charts to React applications. It currently supports Bar and Sunburst charts. Arranger Charts also uses a React context provider to request data from Arranger Server for all charts on the page. Interacting with the charts can update the filters for data requested from Arranger Server. + +## Key Features + +- Leverages the [Nivo charts](https://github.com/plouc/nivo) library. +- Integrates with Arranger theming for configuring colour schemes. +- **ChartsProvider:** React context provider that requests all the data for all charts inside the provider. +- **Bar chart:** Responsive, horizontal bar chart with configurable colours, tooltips, and sorting. +- **Sunburst chart:** Responsive sunburst chart showing relationships between broad and specific categories. + +## Note About Arranger 3.1 and Multiple Catalogues/Indices + +Although Arranger 3.1 has been updated to support multiple catalogues (that is, Elasticsearch indices), currently the Arranger Charts library does not support this. + +Arranger Charts will only support one index/catalogue, with the document type `file`. + +[Arranger Charts issue for allowing multiple indices](https://github.com/overture-stack/arranger/issues/1084) + +## Dashboard Example + +![Dashboard with Arranger Charts](full-screenshot.png) diff --git a/docs/charts/02-Setup.md b/docs/charts/02-Setup.md new file mode 100644 index 000000000..d7d302147 --- /dev/null +++ b/docs/charts/02-Setup.md @@ -0,0 +1,53 @@ +# Setup + +For adding Arranger Charts in a React application. + +## Prerequisites + +- Node 24 or higher +- React 18 +- Arranger Components 3 (for the data context provider) + +## Developer Setup + +This guide will walk you through installing Arranger Charts in your React application, and adding it to a page or component. + +### Installation + +```bash +npm i @overture-stack/arranger-charts @overture-stack/arranger-components +``` + +### Quick Start + +Wrap a charts in required providers: `ArrangerDataProvider`,`ChartsProvider` and `ChartsThemeProvider`. + +Chart component is responsive to its parent container's dimensions. + +```jsx +import { ChartsProvider, ChartsThemeProvider, BarChart, SunburstChart } from '@overture-stack/arranger-charts'; +import { ArrangerDataProvider } from '@overture-stack/arranger-components'; + +function App() { + return ( + + + + console.log(data) }} + /> + + + + ); +} +``` + +### Dependencies + +Arranger Charts requires an `ArrangerDataProvider` from `@overture-stack/arranger-components` as a parent component to handle data fetching and SQON state management. diff --git a/docs/charts/03-Guides/01-Usage.md b/docs/charts/03-Guides/01-Usage.md new file mode 100644 index 000000000..56eaee3cd --- /dev/null +++ b/docs/charts/03-Guides/01-Usage.md @@ -0,0 +1,174 @@ +# Usage + +This guide covers how to use Arranger Charts, what components are available, and React props for each component. + +## Components + +### ChartsProvider + +The main provider that manages chart registration and data fetching, and coordinates multiple charts. + +#### Props + +| Name | Type | Required | Description | +| ----------------------- | --------- | -------- | -------------------------------------- | +| `debugMode` | `boolean` | No | Enable verbose logging for development | +| `disableIncludeMissing` | `boolean` | No | Hide properties with "No Data" | +| `loadingDelay` | `number` | No | Delay network results by milliseconds | + +#### Example + +```jsx + + {/* ChartsThemeProvider */} + +``` + +### ChartsThemeProvider + +Provides theme configuration and custom components to all child charts. You can nest multiple `` components under a single ``. + +#### Props + +| Name | Type | Required | Description | +| ---------------------- | ---------------- | -------- | ------------------------------------- | +| `colors` | `string[]` | No | Array of hex colors for chart theming | +| `components` | `object` | No | Custom fallback components | +| `components.EmptyData` | `ReactComponent` | No | Custom empty state component | +| `components.ErrorData` | `ReactComponent` | No | Custom error component | +| `components.Loader` | `ReactComponent` | No | Custom loading component | + +#### Example + +```jsx + + {/* Charts */} + +``` + +### BarChart + +Renders a horizontal bar chart for aggregation data. + +#### Props + +| Name | Type | Required | Description | +| -------------------------------------- | ---------- | -------- | --------------------------------------------------------------------------------------------------- | +| `disableTopBarsCount` | `boolean` | No | Disables the "Top `bars` of `totalBars`" flag at the top right of charts. | +| `fieldName` | `string` | Yes | GraphQL field name to visualize | +| `handlers` | `object` | No | Event handlers | +| `handlers.onClick` | `function` | No | Callback when clicking a bar segment | +| `maxBars` | `number` | Yes | Maximum number of bars to display | +| `ranges` | `Range[]` | No | For numeric fields, specify value ranges. A `Range` is `{ key: string, from: number, to: number }`. | +| `theme` | `object` | Yes | Chart configuration options | +| `theme.sortByKey` | `string[]` | No | Array of keys to sort the data by. | +| `theme.axisBottom.customTickValueSize` | `number` | `No` | For setting a custom step size for the bottom (X) axis | + +#### Example + +```jsx + + + + { + console.log('Clicked', data.label, data.value); + }, + }} + maxBars={15} + theme={{ + sortByKey: ['Brain', 'Lung', 'Breast', '__missing__'], + }} + /> + + + +``` + +#### Screenshot + +![Example of a bar chart](barchart.png) + +### SunburstChart + +Creates a sunburst chart showing relationships between broad and specific categories. + +#### Props + +| Name | Type | Required | Description | +| ------------------ | ---------- | -------- | ----------------------------------------------- | +| `fieldName` | `string` | Yes | GraphQL field name to visualize | +| `maxSegments` | `number` | Yes | Maximum number of segments to display | +| `mapper` | `function` | Yes | Maps outer ring values to inner ring categories | +| `handlers` | `object` | No | Event handlers | +| `handlers.onClick` | `function` | No | Callback when clicking a segment | +| `theme` | `object` | No | Chart configuration options | + +#### Example + +```jsx + + + + { + if (value.startsWith('C78')) return 'Metastatic'; + if (value.startsWith('C50')) return 'Breast Cancer'; + return value; + }} + handlers={{ + onClick: (data) => { + console.log('Selected category:', data); + }, + }} + /> + + + +``` + +#### Screenshot + +![Example of a sunburst chart](sunburstchart.png) + +## Field Types + +Charts automatically detect field types from Arranger's extended mapping: + +- **Aggregations**: Categorical fields +- **NumericAggregations**: Numeric fields that require range specifications + +For numeric fields, provide ranges: + +```jsx + +``` diff --git a/docs/charts/03-Guides/02-Development.md b/docs/charts/03-Guides/02-Development.md new file mode 100644 index 000000000..d2dbd8475 --- /dev/null +++ b/docs/charts/03-Guides/02-Development.md @@ -0,0 +1,46 @@ +# Development + +This guide covers how to develop or contribute to Arranger Charts. For using Arranger Charts in a React application, see [Guides/Usage](01-Usage.md). + +## Local Development + +```bash +# Install dependencies +npm install + +# Build and watch for changes +npm run dev +``` + +## Using Local Versions of Arranger Charts & Arranger Components + +To develop Arranger modules and see changes in your React app in real-time, you can use `npm link`: + +```bash +# in your local Arranger folder +cd modules/charts +npm link +cd ../.. +cd modules/components +npm link +``` + +Then link these packages in your consumer React project: + +```bash +# in your local React app +npm link @overture-stack/arranger-charts +npm link @overture-stack/arranger-components +``` + +To remove these links: + +```bash +# in your local React app +npm unlink @overture-stack/arranger-charts +npm unlink @overture-stack/arranger-components +``` + +## Debug Mode + +Enable verbose logging by setting the `debugMode` prop on `ChartsProvider`. diff --git a/docs/charts/03-Guides/barchart.png b/docs/charts/03-Guides/barchart.png new file mode 100644 index 000000000..a02bb8836 Binary files /dev/null and b/docs/charts/03-Guides/barchart.png differ diff --git a/docs/charts/03-Guides/sunburstchart.png b/docs/charts/03-Guides/sunburstchart.png new file mode 100644 index 000000000..a158ecbd6 Binary files /dev/null and b/docs/charts/03-Guides/sunburstchart.png differ diff --git a/docs/charts/full-screenshot.png b/docs/charts/full-screenshot.png new file mode 100644 index 000000000..46d659057 Binary files /dev/null and b/docs/charts/full-screenshot.png differ diff --git a/modules/charts/README.md b/modules/charts/README.md index cd9e7eab9..9987f7e45 100644 --- a/modules/charts/README.md +++ b/modules/charts/README.md @@ -1,186 +1,112 @@ # Arranger Charts -A React chart library for visualizing Arranger aggregation. +A React chart library for visualizing Arranger aggregation. Uses the [Nivo](https://github.com/plouc/nivo) library, built on D3, to render charts. -## Installation +
-```bash -npm i @overture-stack/arranger-charts -``` - -## Quick Start - -Wrap a charts in required providers: `ArrangerDataProvider`,`ChartsProvider` and `ChartsThemeProvider`. -Chart component is responsive to parent containers dimensions. - -```jsx -import { ChartsProvider, ChartsThemeProvider, BarChart, SunburstChart } from '@overture-stack/arranger-charts'; - -function App() { - return ( - - - -
- console.log(data) }} - /> -
- - - - ); -} -``` - -## Dependencies - -Arranger Charts requires an `ArrangerDataProvider` from `@overture-stack/arranger-components` as a parent component to handle data fetching and SQON state management. +>
+> +>
+> +> _Arranger Charts is part of [Overture](https://www.overture.bio/), a collection of open-source software microservices used to create platforms for researchers to organize and share genomics data._ -## Components +## Repository Structure -### ChartsProvider +The repository is organized with the following directory structure: -The main provider that manages chart registration, data fetching, and coordinates multiple charts. +``` +charts/ +├── .storybook/ +└── src/ + ├── arranger/ + ├── components/ + │ ├── charts/ + │ │ ├── Bar/ + │ │ │ └── nivo/ + │ │ └── Sunburst/ + │ └── Provider/ + ├── gql/ + ├── hooks/ + ├── logger/ + ├── query/ + ├── utils/ + └── main.tsx +``` -**Props:** +Brief description of each folder: -- `debugMode` (boolean): Enable verbose logging for development -- `loadingDelay` (number): Delay network results by milliseconds +- **.storybook/** - Storybook hasn't been fully implemented at this time. +- **arranger/** - Types for working with Arranger GQL responses. +- **components/charts/** - React components for Bar and Sunburst charts. +- **components/Provider/** - `ChartsProvider` combines all of its child chart requests into one API request, then maps the result into chart data. +- **gql/** - Functions for creating GraphQL queries. +- **hooks/** - React hooks for querying GraphQL & creating the color scheme for all charts on the page. +- **logger/** - Simple logger. +- **query/** - Generates one query for all charts, for the `ChartsProvider`. +- **utils/** - Utility scripts for handling API responses. +- **main.tsx** - Barrel/export file. -### ChartsThemeProvider +## Local development -Provides theme configuration and custom components to all child charts. You can nest multiple under a single . +To use Arranger Charts in your project, you need the following prerequisites: -**Props:** +- Node 24 or above +- React 18 +- Arranger Components 3 (for the data context provider) -- `colors` (string[]): Array of hex colors for chart theming -- `components`: Custom fallback components - - `Loader`: Custom loading component - - `ErrorData`: Custom error component - - `EmptyData`: Custom empty state component +### Installation -```jsx - - {/* Charts */} - -``` - -### BarChart - -Renders horizontal bar charts for aggregation data. - -**Props:** - -- `fieldName` (string, required): GraphQL field name to visualize -- `maxBars` (number, required): Maximum number of bars to display -- `ranges` (Range[]): For numeric fields, specify value ranges -- `handlers`: Event handlers - - `onClick`: Callback when clicking a bar segment -- `theme`: Chart configuration - - `sortByKey`: Array of keys to define custom sort order. Important to account for all values - e.g., `['Male', 'Female', '__missing__']` - -```jsx - { - console.log('Clicked', data.label, data.value); - }, - }} -/> +```bash +npm i @overture-stack/arranger-charts ``` -### SunburstChart - -Creates sunburst chart showing relationships between broad and specific categories. - -**Props:** - -- `fieldName` (string, required): GraphQL field name to visualize -- `maxSegments` (number, required): Maximum number of segments to display -- `mapper` (function, required): Maps outer ring values to inner ring categories -- `handlers`: Event handlers - - `onClick`: Callback when clicking a segment -- `theme`: Chart configuration options - -```jsx - { - // Map specific diagnosis codes to broader categories - if (diagnosisCode.startsWith('C78')) return 'Metastatic'; - if (diagnosisCode.startsWith('C50')) return 'Breast Cancer'; - return 'Other'; - }} - handlers={{ - onClick: (data) => { - console.log('Selected category:', data); - }, - }} -/> -``` +See Documentation links below for setup instructions. -## Field Types +## Documentation -Charts automatically detect field types from Arranger's extended mapping: +Technical resources for those working with or contributing to the project are available from our official documentation site. The following content can also be read and updated within the `/docs` folder of this repository. -- **Aggregations**: Categorical fields -- **NumericAggregations**: Numeric fields that require range specifications +!TODO UPDATE LINKS -For numeric fields, provide ranges: +- **[Component Name Overview](link)** +- [**Setting up the Development Environment**](link) +- [**Common Usage Docs**](link) -```jsx - -``` +## Development Environment -## Development +- [NPM](https://www.npmjs.com/) Project manager +- [Node.js](https://nodejs.org/en) Runtime environment (v24 or higher) +- [VS Code](https://code.visualstudio.com/) As recommended code editor. Plugins recommended: + - [ESLint](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint) + - [vscode-styled-components-cre-edition](https://marketplace.visualstudio.com/items?itemName=anthonycjw.vscode-styled-components-cre-edition) + - [Prettier - Code formatter](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) + - [Makefile Tools](https://marketplace.visualstudio.com/items?itemName=ms-vscode.makefile-tools) + - [Pretty TypeScript Errors](https://marketplace.visualstudio.com/items?itemName=yoavbls.pretty-ts-errors) + - [Todo Tree](https://marketplace.visualstudio.com/items?itemName=gruntfuggly.todo-tree) + - [Chat Customizations Evaluations](https://marketplace.visualstudio.com/items?itemName=ms-vscode.vscode-chat-customizations-evaluations) -### Local Development +## Support & Contributions -```bash -# Install dependencies -npm install +- For support, feature requests, and bug reports, please see our [Support Guide](https://docs.overture.bio/community/support). -# Build and watch for changes -npm run dev -``` +- For detailed information on how to contribute to this project, please see our [Contributing Guide](https://docs.overture.bio/docs/contribution). -To ensure all code is using the same Arranger contexts, also `npm i` to the the consumer projects `@overture-stack/arranger-components` dependency. +## Related Software -```bash -npm i -``` +The Overture Platform includes the following Overture Components: -From consumer project: +| Software | Description | +| ------------------------------------------------------- | ----------------------------------------------------------------------------------------- | +| [Score](https://github.com/overture-stack/score/) | Transfer data to and from any cloud-based storage system | +| [Song](https://github.com/overture-stack/song/) | Catalog and manage metadata associated to file data spread across cloud storage systems | +| [Maestro](https://github.com/overture-stack/maestro/) | Organizing your distributed data into a centralized Elasticsearch index | +| [Arranger](https://github.com/overture-stack/arranger/) | A search API with reusable search UI components | +| [Stage](https://github.com/overture-stack/stage) | A React-based web portal scaffolding | +| [Lyric](https://github.com/overture-stack/lyric) | A model-agnostic, tabular data submission system | +| [Lectern](https://github.com/overture-stack/lectern) | Schema Manager, designed to validate, store, and manage collections of data dictionaries. | -```bash -npm i -``` +If you'd like to get started using our platform [check out our quickstart guides](https://docs.overture.bio/guides/getting-started) -### Debug Mode +## Funding Acknowledgement -Enable verbose logging by setting the `debugMode` prop on `ChartsProvider`. +Overture is supported by grant #U24CA253529 from the National Cancer Institute at the US National Institutes of Health, the Digital Research Alliance of Canada and additional funding from Genome Canada, the Canada Foundation for Innovation, the Canadian Institutes of Health Research and the Ontario Institute for Cancer Research. diff --git a/modules/charts/ov_logo.png b/modules/charts/ov_logo.png new file mode 100644 index 000000000..d612af040 Binary files /dev/null and b/modules/charts/ov_logo.png differ