Integration

Prerequisites

• Node: v18.19.0 and newer
• Angular CLI: 19

Installing the Library

Run the following command to install the library: npm install ngx-oecd-ai-dataviz

Configuration

1. Update angular.json

a. Add required assets

Add the following to the assets array under project/architect/build/options:

{
  "glob": "**/*",
  "input": "node_modules/ngx-oecd-ai-dataviz/assets",
  "output": "/assets"
}

b. Add Required Styles and Fonts

Add the following to the styles array under project/architect/build/options:

styles: [
  ...,
  "node_modules/ngx-oecd-ai-dataviz/assets/fonts/index.scss",
  {
    "input": "node_modules/ngx-oecd-ai-dataviz/styles/indigo-pink.css"
  }
]

Importing the Library

Modules Version

1. Open src/app/app.module.ts

2. Add the library module import: import { NgxOecdAiDatavizModule } from 'ngx-oecd-ai-dataviz';

3. Include NgxOecdAiDatavizModule in the @NgModule imports array.

Standalone Version

1. Open src/app/app.component.ts

2. Import the library module: import { NgxOecdAiDatavizModule } from 'ngx-oecd-ai-dataviz'

3. Add the standalone property to the @Component decorator:

  @Component({
    standalone: true,
    imports: [NgxOecdAiDatavizModule],
    ...
  })

Use case

Example with config

You can provide a custom configuration to the component using the config property

Update app.component.ts Add the following configuration:

config = {
  id: 'bar-chart-component',
  name: 'Bar Chart Component',
  isActive: true,
  isMobile: true,
  dataConfigs: {
    database: 'bigquery\_\_studyportals',
    table: 'country_platform_time_series',
    defaultEntityNTopItems: 5,
  },
  chartConfig: {
    type: 'BarChart',
  },
};

Update app.component.html Add the component to your template:

<div class="content">
  <div class="widget-detail-wrapper-chart" [style]="{height: '80vh', width: '80vw'}">
    <lib-oecd-ai-dataviz [config]="config" />
  </div>
</div>

Example with id

The component can fetch configuration dynamically using an id property.

Update app.component.ts Add the chartId variable:

chartId = 'Research---OpenAlex-Countries--ai-publication-types-by-country'

Update app.component.html Add the component to your template:

<div class="content">
  <div class="widget-detail-wrapper-chart" [style]="{height: '80vh', width: '80vw'}">
    <lib-oecd-ai-dataviz [id]="chartId" [isMobile]="false" configBaseUrl="https://observatory.oecdai.org/api/v1/chart-cfg" />
  </div>
</div>

Component props

id

A string that retrieves the configuration from the API automatically, eliminating the need to pass it manually as a prop.

isMobile

A boolean flag that adjusts the interface layout for optimal display on mobile devices.

isDarkMode

A boolean flag that sets the widget template to dark mode.

unboundedHeight

A boolean flag that forces the widget chart's to follow the datavizConfig aspectRatio if specified in the config object. In case both unboundedHeight is enabled and aspectRatio is configured, the widget will automatically resize it's height in order to accomodate chosen aspect ratio of the chart graphics. Otherwise it will occupy the parent container (as given) without growing or shrinking.

selectedFiltersHash

A Base64-encoded string representing a customized filter selection. This value should be obtained from the selectedFiltersChange callback, described below.

config

A complete configuration object that must be provided if the id property is not set

{
  id: string;
  name: string;
  logoLinkUrl?: string;
  description: string;
  note?: string; //HTML formatted text
  isMobile?: Boolean;
  isActive: Boolean;
  shareConfigs?: {
    hashQueryParam?: string,
    url?: string,
    shareDescription?: string,
    embedUrl?: string;
    embedHashQueryParam?: string;
  },
  dataConfigs: {
    database: string;
    table: string;
    metadataApiUrl?: string;
    graphqlApiUrl?: string;
    isEntityTable?: boolean;
    defaultEntityNTopItems?: number;
    isEntityNTopItemsPerSample?: boolean;
    sortDescOrder?: boolean;
    maxEntityNTopItems?: number; //Sankey nItems slider
    minEntityNTopItems?: number; //Sankey nItems slider
    mapbox?: {
      accessToken: string;
    };
  },
  chartConfig: {
    type: 'LineChart' | 'BarChart' | 'HorizontalBarChart' | 'Map' | 'PieChart' | 'StackBarChart' | 'SankeyDiagram' | 'BubbleListChart' | 'BubbleChart' | 'BumpChart' | 'RadarChart' | 'HeatMapChart' | 'Table';
    tableNumberFormat?: Intl.NumberFormat;
    datavizConfig?: {
      /** Aspect ratio of the chart in CSS aspect-ratio format (e.g., "16 / 9") */
      aspectRatio: string,
      LegendBehavior?: {
        showLegend: boolean,
      },
      /** HeatMapChart only. Adds a summary row at the bottom: 'avg' for average, 'none' to disable */
      summaryRow?: 'avg' | 'none'
    },
    colorKey?: string;
    defaultDate?: string | number | [string | number, string | number],
    filters?: {
      internalLinks?: { //Sankey chart internal links checkbox
        label: string
      }
      samplingIntervals?: Array<'YEAR' | 'YEAR_MONTH' | 'YEAR_QUARTER'>
    };
  },
  controlsConfig: {
    percentage?: { default: boolean };
    divide?: Array<{
      label: string;
      value: string;
      default?: boolean;
      times?: number;
    }>;
    normalizeLastYear?: { default: true };
    logScale?: { default: Boolean };
  },
  columnMappingConfig = {
    itemsColumn: {
      columnId: string;
      hideSelector?: Boolean,
      multiselect?: Boolean;
      defaultSelectedIds?: Array<string | number>;
      blackList?: Array<string>;
    },
    indicatorColumns?: Array<{
      columnId: string;
      hideSelector?: Boolean,
      multiselect?: Boolean;
      defaultSelectedIds?: Array<string | number>;
      blackList?: Array<string>;
      dimension?: 'x' | 'y' | 'size';
    }>,
    filterColumns?: Array<{
      columnId: string;
      hideSelector?: Boolean,
      multiselect?: Boolean;
      defaultSelectedIds?: Array<string | number>;
      blackList?: Array<string>
    }>,
    tableColumns?: Array<Array<{
      columnId: string
    }>>
  }
}

config columnMappingConfig detailed prop

This configuration determines how metadata columns are used in the widget.

If the map is empty or not set, the widget will default to using filters based on the metadata column types.

itemsColumn

Adding a specific value means that this will be the filter for the items to be displayed.

Options

{
  columnId: string;
  hideSelector?: Boolean,
  multiselect?: Boolean;
  defaultSelectedIds?: Array<string | number>;
}

indicatorColumns

Adding values means these will be used as indicator values and displayed as a dropdown selector. The database request will be ordered by the first value.

Options

Array<
  {
    columnId: string;
    hideSelector?: Boolean,
    multiselect?: Boolean;
    defaultSelectedIds?: Array<string | number>;
  }
>

filterColumns

Adding values means these will be used as filters and shown as a dropdown selector.

IMPORTANT: When adding one value, the widget will remove the default dropdown filters, so it is important to define every filter that you want to be displayed.

Options

Array<
  {
    columnId: string;
    hideSelector?: Boolean,
    multiselect?: Boolean;
    defaultSelectedIds?: Array<string | number>;
  }
>

tableColumns

Defines the columns to be shown in the table. By default, the widget builds the table using the 'dateColumn,' 'itemColumn,' and 'indicatorColumn' column structure. However, this can be redefined using this property.

Options

Array<
  {
    columnId: string;
  }
>

Component callbacks

selectedFiltersChange

Returns a hash with the filter selection

Example of use:

<lib-oecd-ai-widget \*ngIf="widgetConfig" [config]="widgetConfig" [selectedFiltersHash]="selectedFiltersHash"
(selectedFiltersChange)="handleSelectedFiltersChange($event)" />

handleSelectedFiltersChange(hash: string | null) {
  console.log('Filters hash', hash);
}

Dataviz config documentation

Detailed documentation is available in the docs directory:

• BarChart
• StackBarChart
• LineChart
• BumpChart
• PieChart
• BubbleChart
• BubbleListChart
• SankeyDiagram
• RadarChart
• HeatMapChart