5. Model Resources¶

This tutorial is based on example code which can be found in the finTRAC Examples Repository.

Models sometimes need small static files that belong with the model code - an image for a report, a template, a lookup table or some text. These can be included in the model’s Python package as model resources, and loaded at runtime. Because resources are part of the model code, they are versioned with the model and the same resources are always used for a given model version.

Note

Model resources are not the same as the resources declared in define_resources(), which are connections to external systems.

Adding resources to a package¶

Resource files live inside a Python package, which is a folder with an __init__.py file. In the example project the resources are kept in their own sub-package, tutorial.resources:

examples-project
├── config
│   └── ...
├── src
│   └── tutorial
│       ├── __init__.py
│       ├── load_resources.py
│       └── resources
│           ├── __init__.py
│           └── tracdap_banner_logo.png
└── ...

When a model runs on the platform, TRAC checks out the model code from the repository at the model’s version. Resource files must be committed to the repository along with the code - files that exist only in your local project will work when you run the model locally, but will be missing on the platform.

Loading a resource¶

To load a resource, import the package it lives in and pass the package and file name to one of the resource functions in the runtime API:

load_resource() returns the content as bytes
load_text_resource() returns the content as a string
load_resource_stream() and load_text_resource_stream() return a readable stream, which must be used in a with block

This example builds the same sales chart as the Using Files tutorial, with a logo loaded from the resources package shown above the chart. First the resources package is imported:

src/tutorial/load_resources.py¶

import tutorial.schemas as schemas
import tutorial.resources as resources

Then the logo is read as a stream and passed straight to Matplotlib:

    def run_model(self, ctx: trac.TracContext):

        matplotlib.use("agg")

        quarterly_sales = ctx.get_pandas_table("quarterly_sales")

        regions = quarterly_sales["region"]
        values = quarterly_sales["gross_profit"]

        fig, (ax_img, ax_plot) = plt.subplots(
            2, 1, figsize=(8, 10),
            gridspec_kw={'height_ratios': [1, 3]})

        with trac.load_resource_stream(resources, "tracdap_banner_logo.png") as logo_stream:

            logo = img.imread(logo_stream)

            # Top panel for image
            ax_img.imshow(logo)
            ax_img.axis('off')

        ax_plot.bar(regions, values)
        ax_plot.set_title("Profit by region report")
        ax_plot.set_xlabel("Region")
        ax_plot.set_ylabel("Gross profit")

        plt.tight_layout()

        with ctx.put_file_stream("sales_report") as sales_report:
            plt.savefig(sales_report, format='svg')

        plt.close(fig)

Size limits¶

Resources are meant for small files. Large files slow down every checkout of the model repository, so the runtime enforces a size limit when a resource is loaded. The default limit is 256 KB, and on the platform it can be changed per tenant with the runtime.limit.resourceSize property (in KB). The limit is checked when the resource is loaded, which is normally while the model runs, so a resource over the limit causes the job to fail.

Larger files should be passed to the model as file inputs instead, see Using Files.