How to include data files with a notebook template as assets

Your report notebook might require additional files to run. These might be data files, like CSV, YAML, HDF5, or FITS.

One approach is to maintain these data files on a web server and use a Python library like Requests to download that data on demand.

In cases where the data files are highly coupled and specific to the report, though, it’s natural to bundle these files with the templated report itself. This approach ensures that data files are maintained and versioned in step with the report template since both the data and code are co-located in the same Git repository. nbreport enables you to do this with a feature called assets.

This pages guides you through using the assets feature.

See also

Another application of assets is for including Python modules alongside a notebook. See How to use Python modules in a report notebook template for details.

Step 1. Commit the data files into the Git repository of the notebook template

Commit the data files into the Git repository of the notebook template. These files must be in the same directory as the notebook (ipynb file) or a subdirectory relative to the notebook file.

For example, the template repository contents might look like this:

.
├── conf.yaml
├── images
│   ├── image1.files
│   └── image2.files
├── nbreport.yaml
└── TEST-000.ipynb

The assets are conf.yaml file and the contents of the images directory.

Step 2. Register the files as “assets” in the nbreport.yaml file

Open the nbreport.yaml file in the notebook template repository. Add a key called assets to that YAML file, and then add list items to that key that match the paths of data files. File paths, directory names, and globs are supported — see the assets reference documentation for details.

To match the assets in the previous example, the assets configuration might be:

assets:
  - 'conf.yaml'
  - 'images'

Alternatively, to ensure that only FITS files in the images directory (and its subdirectories) are matched, you might instead use a glob:

assets:
  - 'conf.yaml'
  - 'images/**/*.fits'

When a new report instance is created with the nbreport init or nbreport issue commands, the files marked as assets are copied from the notebook template repository into the instance’s working directory. Directory structure is preserved. These files are not processed by Jinja templates.

For more information about the assets field in the nbreport.yaml file, see the nbreport.yaml reference.