Configuring Report Metadata
How to ensure your colleagues can easily discover your company's data science work.
All reports on Kyso contain variables like authors, dates, tags, descriptions, and titles as metadata. This metadata can be added in various ways:
  1. 1.
    Directly on reports in the Kyso UI (titles, descriptions and tags only).
  2. 2.
    Include it in a kyso.yaml/kyso.json file in the same directory as the report.
A third way will be possible in one of our upcoming deployments - in the first cell (JSON) of a Jupyter notebook, its "front matter."
And end-users can search across your company's knowledge base by this report metadata.

Properties

Tldr

Here is minimal kyso.yaml file, which includes the most important variables:
  • organization
  • team
  • type
1
organization: acme
2
team: general
3
type: jupyter
4
title: "Project Title"
5
main: report.ipynb
Copied!
Below is an example of a comprehensive YAML file:
1
organization: acme
3
team: general
4
type: jupyter
5
title: "Project Title"
6
description: "Project Description."
7
main: report.ipynb
8
preview: "images/preview.png"
9
tags: [tag1, tag2, tag3]
Copied!

Property Lexicon:

  • main: required. File which will be rendered automatically when the project is opened on Kyso.
  • title: required. Name of the report.
  • description: required. Description of the report.
  • organization: required. Organization which owns the report.
  • team: required. Team within the organization to which the report belongs.
  • type: required. Type of report. Options:
    • jupyter: Jupyter notebook
    • website: Simple HTML file or more complex website
    • meta: Mono-folder in which each sub-directory is published as separate project report.
  • reports: required only if type: meta
    • 1
      reports:
      2
      - folder1
      3
      - folder2
      Copied!
    • In this case, each sub-folder should have its own yaml/json file for the individual reports.
  • preview: optional. Preview image of the report. One will be generated automatically in its absence.
  • author: optional
Note that you are also able configure the title, description, and preview image on the post on Kyso after import, but it is recommended to include this in the YAML header for a more seamless workflow.
Recommendation: Always add a title, description and preview image to your posts. You will receive a lot more readers.
If you want to validate your YAML before pushing to Github - checkout this YAML Validator.

Example Workflow

I am working on my local machine in a directory Users/Kyle/Data-Analysis. This folder contains multiple sub folders, which all denote separate projects and that I want to publish as their own Kyso reports.
Example:
1
Data-Analysis
2
└── Marketing
3
└── data/
4
└── report.ipynb
5
└── images/
6
└── Product
7
└── data/
8
report.ipynb
9
└── images/
10
etc..
Copied!
In my root directory (Users/Kyle/Data-Analysis), I have the following kyso.yaml file:
1
type: meta
2
reports:
3
- marketing
4
- product
Copied!
This tells Kyso to import 'Marketing' and 'Product' as their own individual Kyso reports and not 'Data-Analysis' as the one Kyso report. By default Kyso does not import in the root directory (Data Analysis) as its own report, but rather acts as a navigation system for Kyso in finding the project reports.
Then in each sub-directory I have another kyso.yaml which sets the metadata for that specific report. For example, in 'Marketing' I could have the following"
1
organization: acme
2
team: marketing
3
type: jupyter
4
description: "This report explores how we can pull in website data from Google Analytics and find insights on SEO."
6
main: report.ipynb
7
preview: images/preview.png
8
title: "Predicting the results of our latest marketing campaign"
9
tags: [seo, content-campaigns, google-analytics]
Copied!
And something similar in 'Product'. Any time changes are made to any individual report, Kyso will version the projects as you publish again and again...
Here is how this looks in action on a Git repo: https://github.com/KyleOS/Data-Analysis, feel free to browse through!!

The Power of Tagging

As seen above, authors can 'tag' their reports within the metadata. What makes this specific variable so useful is that when users are searching for reports on Kyso, using specific tags when combined with searching by team and full-text (see next two documents) will really narrow a search from '000s down to a few relevant reports.

Coming Soon: YAML Header in the Notebook

In the absence of any kyso.yaml file in the directory, Kyso will look for a YAML header in a notebook's metadata. This may be a better option for those of you posting ongoing projects, to which commits are made on a daily or weekly basis. Rather than manually configuring a YAML file, you can simply update the metadata while working in the notebook.
The example below is our YAML configs contained within 3 dashed (-) lines top and bottom, in the first Markdown cell of the notebook:
1
---
2
organization: acme
3
team: marketing
4
type: jupyter
5
title: "My awesome post"
6
description: "This is a description of what I did in my awesome post"
7
main: "my-article.ipynb"
8
tags: [apples, oranges]
9
---
Copied!
This feature will be pushed in the next deployment.