Validate installation

The Cantabular software package contains a simple dataset that can be used to validate the installation.

On Linux the Cantabular executables can be run from a shell. On Windows the Cantabular executables can be run from a Command Prompt.

Create dataset

cantabular-make-dataset can be used to compile the example codebook, microdata, files associated with perturbation and other configuration data into a dataset. The following command will create a dataset file called ./example/example.dat:

Linux

cd cantabular-VERSION
./bin/cantabular-make-dataset ./example/example.json

Windows

cd cantabular-VERSION
bin\cantabular-make-dataset.exe example\example.json

Inspect dataset

cantabular-inspect can be used to inspect the dataset file. This executable displays information about the dataset.

Linux

./bin/cantabular-inspect ./example/example.dat

Windows

bin\cantabular-inspect.exe example\example.dat

Serve dataset

cantabular-server can be used to allow non-flow datasets to be queried via a REST API. cantabular-ui provides a UI that communicates with the server via the API. When cantabular-server is run with a -u option then cantabular-ui is automatically run in the background.

When cantabular-server is run with a -a option then cantabular-api-ext is also automatically run in the background.

The following command can therefore be used to make the dataset available for queries via a web browser and to enable extended API outputs:

Linux

./bin/cantabular-server -u -a ./example/example.dat

Windows

bin\cantabular-server.exe -u -a example\example.dat

Serve metadata

cantabular-metadata allows metadata to be associated with a dataset and queried via a GraphQL API. This metadata will automatically appear in the UI when it is available. To start the metadata service with illustrative metadata for this example dataset use the following command:

Linux

./bin/cantabular-metadata ./example/metadata/metadata.graphql ./example/metadata/serviceMetadata.json ./example/metadata/datasetMetadata.json

Windows

bin\cantabular-metadata.exe example\metadata\metadata.graphql example\metadata\serviceMetadata.json example\metadata\datasetMetadata.json

Access UI

By default the UI is available on port 8080 of the localhost interface. It can be accessed via a web browser using the following URL:

http://localhost:8080

Access GraphiQL UI

Both cantabular-api-ext and cantabular-metadata make an API explorer interface called GraphiQL available to allow exploration, querying and access to documentation. They can be accessed using the following URLs in a modern web browser running JavaScript:

Query flow dataset

A Cantabular flow dataset can be queried using cantabular-flow-query on the command-line.

The following command can therefore be used to query flow data.

Linux

./bin/cantabular-flow-query -outfile /tmp/flow.csv ./example/example-flow.dat
CITY CITY_WORK SEX

Windows

bin\cantabular-flow-query.exe -outfile %TEMP%\flow.csv example\example-flow.dat
CITY CITY_WORK SEX