Skip to main content

Model Findings

model_findings.json is the configuration file that defines the structure and content of insights generated by your machine learning model. It specifies visualization types, sections, subsections, and items to be displayed in the Chanterelle platform.

Table of Contents​

Content Overview​

The model_findings.json file describes:

  • Sections that group related insights
  • Insight items with detailed specifications of Text and Visualizations supported by the platform
  • Dropdowns and Subsections for filtering insights and dropdown functionality

Basic Structure​

A model_findings.json file follows this JSON schema:

{
  "model_id": "example-model",
  "version": "1.0.0",
  "content": [
    {
      "type": "section",
      "id": "section1",
      "title": "Example Section",
      "items": [
        {
          "type": "bar_chart",
          "id": "chart1",
          "title": "Example Bar Chart",
          "data": {
            "bars": [
              { "label": "A", "value": 10 },
              { "label": "B", "value": 20 }
            ],
            "axis": {
              "x": { "label": "Categories" },
              "y": { "label": "Values" }
            }
          }
        }
      ]
    }
  ]
}

Insight Items and Visualization Types​

Insight items represent text, individual visualizations or data points. Supported types include:

  • bar_chart — Bar charts
  • line_chart — Line charts
  • scatter_plot — Scatter plots
  • table — Data tables
  • text — Rich text with paragraphs, bullets, and styling
  • image — Images from file paths or URLs
  • markdown — Full Markdown rendering (GFM, code blocks, tables)
  • plotly — Interactive Plotly.js charts
  • html — Embedded HTML content (inline or from file)
  • error — Styled error messages

Common Item Properties​

All insight items share these base properties:

FieldTypeRequiredDescription
typestring✅The visualization type
idstring❌Unique identifier
titlestring❌Display title
descriptionstring❌Help text or description
commentstring❌Additional commentary
collapsibleboolean❌Whether the item can be collapsed
collapsedboolean❌Whether the item starts collapsed
full_widthboolean❌Override items_per_row and take full width

Each type has specific fields and configurations. Below are examples for each type, with optional fields explicitly marked:

Bar Chart​

{
  "type": "bar_chart",
  "id": "chart1",
  "title": "Example Bar Chart",
  "description": "A bar chart example", // Optional
  "comment": "This chart shows category values", // Optional
  "data": {
    "bars": [
      { "label": "A", "value": 10 },
      { "label": "B", "value": 20 }
    ],
    "axis": {
      "x": { "label": "Categories" },
      "y": { "label": "Values" }
    }
  }
}

Line Chart​

{
  "type": "line_chart",
  "id": "line1",
  "title": "Example Line Chart",
  "description": "A line chart example", // Optional
  "comment": "This chart shows trends over time", // Optional
  "data": {
    "lines": [
      {
        "id": "lineA",
        "points": [
          { "x": 1, "y": 10 },
          { "x": 2, "y": 20 }
        ],
        "style": {
          "color": "blue", // Optional
          "width": 2 // Optional
        }
      }
    ],
    "axis": {
      "x": { "label": "Time" },
      "y": { "label": "Values" }
    }
  }
}

Table​

{
  "type": "table",
  "id": "table1",
  "title": "Example Table",
  "description": "A table example", // Optional
  "comment": "This table shows data in rows and columns", // Optional
  "data": {
    "columns": [
      { "header": "Column 1", "field": "col1" },
      { "header": "Column 2", "field": "col2" }
    ],
    "rows": [
      { "col1": "Row 1", "col2": 10 },
      { "col1": "Row 2", "col2": 20 }
    ]
  }
}

Bullet List​

{
  "type": "bullet_list",
  "id": "bullet1",
  "title": "Example Bullet List",
  "description": "A bullet list example", // Optional
  "comment": "This list shows key points", // Optional
  "data": {
    "bullets": [
      { "text": "Bullet 1", "style": "bold" }, // Optional
      { "text": "Bullet 2", "style": "italic" } // Optional
    ]
  }
}

Image​

Images can be loaded from relative file paths (relative to the project directory), absolute paths, file:// URIs, or HTTP URLs.

{
  "type": "image",
  "id": "image1",
  "title": "Example Image",
  "description": "An image example",
  "caption": "This is an example image",
  "file_path": "graphs/example.png"
}

Text​

The text type supports rich text content with paragraphs, bullet lists (including nested bullets), and styling options.

Simple text:

{
  "type": "text",
  "id": "text1",
  "title": "Example Text",
  "content": [
    { "type": "paragraph", "text": "This is a paragraph of text." },
    { "type": "paragraph", "text": "This is another paragraph." }
  ]
}

With bullet lists and styling:

{
  "type": "text",
  "id": "text2",
  "title": "Styled Text",
  "content": [
    { "type": "paragraph", "text": "Key findings:", "style": { "bold": true } },
    {
      "type": "bullet_list",
      "items": [
        { "text": "First point" },
        { "text": "Second point", "style": { "color": "green" } },
        {
          "text": "Third point with sub-items",
          "items": [
            { "text": "Sub-item A" },
            { "text": "Sub-item B" }
          ]
        }
      ]
    }
  ]
}

Error​

{
  "type": "error",
  "id": "error1",
  "title": "Example Error",
  "error": "File not found"
}

Scatter Plot​

{
  "type": "scatter_plot",
  "id": "scatter1",
  "title": "Feature Scatter Plot",
  "data": {
    "points": [
      { "x": 1.2, "y": 3.4 },
      { "x": 2.5, "y": 1.8 },
      { "x": 3.1, "y": 4.2 }
    ],
    "axis": {
      "x": { "label": "Feature A" },
      "y": { "label": "Feature B" }
    }
  }
}

Plotly​

Render interactive Plotly.js charts. Data can be provided inline, as a stringified JSON blob, or loaded from a file.

Inline data:

{
  "type": "plotly",
  "id": "plotly1",
  "title": "Interactive Scatter",
  "data": [
    {
      "x": [1, 2, 3],
      "y": [2, 6, 3],
      "type": "scatter",
      "mode": "lines+markers",
      "marker": { "color": "red" }
    }
  ],
  "layout": { "title": "My Plotly Chart" }
}

From file (Plotly JSON export):

{
  "type": "plotly",
  "id": "plotly2",
  "title": "Chart from File",
  "file_path": "graphs/my_chart.json"
}

Using figure_json (stringified Plotly figure):

{
  "type": "plotly",
  "id": "plotly3",
  "title": "Plotly Figure",
  "figure_json": "{\"data\": [...], \"layout\": {...}}"
}

Markdown​

Render Markdown content with GFM (GitHub Flavored Markdown) support including tables, code blocks with syntax highlighting, and more. Content can be inline or loaded from a .md file.

Inline markdown:

{
  "type": "markdown",
  "id": "md1",
  "title": "Inline Markdown",
  "content": "# Heading\n\n- Bullet 1\n- Bullet 2\n\n| Col A | Col B |\n|:------|------:|\n| hi    |     1 |\n\n```python\ndef hello():\n    print('world')\n```"
}

Markdown from file:

{
  "type": "markdown",
  "id": "md2",
  "title": "From File",
  "file_path": "docs/analysis.md"
}

HTML​

Embed HTML content either inline or from a file. HTML is rendered in a sandboxed iframe.

Inline HTML:

{
  "type": "html",
  "id": "html1",
  "title": "Inline HTML",
  "content": "<h1>Hello</h1><p>Custom HTML content</p>"
}

HTML from file (e.g., Plotly HTML export):

{
  "type": "html",
  "id": "html2",
  "title": "Interactive Visualization",
  "file_path": "graphs/visualization.html"
}

Sections​

Sections group related insights. They support nesting, grid layout, collapsible behavior, dropdown filtering, and colored headers.

Section Properties​

FieldTypeRequiredDescription
type"section"✅Must be "section"
idstring❌Unique identifier
titlestring✅Display name (appears in Table of Contents)
descriptionstring❌Help text
itemsarray✅*Array of insight items or nested sections
items_per_rownumber❌Number of items to display per row (default: 1)
colorstring❌Color for section header
collapsibleboolean❌Whether the section can be collapsed
collapsedboolean❌Whether the section starts collapsed
dropdownobject❌Dropdown configuration (see Dropdown Configuration)
subsectionsobject❌Subsection content keyed by dropdown option ID

*Items are required unless dropdown + subsections are used instead.

Example Section​

{
  "type": "section",
  "id": "section1",
  "title": "Example Section",
  "description": "This is an example section.",
  "items": [
    {
      "type": "text",
      "id": "text1",
      "title": "Example Text",
      "text": "This is a sample text insight."
    }
  ]
}

Dropdowns allow users to select specific options to filter or customize the displayed insights. Each dropdown includes:

  • enabled: Boolean indicating whether the dropdown is active.
  • default_selection: The default option selected when the dropdown is displayed.
  • options: Array of dropdown options, each with:
    • id: Unique identifier for the option.
    • label: Display name for the option.
    • description: Optional help text explaining the option.
  • subsections: Nested subsections for each dropdown option, allowing further customization.

Subsections Properties​

Subsections provide additional structure within dropdown options. Each subsection includes:

  • items: Array of insight items to be displayed within the subsection. Insight items can include visualizations like charts, tables, images, or text.
  • items_per_row: Optional property specifying the number of items to display per row. Defaults to 1 if not provided.

Example of Dropdown Configuration​

{
  "dropdown": {
    "enabled": true,
    "default_selection": "overview",
    "options": [
      {
        "id": "overview",
        "label": "Overview",
        "description": "General overview of the data"
      },
      {
        "id": "details",
        "label": "Details",
        "description": "Detailed breakdown of the data"
      },
      {
        "id": "summary",
        "label": "Summary",
        "description": "Summary of key insights"
      }
    ]
  },
  "subsections": {
    "overview": {
      "items_per_row": 2, // Optional
      "items": [
        {
          "type": "text",
          "id": "overview_text",
          "title": "Overview Text",
          "text": "This section provides a general overview of the data."
        }
      ]
    },
    "details": {
      "items_per_row": 1, // Optional
      "items": [
        {
          "type": "table",
          "id": "details_table",
          "title": "Detailed Data Table",
          "data": {
            "columns": [
              { "header": "Column 1", "field": "col1" },
              { "header": "Column 2", "field": "col2" }
            ],
            "rows": [
              { "col1": "Row 1", "col2": 10 },
              { "col1": "Row 2", "col2": 20 }
            ]
          }
        }
      ]
    },
    "summary": {
      "items_per_row": 1, // Optional
      "items": [
        {
          "type": "image", // just an example, can be any type
          "id": "summary_image",
          "title": "Summary Image",
          "url_filename": "images/summary.png"
        }
      ]
    }
  }
}

Complete Example​

{
  "model_id": "example-model",
  "version": "1.0.0",
  "content": [
    {
      "type": "section",
      "id": "section1",
      "title": "Example Section",
      "items": [
        {
          "type": "bar_chart",
          "id": "chart1",
          "title": "Example Bar Chart",
          "data": {
            "bars": [
              { "label": "A", "value": 10 },
              { "label": "B", "value": 20 }
            ],
            "axis": {
              "x": { "label": "Categories" },
              "y": { "label": "Values" }
            }
          }
        }
      ]
    }
  ]
}

Decomposing and Referencing Other JSON Files​

You can decompose your findings file into smaller, more manageable files. This is useful if you have JSON generated programmatically or if you want to keep your project organized.

Use the $href keyword to reference an external JSON file. The referenced file's content will be inlined at that position. References are resolved recursively.

Referencing a section:

{
  "model_id": "example-model",
  "version": "1.0.0",
  "content": [
    {
      "$href": "path/to/section.json"
    }
  ]
}

Referencing an insight item:

{
  "model_id": "example-model",
  "version": "1.0.0",
  "content": [
    {
      "type": "section",
      "id": "section1",
      "title": "Example Section",
      "items": [
        {
          "$href": "graphs/chart_data.json"
        }
      ]
    }
  ]
}

File paths are resolved relative to the project directory.