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.Directly on reports in the Kyso UI (titles, descriptions and tags only).
- 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.
Here is minimal kyso.yaml file, which includes the most important variables:
organizationteam
organization: acme
team/channel: general
title: "Project Title"
main: report.ipynb
Below is an example of a comprehensive YAML file:
organization: acme
author: [email protected]
team/channel: general
title: "Project Title"
description: "Project Description."
main: report.ipynb
preview: "images/preview.png"
tags: [tag1, tag2, tag3]
- 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 if 'meta'. Type of report.
- meta: Mono-folder in which each sub-directory is published as separate project report.
- reports: required only if
type: meta- reports:- folder1- folder2
- 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. If no author is specified, the logged in user pushing from the command line will be set as the sole author.
You can specify multiple authors as a list!
authors: ["[email protected]", "[email protected]"]
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.
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:
Data-Analysis
└── Marketing
└── data/
└── report.ipynb
└── images/
└── Product
└── data/
report.ipynb
└── images/
etc..
In my root directory (Users/Kyle/Data-Analysis), I have the following kyso.yaml file:
type: meta
reports:
- marketing
- product
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"
organization: acme
team: marketing
description: "This report explores how we can pull in website data from Google Analytics and find insights on SEO."
author: [email protected]
main: report.ipynb
preview: images/preview.png
title: "Predicting the results of our latest marketing campaign"
tags: [seo, content-campaigns, google-analytics]
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!!
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.
In the absence of any kyso.yaml file in the directory, Kyso will look for a YAML header in a notebook's or markdown file'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.
Note that this currently only works for Jupyter- and Markdown-based reports.
The example below is our YAML configs contained within 3 dashed (-) lines top and bottom, in the first Markdown cell of the notebook or markdown file:
---
organization: acme
team/channel: marketing
title: "My awesome post"
description: "This is a description of what I did in my awesome post"
main: "my-article.ipynb"
tags: [apples, oranges]
---
Here is a link to an example report that contains the report metadata in the frontmatter, rather than in a separate YAML file: https://kyso.io/kyso-demo/general/publishing-a-single-notebook-file-using-frontmatter-metadata/