bands-visualiser/README.md

A plotly.js renderer for Bands, DOS, combined Bands/Dos and fatBands.

# Band Structure Visualiser

A plotly.js renderer for Bands, DOS, combined Bands/Dos and fatBands.

The `BandsVisualiser` requires atleast one of two arrays:

- `bandDataArray`
- `dosDataArray`

Related repositories:

- https://github.com/osscar-org/widget-bandsplot (A similar Jupyter widget)
- https://github.com/materialscloud-org/bands-widget (outdated version used in legacy)
- https://github.com/materialscloud-org/mc-react-bands (the current implementation on MCXD)

# Installation
The bands-visualiser entire source is published as an [npm package](https://www.npmjs.com/package/bands-visualiser).
```
npm install bands-visualiser
```

# Basic Usage

The bandsVisualiser renders through plotly.js and can be invoked into a html element via:

```JSX
import { BandsVisualiser } from "bands-visualiser";

BandsVisualiser(container, {
  bandsDataArray: [test_bands],
});
```

It's expected that each entry into this array will be an object with a "typeData" key and a "traceFormat" key. If no traceFormat is supplied, some basic formatting is applied.

minimum example objects:

```JSX
bandObject = {
  bandsData: {
    path: [["A", "B"], ["B","C"], ... ],
    paths: [{values: [[], [], ...], x:[0, 1, ... ]}]
  }
  traceFormat: {}
}

dosObject = {
  dosData: {x: [], y: []
  }
  traceFormat: {
    name: "Total DOS",
    fillcolor: "rgba(180, 20, 20, 0.6)", //
    ...
  }
}
```

aiida discerns spin polarised calculations through indexing. If you would like to render up and down spins with different format some work is needed.

The `splitBands` utility can split a BandsData (passing along the same path/paths).

```JSX
import { splitBandsData,} from "./lib/utils/dataUtils.js";

const splitBands = splitBandsData(bandsData, nParts=2)
[bandsDown, bandsUp] = splitBands
```

Its then easy to pass traceFormatting information to this these;

```JSX
bandsDataArray = [
  {
    bandsData: bandsDown,
    traceFormat: {
      label: "Down Channel",
      line: {
        color: "blue", dash: "dash"}}},
 {
    bandsData: bandsUp,
    traceFormat: {
      label: "Up Channel",
      line: {
        color: "red", dash: "solid"}}}
        ]
```

The traceFormat key follows the format of plotly traces; for a full list of possible props see: https://plotly.com/python/reference/scatter/.

# Advanced Usage

Projections are embedded inside the bandsDataObject;

```JSX
bDO = {
  bandsData: { x: [], y [[]]: path: ..., paths: ...}
  traceFormat: {} // formatting for the
  projections: [
  {
    projData: {
      weights: [[]],
    },
    traceFormat: {name: "projection 1"}
  },
  {
    projData: {
      weights: [[]],
    },
    traceFormat: {name: "projection 2", showlegend: false}
  },
  ]
}
```

Calling the BandsVisualiser with this bDO will render projections by default:

```JSX
BandsVisualiser(container, {
  bandsDataArray: [bDO],
  fermiLevels: [21],
});
```