Creating Your First Livedoc

This tutorial guides you through creating a Livedocs document to analyze and visualize employee salary data using the sample dataset employee.csv. This file contains detailed information about employee demographics, job roles, salaries, and performance ratings, providing a realistic dataset for practicing data exploration and visualization.

Through this hands-on tutorial, you will learn how to import data, perform analyses, and create visualizations using Livedocs' core features. Specifically, you will focus on exploring how salary varies across departments and uncovering patterns in salary distribution. By following along, you will gain a foundational understanding of Livedocs' data handling, analysis, and visualization capabilities. These skills will equip you to confidently navigate your own data projects and uncover actionable insights.

Step 1: Setting Up the Data Source

The first step in this tutorial is to set up the data source and explore its structure. You will create a new document, add a Table element, and inspect the raw data to get familiar with the dataset.

Accessing the Sample Data

Livedocs provides the employee.csv file as a preloaded sample dataset. This file contains key details about employees, including their salaries and the departments they belong to. It is the foundation for the analyses we will perform in this tutorial.

To locate the data:

1. Navigate to the Data tab in the Livedocs workspace.
2. Under the Files section, find employee.csv listed as an available file. There is no need to upload this file because it is ready to use.

note

You may also see another file, sales.csv, available under the Files section. While sales.csv is provided for additional exploration, this tutorial will focus exclusively on employee.csv.

Creating a New Document

Now that you have located the data source, it is time to create a document where you will conduct your analysis.

1. Click on the Docs tab at the top of the workspace.
2. Click Create doc to open a new, blank document.
3. In the blank document canvas, update the default title (New doc - [current date]) to reflect the purpose or content of this tutorial, such as "Employee Salary Analysis."
4. Provide an optional description for your document in the smaller description field below the title. For this tutorial, you can use: "Analyzing average salaries across departments to uncover trends in employee compensation."

Your new document is now ready for you to add elements and begin building your analysis. Each document in Livedocs is automatically saved as you work, so you can focus on your tasks without worrying about data loss.

Adding a Table Element to View Data

To start exploring the dataset, let us add a Table element to the document. This element allows you to view and interact with the raw data, providing an overview of its structure and contents.

info

Elements are the building blocks of a Livedocs document, enabling you to create interactive and data-driven narratives. Each element serves a specific purpose, from visualizing data to documenting findings or performing complex transformations.

To add a Table element:

1. Locate the elements toolbar at the bottom of the document workspace. This toolbar provides options for adding other elements such as tables, charts, and queries.
2. Click Table to insert a new Table element.
3. In the dropdown menu inside the Table element, select employee.csv as the data source.

Once added, the Table element will display the data in a structured format. Here are some key fields to note:

• Age: Provides demographic data, offering insights into how salaries vary across age groups.
• Department: Groups employees by their respective teams or functions.
• MonthlyIncome: Shows employee salaries, which are the focus of this tutorial.

info

The Table element displays raw data directly from the data source, such as database tables and CSV files. It can also render data from supported Python objects, including Polars DataFrames. While it cannot modify or transform data, the Table element serves as a foundational tool for exploring and referencing the dataset. Take a moment to familiarize yourself with the structure of the data before moving on to the next step.

With the data now displayed in the Table element, you have a clear view of the dataset's structure and key fields. In the next step, you will analyze salary variations across departments by creating a Query element to calculate averages and a Chart element to visualize the results.

Step 2: Analyzing Salary Data by Department

With the data source set up and displayed in the Table element, the next step is to analyze salary variations across departments. This involves using a Query element to calculate the average monthly income and count the number of employees in each department. You will then create a Grouped column chart to visualize the results, showcasing how department size and income levels relate.

Adding a Query Element for Analysis

To calculate the average monthly income and the number of employees for each department:

1. Click Query in the elements toolbar to add a new Query element below the Table element.
2. In the Query element's data source dropdown menu, select employee.csv.
3. Enter the following SQL query into the query editor:

   SELECT
     Department,
     AVG(MonthlyIncome) AS AverageIncome,
     COUNT(*) AS EmployeeCount
   FROM employee.csv
   GROUP BY Department
   ORDER BY AverageIncome DESC;
4. Click the Run button of the Query element to execute the query.
5. At the top of the Query element, enter "Department Income and Count" as the name for this element.

The Query element will display a table with the following columns:

• Department: The name of each department.
• AverageIncome: The average monthly income of employees in that department.
• EmployeeCount: The total number of employees in each department.

Based on the employee.csv dataset, the results should look like this:

• Sales: AverageIncome = 6959.17, EmployeeCount = 446
• Human Resources: AverageIncome = 6654.50, EmployeeCount = 63
• Research & Development: AverageIncome = 6281.25, EmployeeCount = 961

Visualizing the Results with a Grouped Column Chart

Now that you have calculated the average monthly income and employee count for each department, let us create a Grouped column chart to visualize the results:

1. Click Chart in the elements toolbar to add a new Chart element below the Query element.
2. In the Chart element's data source dropdown menu, select dataframe_0, the Polars DataFrame variable generated by the Query element.
3. In the Chart type option, select Grouped column.
4. Configure the X-axis:
   • Set the Field to Department.
5. Configure the Y-axis:
   • Add AverageIncome as the primary metric.
   • Set Scale type to Number (this will be automatically detected).
   • In the Color by option, select EmployeeCount as the data field. This will colorize the bars based on department size, providing an additional layer of context.
6. Click the Run button within the Chart element to render the chart.
7. At the top of the Chart element, enter "Department Income Visualization" as the name for this element.

The chart will display three vertical bars, one for each department, representing the average monthly income. The color intensity of the bars corresponds to the employee count, as indicated by the legend. This configuration provides a clear comparison of income levels while subtly reflecting department sizes.

info

The variable name dataframe_0 is not guaranteed to be the same on the user's end. This variable naming starts at 0 for newly created documents and increments based on the number of DataFrame objects present. Ensure you select the correct data source in your Chart element.

note

The Chart element auto-updates its visualization as you adjust its options or inputs. Although the Run button is rarely needed for the Chart element, clicking it ensures any manual changes are finalized and properly rendered.

Why Include Employee Count?

Including EmployeeCount in this analysis helps contextualize the income data. It highlights discrepancies, such as why a department with fewer employees (e.g., Human Resources) might have a higher average income than a larger department (e.g., Research & Development). By visualizing employee count alongside income, you can uncover patterns that might not be apparent from raw data alone.

---

With this visualization complete, the next step is to document your findings and questions for further analysis. In the following step, you will learn how to use the Text element to summarize insights and prepare for deeper exploration.

Step 3: Documenting Insights with the Text Element

With the visualization complete, the next step is to document your findings and outline any questions or further analyses using the Text element. This step demonstrates how to use the Text element effectively to annotate and summarize your work within a Livedocs document.

Adding a Text Element

To add a Text element:

1. Click Text in the elements toolbar to add a new Text element below the Chart element.
2. In the Text element, write a short summary of your findings from the query results and chart visualization. For example:
   • "The Sales department has the highest average income at $6,959.17, followed by Human Resources at $6,654.51, and Research & Development at $6,281.25. Despite having the highest employee count (961), the Research department has the lowest average income, while Human Resources, with the fewest employees (63), has a higher average income."

note

The Run button renders the Text element's content as a finalized output in your document. Since formatting is applied instantly in the element's editor, the Run button might seem redundant. However, the rendered output is collapsible, allowing you to declutter your workspace. This feature is especially useful when working with extensive annotations or observations.

Utilizing Rich-Text Formatting

The Text element supports rich-text formatting, allowing you to organize and present your findings in a visually appealing and clear manner. Formatting options include:

• Bold, italic, and strikethrough text
• Ordered and unordered lists
• Hyperlinks for referencing external resources

Take advantage of these features to highlight key insights or structure your content effectively. For example:

• Use bold to emphasize significant values, such as department averages.
• Organize observations and questions using bullet points for better readability.

Summarizing Insights

Here is an example of how you might summarize the insights using rich-text formatting:

• Sales department leads in average income, which might reflect higher compensation for sales-driven roles.
• Research & Development department, despite its large workforce, has the lowest average income, likely due to a higher proportion of lower-paying roles.
• Human Resources, though small in size, has specialized roles that contribute to its higher average income.

note

The example text and formatting in this section are designed to inspire and guide you in using the Text element effectively. The screenshot provided is a rendition of how we applied formatting to document insights in this tutorial. While you are welcome to replicate the example, we encourage you to decide how to format your text creatively. This flexibility allows you to personalize the content and practice applying rich-text features in Livedocs.

The screenshot below illustrates how the example insights could be formatted within the Text element. Use it as a reference or inspiration for your own documentation style:

Noting Questions for Further Analysis

You can also use the Text element to jot down questions or areas for further analysis. For example:

• "What roles in Research & Development contribute to the lower average income?"
• "How do job roles within departments affect overall compensation trends?"
• "Does the number of years with the company correlate with income levels?"

These notes help structure your next steps in exploring the dataset and making data-driven conclusions.

---

In the next step, you will dig deeper into the dataset to analyze role-level income variations using another Chart element. This analysis will provide a more granular view of the factors influencing average income across departments.

Step 4: Exploring Role-Level Income Variations

Having documented your observations and questions, the next step is to delve deeper into the dataset to uncover insights at the role level. By analyzing job roles within each department, you can better understand how specific roles contribute to income variations across departments.

info

For this deeper analysis, we will switch back to using the raw data from employee.csv instead of the aggregated DataFrame object (dataframe_0). The raw dataset allows us to leverage the Chart element's built-in aggregation features, enabling a more granular examination of job roles within departments.

Adding a New Chart Element

To create a chart that visualizes income variations by job role:

1. Click Chart in the elements toolbar to add a new Chart element below the Text element.
2. In the Chart element's data source dropdown menu, select employee.csv as the data source.
3. In the Chart type option, select Grouped column.
4. Configure the X-axis:
   • Set the Field to Department.
5. Configure the Y-axis:
   • Add MonthlyIncome as the primary metric.
   • Set Aggregate to Average to calculate the average income for each job role within departments.
6. In the Color by option:
   • Select JobRole to distinguish job roles by unique colors, enabling you to see the distribution of roles and their average incomes within each department.
7. Click the Run button within the Chart element to render the chart.
8. At the top of the Chart element, enter "Role-Level Income Distribution" as its title to reflect the focus of this visualization.

The chart will display grouped vertical bars for each department, with each bar segment representing a job role. This provides a clear visualization of how roles contribute to department-wide income trends.

note

The Color by option groups and colorizes job roles within departments, making it easier to differentiate their contributions to overall income. Use the chart legend to identify each role by its assigned color.

Interpreting Role-Level Insights

Analyze the chart to identify trends and discrepancies:

• Sales Department: The high average income is primarily driven by the Manager role, which has significantly higher compensation compared to other roles like Sales Representatives.
• Research & Development: A greater variation in role-level incomes suggests that lower-paying roles like Laboratory Technicians contribute to the department's overall lower average income.
• Human Resources: Despite having fewer roles, the higher average income is influenced by specialized positions such as Managers, who are consistently among the highest-paid roles across all departments.

tip

Consider adding a new Text element below the chart to document your role-level findings in detail. Use rich-text formatting to organize observations, emphasize key insights, and note questions for further analysis.

note

The screenshot below is an example of how you might use a new Text element to document role-level insights. While you are welcome to replicate this, feel free to customize the content and formatting to suit your own observations and style.

Optional Questions for Further Exploration

After completing the analysis in Step 4, consider these optional questions to extend your learning:

• How do other factors, such as years of experience, correlate with income across roles and departments?
• Are there patterns in job roles across departments that consistently affect average income?
• What strategies could improve income equality among roles within departments?

info

These questions are optional and designed to inspire further exploration using Livedocs. While the tutorial does not address these directly, you are encouraged to investigate them as a way to deepen your understanding and practice with the tool.

Preparing for the Final Steps

With a comprehensive analysis complete, it is time to focus on sharing and collaborating on your findings. In the final steps, you will ensure that your document is up-to-date, validated, and ready for publishing and collaboration with your team or stakeholders.

Step 5: Running the Document and Preparing for Sharing

Before sharing or publishing your document, it is important to ensure that all elements are up-to-date and processed correctly. Livedocs provides a main Run button at the top of the document workspace for this purpose.

Introducing the Main Run Button

The Run button, located at the top-right corner of the navigation bar, executes all elements within the document. This function ensures that every element is processed with the latest data and configurations.

Why Use the Main Run Button?

While the individual Run buttons of the elements allow you to execute and validate specific sections of your document, the main Run button applies this functionality across the entire document. This feature is particularly useful when:

• Working with Dynamic Data: Refreshes data pulled from external sources, ensuring that your document reflects the latest information.
• Validating Analysis: Confirms the accuracy and integrity of your calculations, queries, and visualizations by processing all elements at once.
• Preparing for Sharing or Publishing: Ensures collaborators or readers see the most up-to-date content when accessing your document.

info

However, in this tutorial, the data source is a static CSV file (employee.csv). Since the data is fixed, you might not notice a difference when using the main Run button. This example demonstrates its use, but the button's benefits become more apparent with dynamic or live data sources. Understanding this functionality is key when working with real-world, changing datasets.

How to Use the Main Run Button

1. Locate the Run button at the top of the document workspace.
2. Click the button to execute all elements in the document.
3. Observe the progress indicator within the Run button to monitor execution.

Once the document finishes running, all elements will display their respective results, refreshed and ready for sharing.

note

Although the main Run button is an excellent way to ensure the entire document is updated, individual Run buttons for elements have their merits. For example, if you are troubleshooting or making changes to a specific element, running it individually avoids unnecessary execution of unrelated elements.

With the document refreshed and validated, you are now ready to share your insights with collaborators. The next section will guide you through the process of publishing and sharing your document in Livedocs.

Step 6: Publishing and Sharing Your Livedocs Document

With your analysis and findings complete, the next steps involve publishing your document to make it accessible to collaborators and sharing it with others for collaboration or review.

Publishing Changes

To ensure your document is up-to-date and shareable:

1. Locate the Publish Changes button next to the Run button at the top-right corner of the document workspace.
2. Click Publish Changes to finalize your edits and make the document accessible for sharing.

Once published, the document reflects your latest updates and is ready to be shared.

info

Publishing your document is necessary for collaborators or viewers to access your latest updates. Without publishing, changes made to the document remain private and are not visible to others. This applies to both new documents and updates made to previously shared ones.

Sharing the Document

After publishing, you can share the document with collaborators or stakeholders:

1. Click the Share button to open the sharing menu.
2. Toggle Share with link ON to allow anyone with the link to view the document. If toggled OFF, access will be restricted.
3. Choose one of the following sharing methods:
   • Copy Link: Click this option to copy the document's shareable URL. Share this link directly with collaborators.
   • Send doc by email: Enter the recipient's email address in the provided field, then click Send to email the link directly.

Your collaborators will now be able to access the shared document based on the configured settings. Regardless of the method, the shared document appears consistent for all viewers.

How the Shared Document Looks

When collaborators access the shared document using one of the sharing methods mentioned earlier, they will see the elements exactly as you created them in the Livedocs workspace. However, there are some differences:

• View-Only Elements: Interactive elements like Table and Query elements retain functionality like pagination if applicable, but cannot be moved or edited.
• Rendered Results Only: The shared document displays the results of the elements (e.g., executed queries, rendered charts, and formatted text) at the time of publishing.
• Simplified Interface: The shared document includes only the document title, description, and elements. It does not display the Livedocs Sidekick or navigation bar.

Below is a cropped screenshot of the tutorial's example document as it appears to collaborators:

Collaborating Effectively

Livedocs enables real-time collaboration, making it easier for teams to work together on the same document. Here are some tips for effective teamwork:

• Annotating Insights: Use Text elements to provide context for visualizations or analyses, making it easier for collaborators to understand the document.
• Publishing Updates: Publish changes periodically to keep collaborators aligned with the latest content. Ensure proper permissions are set in the sharing menu for collaboration.
• Sharing Flexibility: Use sharing links, embedded codes, or email invitations to tailor access based on your audience's needs.

---

With your document now published and shared, you are ready to move forward and reflect on the steps you have completed in this tutorial. From setting up a data source to sharing your findings, you have laid the groundwork for leveraging Livedocs in your workflows. In the next section, we will review what you have accomplished and explore opportunities to expand your skills with Livedocs.

Wrapping Up the Tutorial

Congratulations on completing this tutorial! You have explored the core features of Livedocs, from setting up a data source to sharing your findings. Let us review the steps you took and provide recommendations for your next steps.

Summary of Steps

Here is a recap of what you have accomplished:

1. Working with Provided Data: You used the pre-loaded employee.csv file as a data source in Livedocs, which served as the foundation for your analysis.
2. Querying and Visualizing: Using Query and Chart elements, you explored and visualized trends such as average income across departments and role-level variations.
3. Documenting Insights: You used the Text element to summarize findings, document observations, and jot down questions for further analysis.
4. Publishing and Sharing: You published and shared your document, making it accessible for collaboration with your team.

Next Steps for Users

This tutorial provided you with a glimpse into Livedocs and its foundational features. While it is a great starting point, we encourage you to continue exploring and expanding your knowledge of Livedocs to unlock its full potential.

To build on what you have learned, consider the following:

1. Dive Deeper into the Dataset: Analyze relationships between fields like YearsAtCompany and JobSatisfaction, or explore variations in WorkLifeBalance by JobRole. Use Query and Chart elements to uncover more insights and patterns.
2. Read the Livedocs Document Basics Guide: For a deeper understanding, we recommend reading the Livedocs Document Basics guide. This foundational resource covers workflows, tips, and techniques to optimize your use of Livedocs.
3. Explore Advanced Features: When ready, explore other guides under the Working with Documents section, such as managing documents and understanding Sidekick, to deepen your understanding.

If you are interested in advanced workflows, consider experimenting with:

• Python Elements: Integrate Python into your workflow for advanced analysis. For example, use the DataFrame object from the Polars library to manipulate and analyze datasets effectively.
• Real-Time Data Sources: Experiment with connecting to live databases or APIs for dynamic data integration.
• Advanced Visualizations: Create multi-metric or layered charts to uncover complex patterns and trends, or embed visualizations for interactive presentations and reports.

Moving Forward

Livedocs is a powerful tool for transforming data into actionable insights. As you continue working with your own datasets, try experimenting with the supported elements and customizing documents to suit your unique workflows.

For further assistance, consult the guides in this documentation, which cover everything from foundational workflows to advanced techniques. These resources are designed to help you make the most of Livedocs as you grow in confidence and skill.

---

We hope this tutorial has inspired you to explore Livedocs' many possibilities. With practice and experimentation, you will uncover its full potential for data analysis and storytelling. Keep pushing boundaries and discovering new ways to leverage Livedocs!