Docs portal

data.world tools

Intro to the Simple Data Documentation Editor

The Simple Data Documentation Editor--Simple Editor for short--is data.world's built-in WYSIWYG editor for project and dataset summaries, posts, and insights. The Simple Editor generates powerful data-enabled markdown, and allows you to create data-rich documentation for your datasets and projects faster than ever before. Now you can:

  • Use drag and drop or autofill to embed or link resources in various formats from many different sources

  • Benefit from easy-to-use styling or standard Markdown

  • Insert a variety of content blocks

  • Use Markdown shortcuts while in the Simple Editor

  • Switch back and forth between the Simple Editor and Markdown

Accessing the command menu

When you place your cursor on a new line in a Simple Editor field, a list of shortcuts for basic embed and format options appears:

Screen_Shot_2019-04-16_at_11.40.17_AM.png

If your cursor is not at the beginning of the line your content will be linked instead of embedded. More information about embedding vs. linking can be found in the article Embedding resources with the Simple Editor.

The forward slash (/) brings up the command menu which is covered in detail in the article Using the Simple Editor command menu.

Embedding links to other users and organizations

The ampersand ( @ ) brings up a list of users and organizations with whom you've recently interacted in order to @mention them. If the person or org you want to tag is not in the list, you can begin typing the name for a list of options:

Screen_Shot_2019-04-15_at_4.56.30_PM.png

The @mention takes readers to the profile page of the user or organization who was tagged.

Formatting options and shortcuts

The last item on the initial prompt of commands for the Simple Editor is highlight text. It serves as a reminder that when you are in the Simple Editor you can highlight a section of text to get a menu of the formatting options built in to the editor:

Simple_editor_highlight_menu.png

The options on the Highlight menu are Bold, Italics, code, header types 1-3, and links. In addition to formatting with the highlight text menu you can also use the basic keyboard shortcuts like ⌘+b for bold, ⌘+i for italics (Ctrl+ for Windows). The standard Markdown shortcuts (# Header1, ## Header2, **bold**, _italics_, etc.) can also be used in the Simple Editor window. For more information on Markdown styling see our Markdown syntax reference.

Switching between the Simple Editor and Markdown

Though the simplicity of the WYSIWYG interface of the Simple Editor will appeal to most users, those who prefer to use Markdown can switch to Markdown by selecting the Switch to Markdown link at the top of the edit window:

Screen_Shot_2019-05-06_at_5.40.12_PM.png

It is also possible to do some editing in the Simple Editor and continue editing in Markdown or vice versa. Both versions are maintained simultaneously:

Screen_Shot_2019-05-06_at_5.42.58_PM.png

More information about how the Simple Editor works can be found in the article Using the Simple Editor command menu.

Using the Simple Editor command menu

In the article Intro to the Simple Data Documentation Editor we introduced data.world's Simple Editor that allows you to quickly and easily add different kinds of files from various sources into project and dataset summaries, posts, and insights.

The command menu (accessed by typing forward slash ( / ) at the beginning of a line in the editor window) contains a list of items you can embed including recent files, queries, insights, and various content block options. If your cursor is not at the beginning of a line when you type the forward slash, your content will be linked, not embedded. More information about embedding vs. linking can be found in the article Embedding resources with the Simple Editor.

Recently updated resources

The first several items on the command menu are files, queries, insights, and other resources specific to your current dataset or project that you have recently modified:

Screen_Shot_2019-05-06_at_5.58.53_PM.png

If the item you wish to embed is not in the recent items list you can begin typing its name and autocomplete will take over:

Screen_Shot_2019-05-06_at_6.26.00_PM.png
Checklists

Creating a checklist is as easy as selecting the item on the menu and then entering all your list items separated by a return. Checklists format as items in a list and the boxes can be checked during the edit process. Once the summary or insight has been saved, the state of the checkboxes is set and can be changed by opening and editing the summary or insight again:

Screen_Shot_2019-03-29_at_4.32.37_PM.png
Code blocks

Selecting < > Code from the dropdown inserts a formatted code block where you can type or paste a code snippet:

Screen_Shot_2019-03-29_at_4.38.36_PM.png
Embed Content

The </> Embed Content menu item inserts the formatting required for a URL so all you need to do is paste the URL into it and it will be embedded after it's saved:

Screen_Shot_2019-04-16_at_11.37.15_AM.png

When adding embedded content, the embed link must be the only text on its line. You cannot, for instance, embedded content in the middle of a sentence.

More information on embedding and linking content can be found in the article Embedding resources with the Simple Editor

Embedding resources with the Simple Editor

With data.world's Simple Editor you can quickly and easily add different kinds of files from various sources into project and dataset summaries, posts, and insights. The articles Intro to the Simple Data Documentation Editor and Using the Simple Editor command menu describe the editor and the features of the command menu.

Using drag and drop to embed resources

In addition to using the command menu, you can also embed resources into a Simple Editor window with drag and drop. Drag and drop works with resources located in the current project or dataset, on your local drive, a networked or cloud drive, and a web page. To embed a resource by dragging and dropping it the resource needs to be dragged to the beginning of a new line in the Simple Editor window. Resources placed in-line render as links rather

Various sources for embedded resources

The command menu is useful for embedding resources from the current dataset or project into the editor window, but resources in connected datasets or located outside of data.world must be embedded with drag and drop. Sources for resources that can be embedded include:

  • The current project or dataset

  • Desktop or cloud storage

  • From a URL

The current project or dataset

While recently modified files in the current project will show up in the command menu, files in linked datasets do not. Drag and drop works for both the current project or dataset files and also for the connected dataset files. To include any resource from the left sidebar of the workspace select it and drag it to the beginning of a new line in the editor window:

Screen_Shot_2019-05-07_at_11.38.41_AM.png

The files in your project or dataset that can be viewed in the workspace typically render in full or as a preview in the Simple Editor window. PDF's are the current exception to this rule and can only be embedded as a link. Tabular files are displayed as a preview with a link to the full file. Text files (.txt, not rich-text files--.rtf) and most image files are also previewed in the editor. See the article Supported file types for detailed information on the rendering of specific file types.

Queries and insights are both rendered as previews in the Simple Editor. Notice that for queries there is also an option to run the query in the bottom right corner of the window:

Screen_Shot_2019-03-29_at_3.20.56_PM.png

If you select the Run query option you'll be taken to a new tab in the workspace which will display the full results of the query (or the maximum number allowed for larger tables):

Screen_Shot_2019-03-29_at_3.24.56_PM.png

To get back to the summary window click on its tab at the top of the workspace:

Screen_Shot_2019-03-29_at_3.37.07_PM.png

Parameterized queries can also be embedded into the Simple Editor where they will be executable by the reader. The query is previewed in the editor window with all the parameter fields showing the default values. The reader can replace the defaults with other values and interactively run the query without ever leaving the summary, post, or insight. Running the query returns a preview of the first five rows of the query results. Clicking See all runs the query in a workspace and returns all the results from the parameters set by the reader (up to 10,000):

Screen_Shot_2019-05-06_at_12.49.37_PM.png

Embedding files from your desktop or a cloud storage device like iCloud, Dropbox, or Box is easy with the editor's drag and drop interface. Simply choose the file and drag it to the beginning of a line in the Simple Editor window. Non-image files will be added to the dataset or project:

drag_add__file.jpg

You will then need to embed the uploaded file into the editor window either with the command menu or by dragging and dropping it. If the file you choose is a supported image file, the image will be added to the editor window without being added to the dataset or project as a new file:

From a URL

Another source for embeddable content is a webpage. URL's can be embedded into the beginning of a line in a Simple Editor window and they will show up as either a preview of the webpage or as a link to it, depending on how the source page was configured by its author:

Screen_Shot_2019-05-06_at_1.42.33_PM.png
Embedding resources vs. linking resources

With the Simple Editor you have the choice of either embedding content directly into an editor window or linking to it. As we have seen, embedding content is done by dragging a resource to a new line in the editor window and dropping it into place. If, instead of dropping a resource at the beginning of a new line, you insert it in-line, a link to the resource will be created.

In each of the examples below a resource is shown linked on the top line of the summary and then embedded below the link:

Parameterized query link and embed
Screen_Shot_2019-05-06_at_2.13.34_PM.png
Image link and embed
Screen_Shot_2019-05-06_at_2.23.55_PM.png

Data visualization with Chart Builder

One of the most powerful ways to share results of your data analysis is through visualizations. On data.world you have access to both integrations for many third-party tools and also to Chart Builder, a visual editor for Vega-Lite built specifically for data.world. It is the perfect tool for those looking to create a simple visualization that is lightweight and easy to embed.

Visualizations in Chart Builder can be made from either a file or a query. They can be saved in various formats, shared, or embedded in the various Simple Editor windows.

Using Chart Builder with files

You can create visualizations of tabular data files in either projects or datasets without ever writing a query. To follow along with this example, open the dataset Shark attack data updated daily. To create a visualization of all the data in the file, select the View icon to the right of the file name on the overview page:

chart-builder-viz-01.png

You'll be taken to the data workspace and a view of all the data in the file. Next, click the dropdown arrow next to Open in app and choose Open with Chart Builder:

chart-builder-viz-02.png

If you're using Chart Builder for the first time, you'll be directed to a page requesting authorization. After authorizing, you'll be redirected to the Chart Builder workspace.

Chart Builder comes with two options for creating and modifying charts: a Visual Builder and a Vega-Lite Editor. The easiest way to use it is to create your initial chart on the Visual Builder tab and then switch over to the Vega-Lite Editor to make any changes outside the scope of the Visual Builder. See our article on using Vega-Lite or the Vega-Lite website for more information.

To create a quick bar chart of the number of people in the dataset who have been fatally attacked by sharks, select the field fatal_y_n from the dropdown list for the X axis, and COUNT(*) from the bottom of the list on the Y axis. Like magic, our chart appears on the right side of the screen:

Screen_Shot_2018-12-19_at_1.57.56_PM.png
Using Chart Builder with queries

Chart Builder can also be used on queries. Using a query as the basis for your chart enables you to:

  • Clean up data (e.g., remove NULL values)

  • Filter out data (e.g., specify a time period, a specific value, an aggregation, etc.)

  • Change your data structure so that it can be charted

In the shark attack dataset referenced above there is a saved query called Query for analysis by year or country This query has been written to exclude NULL values and remove non-binary entries on specific fields. It can be used to create a number of different charts. Click the dropdown arrow next to Open in app and choose Open with Chart Builder:

chart-builder-viz-03.png
Formatting options for visualizations

Continuing with the example above, to make a chart with circles for marks that compares the number of attacks on men vs on women across the years select Circle from the Marks dropdown, and year from the X axis dropdown:

Screen_Shot_2018-12-26_at_6.46.22_PM.png

If the axis doesn't display the way you want it to, you can override the default format for the Type under the Options dropdown. In this case the year was read as a number because of the underlying data type and the type was set to Quantitative when Ordinal was the right choice:

Screen_Shot_2018-12-26_at_6.50.01_PM.png

Set the Y axis to COUNT(*) and Color to sex:

Screen_Shot_2018-12-26_at_6.57.47_PM.png

If your chart is not appropriately sized for viewing you can manually set the chart size. A size that shows the data of this chart to best effect is a width of 950 and a height of 730:

Screen_Shot_2018-12-26_at_7.04.11_PM.png

Another handy thing you can do in the options section is order the results in your graph. You may have ordered them already in your query results, but that order does not carry over to the graph. For this example we'll use the saved query Countries with >10 unprovoked attacks since 1960 with mortality data. After running the query, click Chart, set the X axis to country and the Y axis to # attacks:

Screen_Shot_2018-12-26_at_7.14.54_PM.png

To sort by the country with he most attacks select Options on the X axis, choose Descending for the sort and y - # attacks on the field:

Screen_Shot_2018-12-23_at_5.19.49_PM.png

To add information on if the attacks were fatal or not, select fatal_y_n next to color.

Screen_Shot_2018-12-26_at_7.39.25_PM.png

If your results do not seem to display as they should, check to make sure the field you are sorting on is not being improperly aggregated. Being able to switch over to the Vega-Lite Editor is very handy for identifying this kind of configuration issues. Looking in the Vega-Lite Editor in the area dealing with "sort" the operation is set to "average":

Screen_Shot_2018-12-26_at_7.42.17_PM.png

In this case "sum" is the correct option, and upon replacing "average" with "sum" the visualization displays properly:

Screen_Shot_2018-12-26_at_7.45.33_PM.png

NOTE: Once you have made edits in the Vega-Lite Editor you can no longer make any changes in the Visual Builder so save your Vega-Lite Editor changes for when you are finished building the chart with the Visual Builder.

Saving and sharing visualizations

Chart-builder visualizations on data.world can be saved in a number of json, image, and html formats shown under the Download button:

Screen_Shot_2018-12-26_at_1.14.46_PM.png

There are also a variety of options for sharing your visualization on data.world:

Screen_Shot_2018-12-26_at_10.57.40_PM.png

Selecting Share > Insight lets you add your visualization to any project on data.world for which you have permission. To share the insight you are prompted to chose a project where you will share it, to give it a title, and optionally to add comments. The final option (selected by default) is to save the visualization as a Vega-Lite source file on the project.

Share > File lets you add the visualization to any dataset or project for which you have permission. Share > Markdown Embed (Comment) you can embed your chart in any place which uses Markdown (e.g., insights, comments, summaries). By default the embedded chart will be a static rendering of the data from when the visualization was created. However using the Vega-Lite Editor you can create a 'live' chart that updates as the data on which it's based updates. The shark attack dataset is an example of continually-updating data.

To make a chart 'live', go to the Vega-Lite Editor and scroll down to the section referencing the "data" parameters:

Screen_Shot_2018-12-26_at_10.40.49_PM.png

Under the "data" element replace "source" with "url" and add a hardcoded url for the query that drives the visualization (you get this in the workspace while viewing the query), and add a "format" element with the type "csv":

Screen_Shot_2018-12-26_at_10.42.13_PM.png

Then when you select Share > Markdown Embed (Comment), you'll get Markdown text for a live version of the visualization that you can copy and paste into Insights, Comments, and Summaries on data.world:

Screen_Shot_2018-12-26_at_10.39.43_PM.png

Here is an example of the live visualization above used as an insight on a project that uses the dataset:

Screen_Shot_2019-02-20_at_11.14.01_AM.png

Finally, if you want to share a link to the Chart Builder screen for the visualization so someone else can edit and run it, you can do so with the Share > URL option:

Screen_Shot_2018-12-27_at_12.11.48_AM.png
Troubleshooting
Error loading data

An expired token can cause one to receive a "Error loading data." message when opening Chart Builder. To remedy this:

  • Click on your account avatar on the top right corner of data.world and go to 'Your integrations'

  • Select the Chart Builder tile

  • On the Chart Builder page, select the Manage tab

  • Click the Revoke button and disconnect the Chart Builder integration

  • Click the Enable integration button and authorize access

Re-launching Chart Builder will now allow it to fetch the data successfully

Blank chart

When using the Vega-Lite editor to modify the Chart Builder output, many errors cause a blank chart to display. Troubleshooting must be manually carried out in this case - the Vega-Lite editor does not include any error identification functionality.

Using multiple columns of data in Chart Builder visualizations

Chart Builder is a quick and easy tool for creating visualizations of data on the fly, but there is one thing that isn't easy to do with it: include data from more than one column in your graph. This limitation can be a real problem if, say, you want to look at both the high and low temperatures on the days when Bigfoot was sighted. Or if you want to have a graph with gender, attack type, and fatality in shark attacks so you can see if there is any correlation between them. Though you can easily run the queries to display the data, you can't obviously render it all at the same time in Chart Builder. However, though it is a bit tricky and requires the use of UNPIVOT, you can build visualizations in Chart Builder that include data from more than one column in a query.

In this article we'll use the Project Monsters Among Us to show how to include two related fields in a visualization, and Analysis of shark attacks by region and species to do a little fancier combination of multiple columns of unrelated data into one visualization.

How to show data from two related fields in a Chart Builder visualization

There is a query called High and low temperatures on the dates of Bigfoot sightings in the Monsters project that returns a simple table with three columns:

Screen_Shot_2018-12-27_at_5.55.05_PM.png

Click on the Chart icon above the results to build a quick visualization from the query results. Set the X axis to date, the Y axis to temperature_low, and you have a visualization, but where do you put temperature_high?:

Screen_Shot_2018-12-27_at_9.51.04_PM.png

Looking at the data, the solution is to put both the high temp and the low temp values in the same column and call it temperature, and to have another column called temp_value that would indicate whether the temp shown is a high temp or a low temp for the day. Fortunately, this kind of data reorganization where columns get collapsed into rows is what the SQL UNPIVOT command does. Here is the original query rewritten to use UNPIVOT to collapse the high and low temp columns into one column, and the resulting table:

Screen_Shot_2018-12-27_at_10.17.25_PM.png

Select Chart to use Chart Builder on the results of the query, set the marks to Circle, the X axis to date, the Y axis to temperature, the color to temp_type, resize the chart toto 640 X 700, and you'll have this visualization:

Screen_Shot_2018-12-27_at_10.23.44_PM.png
Combining multiple columns of unrelated data into one visualization

In this example we have a query in the project Analysis of shark attacks by region and species that returns dates, type of attack, gender of the victim, and whether the attack was fatal or not:

Screen_Shot_2018-12-28_at_9.28.51_AM.png

To get a quick visualization of it select Chart, setCircle for marks,year for the X axis (you might have to open the options and set the type to Ordinal), COUNT (*) for the Y axis, and Gender for the color. Once it's been resized you get this chart:

Screen_Shot_2018-12-28_at_9.39.01_AM.png

As in the last example, there's no way to include attack-type or fatality data. However, a redo of the original query with UNPIVOT combines all the data into one column ready for Chart Builder:

Screen_Shot_2018-12-28_at_6.42.13_PM.png

Note: Even though there is a warning that only the first 10,000 rows of the results are displayed, when we chart the query with chart Builder, all the data is used in the visualization.

The chart from the query is built the same as before. SetCircle for marks,year for the X axis (you might have to open the options and set the type to Ordinal), COUNT (*) for the Y axis. Set Type for the color. Once it's been resized you get this chart::

Screen_Shot_2018-12-28_at_6.47.48_PM.png

If you want to try unpivoting some queries on your own and charting them, there are a couple more--Provocation and gender in shark attacks, and Provocation and fatality in shark attacks--saved on the project that you can use.

Additional information about UNPIVOT can be found in our SQL documentation.

Using the Vega Lite editor in Chart Builder

Chart Builder uses Vega-Lite, which provides a JSON syntax for creating and styling visualizations. While the Visual Builder interface within Chart Builder on data.world allows one to quickly generate a simple chart, using the Vega Lite editor allows extensive customization of the appearance of the chart.

One important note - once you modify a chart using the Vega Lite editor, the Visual Builder will no longer be accessible. Customize the chart as much as possible in the Visual Builder first before switching to the Vega Lite editor for fine-tuning to keep yourself from needing to do extra work.

This article assumes that you have already enabled the Chart Builder integration on your data.world account. If you have not already, you can enable it from the integrations page while logged into your account.

For a primer on using Chart Builder, please see the Data visualization with Chart Builder.

Getting started

As an example, I've created a project based on a dataset from the US Department of Energy regarding types of energy production throughout the US.

  1. Open up the following query saved to that project: Top 10 states by residential solar energy production

  2. You can then open these query results in Chart Builder using the dropdown menu above the results pane:

    mceclip0.png
  3. Title the chart "Rooftop photovoltaic energy production by US state (top 10)" by clicking on the text that says Untitled chart above.

  4. To the left of the chart, configure the the X axis to use the state field and the Y axis to use the gwh field.

  5. Click on the Options dropdown for the X axis, and under the Sort section, choose Descending by y - gwh.

Screen_Shot_2019-07-18_at_5.42.41_PM.png

You will then see the same chart as below:

Screen_Shot_2019-07-16_at_1.35.42_PM.png

That's a good start, but it's a bit bland and would be difficult to read if projected onto a screen across a conference room. Let's get to work!

Styling the chart title

By default, a Chart Builder adds the title automatically, but does not provide any graphical way to style it. Click on the Vega Lite editor on the top left and you'll see the following entry near the top:

"title": "Rooftop photovoltaic energy production by US state (top 10)"

To transform the title into a field that we can customize, make it into a JSON object by adding curly braces and adding the text property:

"title": {"text": "Rooftop photovoltaic energy production by US state (top 10)" }

The title will look the same as before, but we've laid the foundation for further styling by turning it into a JSON object.

Alignment

The anchor attribute determines the horizontal alignment of the title. Options include:

  • start

  • middle

  • end

In our example, let's align the title on the left side of the chart:

"title": {
   "text": "Rooftop photovoltaic energy production by US state (top 10)",
   "anchor": "start"
 }
Font

We'll use the following attributes to style the font used for the title:

  • font - the name of the font

  • fontSize - the size of the font in pixels

  • color - color of the font, given in a CSS-compatible hex code or color name

This attributes are great for matching the chart to an organization's own branding guidelines. Make the following update to give the title that authentic data.world feel:

"title": {
   "text": "Rooftop photovoltaic energy production by US state (top 10)",
   "anchor": "start",
   "font": "Lato",   "fontSize": 24,   "color": "#355D8A"
 }
Offset

Our title is looking much better now, but there isn't much space between it and the chart beneath it. Give it some breathing room by adding the offsetattribute. The offset value is the number of pixels between the title and the edge of the chart.

"title": {
   "text": "Rooftop photovoltaic energy production by US state (top 10)",
   "anchor": "start",
   "font": "Lato",
   "fontSize": 24,
   "color": "#355D8A",
   "offset": 40
 }

And here's the result so far:

Styling the axis labels

To modify the axis labels (in this case, the names on the x-axis andnumbers on on the y-axis), we'll add some additional attributes within the configobject already present in our Vega Lite editor. By default, the config object will look like:

"config": {
   "background": "#ffffff",
   "padding": 20,
}

Within that configobject, add a new object called axis to modify the labels on both the X and Y axes at the same time. That object will accept a number of attributes; we'll use the following:

  • labelFontSize - label font size in pixels

  • labelFont - label font name

  • labelColor - color of the label font, given in a CSS-compatible hex code or color name

Our config object now looks like this:

"config": {
   "background": "#ffffff",
   "padding": 20,
   "axis": {     "labelFontSize": 20,     "labelFont": "Lato",     "labelColor": "#6290C3"   }
 }

We modified labels for both axes above, but we can also style axes singly as well. The state names under the X axis are difficult to read with their current orientation, so change that by adding an axisX object within the config object.

Use the labelAngle attribute to control the angle of those labels, providing the number of degrees to rotate them.

"config": {
   "background": "#ffffff",
   "padding": 20,
   "axis": {
     "labelFontSize": 20,
     "labelFont": "Lato",
     "labelColor": "#6290C3",
     "titleFontSize": 24,
     "titleColor": "#333D49",
     "titleFont": "Lato"
   },
   "axisX": {     "labelAngle": 40   }
 }
Styling the axis titles

Our labels are much more readable now, but we need to update those state and gwh axis titles as well. For those, specify the following attributes within the config>axis object:

  • titleFont - axis title font name

  • titleFontSize - axis title font size in pixels

  • titleFontColor - color of the axis title font, given in a CSS-compatible hex code or color name

"config": {
 "background": "#ffffff",
 "padding": 20,
 "axis": {
   "labelFontSize": 20,
   "labelFont": "Lato",
   "labelColor": "#6290C3",
   "titleFontSize": 24,   "titleColor": "#333D49",   "titleFont": "Lato"
   }
}
Screen_Shot_2019-07-16_at_3.15.09_PM.png

Finally, let's edit the title text for each axis (e.g. state and gwh). This will use the column name from our query results by default. In our case, those titles aren't so bad, but in many cases they'll be difficult to read and full of underscores and abbreviations.

Navigate to the encoding object within the Vega Lite editor. It will have a number of nested objects below it already. Find the nested object encoding>x. Add and attribute called title and provide the desired name to that attribute - in this case, give it the value "State Name".

Also add a title attribute under encoding>y and provide the value "Gigawatt hours (GWh)".

Here's our new encoding object:

"encoding": {
 "x": {
   "field": "state",
   "title": "State Name",
   "type": "nominal",
   "sort": {
     "field": "gwh",
     "op": "sum",
     "order": "descending"
      },
   "scale": {
   "type": "linear",
   "zero": true
   }
 },
 "y": {
   "field": "gwh",
   "title": "Gigawatt hours (GWh)",
   "type": "quantitative",
   "scale": {
     "type": "linear",
     "zero": true
     }
   }
 }

And our final chart:

Screen_Shot_2019-07-16_at_3.39.05_PM.png

This tutorial provided some basic styling functionality by accessing the Vega Lite editor in Chart Builder directly, but it can do so much more. Check out the official Vega Lite examples, tutorials, and full documentation for an in depth look.