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.

Properties

TL/DR

Here is minimal kyso.yaml file, which includes the most important variables:

• organization

• channel (can also be denoted team)

organization: acme
channel: general
title: "Project Title"
main: report.ipynb

Below is an example of a comprehensive YAML file:

organization: acme
author: [e-mail]
channel: general
title: "Project Title"
description: "Project Description."
main: report.ipynb
preview: "images/preview.png"
tags: [tag1, tag2, tag3]

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 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: ["[e-mail]", "[e-mail]"]

Meta Reports

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.

Users need to manually add authors to the YAML file when updating reports from a new profile. Kyso does NOT automatically detect a new author on later versions if pushed from another account.

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:

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: [e-mail]
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.

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.

File Header Metadata

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.

Pushing Single Files

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
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]
---