Administering AI Factsheets

After you install AI Factsheets, you can administer your model inventory provided you have admin permissions for Watson™ Knowledge Catalog or Watson Studio.

About this task

Note: You only need editor permission to access AI Factsheets, for example to create and update a model use case. Only some tasks require admin permission.

You might need to have Create Catalog permissions for some tasks to set up or customize AI Factsheets for your specific business needs. As an admin, you can open the Manage tab in your catalog and do the following tasks:

Creating a Platform Asset catalog

You might be prompted to create a Platform Asset catalog for managing your model inventory. If you do not have a Platform Asset catalog, you are sent a notification to create one after you click the Manage tab. Then you must do the following steps:

  1. Click the link in the notification.
  2. Complete the details for the catalog.
  3. Click Create to create the catalog.
  4. Close the tab to return to the model inventory.

Creating a custom report template

AI Factsheets includes default report templates for presenting data from model use cases and factsheets. You can customize the report templates to suit the needs of your organization.

Note: You must have a Platform Asset catalog before you begin.

If the default report templates provided with AI Factsheets do not meet your needs, you can download a default report template, customize it for your needs, and upload the new template. Currently, you must use the AI Factsheets API to download the template, but you can upload it from the model inventory UI.

Download a report template
  1. Use the GET endpoint for /v1/aigov/report_templates in the IBM Watson Data API to list the available templates. Note the id for the template you want to download.
  2. Use the GET endpoint /v1/aigov/report_templates/{template_id}/content with the template id to download the template file.
  3. Open the <report-name>.ftl file in an editor.
  4. Edit the template, using instructions from Apache FreeMarker or the API commands.
Add a custom template to the model inventory
  1. Open the model inventory and click the Manage tab.
  2. Click Add template.
  3. Specify a name for the template and an optional description.
  4. Choose the type of template: model or model use case. Note that the reports are available for external models as well as Watson Machine Learning models.
  5. Upload the updated FTL file. Restriction: The ftl file that you upload must not import any other files. Support is not yet available for import statements in the ftl file.

The custom template displays in the Report templates section and will be available for creating reports. Click Edit or Delete from the action menu for a custom template to update the template details or to remove the template.

Adding attachments for factsheets

As an admin, you can define attachment groups and manage attachment definitions for the model inventory. Use an attachment group to organize a set of related attachment facts and render them together. Attachments can provide supporting information and additional detail for a model use case. Data scientists might want to attach visualizations from their model. Model requestors might want to attach a file of requirements to describe a business need. There are two ways to manage and facilitate attachments:
  • Define attachment groups and manage attachment definitions from the Manage page of the model inventory.
  • Attach files and manage attachments using the Python client. For details, see Adding and managing attachments for factsheets.

To create an attachment group:

  1. Open the model inventory, click the Manage tab and navigate to the Attachments section.
  2. Create a new attachment group, assigning a name and optional description.

Reviewing and updating attachments for factsheets

You can also review or update existing attachment groups.

To add attachment facts to a group:
  1. From an attachment group, add attachment fact definitions that will specify how a user can add an attachment to a factsheet. Attachment definitions display as available slots in the attachment section for a factsheet.
  2. Use the up and down arrow keys to reorder attachments in the list.
    Defining an attachment fact
Note: If you add attachments from the Python client, provide the fact definition ID that is created in the Manage tab to add the attachment to the slot defined in the attachment group. Then that attachment shows in that slot in the factsheet. If the fact_id that is provided is not created in the Manage tab, then the attachment displays in the Other attachments section rather than as part of the group.

When you save your attachment fact definitions, an attachment slot and description display on the factsheet for attaching a file in the definition from the UI. A pin icon indicates an available attachment slot. Users can upload attachments.


Uploading an attachment fact

The attachment displays as part of the use case.


Viewing an attachment fact

If you delete a fact definition, the images that were showing in the group section would show up in Other attachments instead.

What to do next

To get started with AI Factsheets, see AI Factsheets.