[DOCS] Updates Lens and editor pages for 7.14 (#104756)

* [DOCS] Lens features and changes for 7.14

* Aggregation reference

* Formatting

* Fixes terminology

* Updates from 8-Jul meeting

* Terminology

* Updates terminology, images, and tutorial steps

* Update docs/user/dashboard/lens-advanced.asciidoc

Co-authored-by: Wylie Conlon <wylieconlon@gmail.com>

* Update docs/user/dashboard/create-panels-with-editors.asciidoc

Co-authored-by: Wylie Conlon <wylieconlon@gmail.com>

* Update docs/user/dashboard/lens.asciidoc

Co-authored-by: Wylie Conlon <wylieconlon@gmail.com>

* Comments from review

* Cleans up unused images

* Fixes image reference

Co-authored-by: Wylie Conlon <wylieconlon@gmail.com>

docs/management/manage-index-patterns.asciidoc

@@ -48,7 +48,7 @@ The script must match the field *Type*, or the script fails.
 +
 For information on how to create runtime fields in *Discover*, refer to <<add-field-in-discover,Add a field>>.
 +
-For information on how to create runtime fields in *Lens*, refer to <<add-fields-in-lens,Add fields>>.
+For information on how to create runtime fields in *Lens*, refer to <<change-the-fields,Change the fields list>>.
 
 [float]
 [[runtime-field-examples]]

docs/user/dashboard/aggregation-based.asciidoc

@@ -1,8 +1,22 @@
 [[add-aggregation-based-visualization-panels]]
 === Aggregation-based
 
-Aggregation-based visualizations are the core {kib} panels, and are not optimized
-for a specific use case.
+Aggregation-based visualizations are the core {kib} panels, and are not optimized for a specific use case.
+
+With aggregation-based visualizations, you can:
+
+* Split charts up to three aggregation levels, which is more than *Lens* and *TSVB*
+* Create visualization with non-time series data
+* Use a <<save-open-search,saved search>> as an input
+* Sort data tables and use the summary row and percentage column features
+* Assign colors to data series
+* Extend features with plugins
+
+Aggregation-based visualizations include the following limitations:
+
+* Limited styling options
+* Math is unsupported
+* Multiple indices is unsupported
 
 [float]
 [[types-of-visualizations]]
@@ -135,7 +149,7 @@ Add the sample web logs data that you'll use to create the bar chart, then creat
 [float]
 ===== Open and set up the aggregation-based bar chart
 
-Open the bar chart visualization builder and change the time range. 
+Open the *Aggregation based* editor and change the time range. 
 
 . On the dashboard, click *All types > Aggregation based*, select *Vertical bar*, then select *kibana_sample_data_logs*.
 

docs/user/dashboard/create-panels-with-editors.asciidoc

@@ -1,134 +1,496 @@
-[[create-panels-with-editors]]
+[[aggregation-reference]]
 == Create panels with editors
 
-{kib} provides several editors that you can use to create panels of your data.
+{kib} provides several editors that you can use to create panels of your data. Each editor supports different features and {ref}/search-aggregations.html[{es} aggregations]. To choose the best editor for your data, review the following information.
 
-[cols="2"]
+[float]
+[[chart-types]]
+=== Supported panel types
+
+[options="header"]
 |===
 
-| <<lens,*Lens*>>
-| Create visualizations with the drag and drop editor.
+| Panel type | *Lens* | *TSVB* | *Aggregation-based* | *Vega* | *Timelion*
 
-| <<maps,*Maps*>>
-| Create visualizations with your geographical data.
+| Table
+| &check;
+| &check;
+| &check;
+|
+|
 
-| <<tsvb,*TSVB*>>
-| Create visualizations with your time series data.
+| Bar, line, and area
+| &check;
+| &check;
+| &check;
+| &check;
+| &check;
 
-| <<vega,*Vega*>>
-| Create custom visualizations with the *Vega* and *Vega-Lite* grammars.
+| Split chart and small multiples
+|
+| &check;
+| &check;
+| &check;
+|
 
-| <<add-aggregation-based-visualization-panels,*Aggregation based*>>
-| Build most visualization types using {es} <<aggregation-reference,aggregations>>. 
+| Pie and donut
+| &check;
+|
+| &check;
+| &check;
+|
 
-| <<timelion,*Timelion*>>
-| Create visualizations with your time series data using a simple expression language.
+| Sunburst
+| &check;
+|
+| &check;
+| &check;
+|
+
+| Treemap
+| &check;
+|
+|
+| &check;
+|
+
+| Heatmap
+| &check;
+|
+| &check;
+| &check;
+|
+
+| Gauge and Goal
+|
+| &check;
+| &check;
+| &check;
+|
+
+| Markdown
+|
+| &check;
+|
+|
+|
+
+| Metric
+| &check;
+| &check;
+| &check;
+| &check;
+|
+
+| Tag cloud
+|
+|
+| &check;
+| &check;
+|
 
 |===
 
 [float]
-[[lens-editor]]
-=== Lens
+[[xy-features]]
+=== Bar, line, and area chart features
 
-*Lens* is the drag and drop editor that creates visualizations of your data, recommended for most
-users.
+[options="header"]
+|===
 
-With *Lens*, you can:
+| Feature | *Lens* | *TSVB* | *Aggregation-based* | *Vega* | *Timelion*
 
-* Use the automatically generated suggestions to change the visualization type.
-* Create visualizations with multiple layers and indices.
-* Change the aggregation and labels to customize the data.
-* Perform math on aggregations using *Formula*.
-* Use time shifts to compare data at two times, such as month over month.
+| Dense time series
+| Customizable
+| &check;
+| Customizable
+| &check;
+| &check;
 
-[role="screenshot"]
-image:dashboard/images/lens_advanced_1_1.png[Lens]
+| Percentage mode
+| &check;
+| &check;
+| &check;
+| &check;
+|
+
+| Break downs
+| 1
+| 1
+| 3
+| &infin;
+| 1
+
+| Custom color with break downs
+|
+| Only for Filters
+| &check;
+| &check;
+|
+
+| Fit missing values
+| &check;
+|
+| &check;
+| &check;
+| &check;
+
+| Synchronized tooltips
+|
+| &check;
+|
+|
+|
+
+|===
 
 [float]
-[[tsvb-editor]]
-=== TSVB
+[[other-features]]
+=== Advanced features
 
-*TSVB* is a time series data visualization editor that allows you to use the full power of the {es} aggregation framework. 
+[options="header"]
+|===
 
-With *TSVB*, you can:
+| Feature | *Lens* | *TSVB* | *Vega* | *Timelion*
 
-* Combine an infinite number of <<aggregation-reference,aggregations>> to display your data.
-* Annotate time series data with timestamped events from an {es} index.
-* View the data in several types of visualizations, including charts, data tables, and markdown panels.
-* Display multiple <<index-patterns, index patterns>> in each visualization.
-* Customize the data with labels and colors.
+| Math
+| &check;
+| &check;
+| &check;
+| &check;
 
-[role="screenshot"]
-image::images/tsvb.png[TSVB UI]
+| Math across indices
+|
+|
+| &check;
+| &check;
+
+| Visualize two indices
+| &check;
+| &check;
+| &check;
+| &check;
+
+| Time shift
+| &check;
+| &check;
+| &check;
+| &check;
+
+| Custom {es} queries
+|
+|
+| &check;
+|
+
+| Normalize by time
+| &check;
+| &check;
+|
+|
+
+| Automatically generated suggestions
+| &check;
+| 
+|
+|
+
+| Annotations
+| 
+| &check;
+|
+|
+
+|===
 
 [float]
-[[custom-visualizations]]
-=== Custom visualizations
+[[table-features]]
+=== Table features
 
-*Vega* and *Vega-Lite* are visualization grammars that are integrated into {kib} for custom visualizations.
+[options="header"]
+|===
 
-* *Vega-Lite* &mdash; A high-level grammar for rapid analysis.
+| Feature | *Lens* | *TSVB* | *Aggregation-based*
 
-* *Vega* &mdash; A declarative language with support for interactivity.
+| Summary row
+| &check;
+|
+| &check;
 
-*Vega* and *Vega-Lite* panels can display one or more data sources, including {es}, Elastic Map Service,
-URL, or static data, and support <<reference-for-kibana-extensions,{kib} extensions>> that allow you to embed the panels on your dashboard and add interactive tools.
+| Pivot table
+| &check;
+|
+|
 
-Use *Vega* or *Vega-Lite* when you want to create visualizations with:
+| Calculated column
+| Formula
+| &check;
+| Percent only
 
-* Aggregations that use `nested` or `parent/child` mapping
-* Aggregations without an index pattern
-* Queries that use custom time filters
-* Complex calculations
-* Extracted data from _source instead of aggregations
-* Scatter charts, sankey charts, and custom maps
-* An unsupported visual theme
+| Color by value
+| &check;
+| &check;
+|
 
-These grammars have some limitations: they do not support tables, and can't run queries conditionally.
-
-[role="screenshot"]
-image::images/vega.png[Vega UI]
-
-For detailed *Vega* and *Vega-Lite* information and examples, refer to <<resources-and-examples,Resources and examples>>. 
+|===
 
 [float]
-[[aggregation-based]]
-=== Aggregation-based
+[[custom-functions]]
+=== Functions
 
-With aggregation-based visualizations, you can:
+[options="header"]
+|===
 
-* Create heat map, tag cloud, gauge, and goal visualizations
-* Split charts up to three aggregation levels, which is more than *Lens* and *TSVB*
-* Time series data is not required
-* Use a <<save-open-search,saved search>> as an input
-* Sort data tables and use the summary row and percentage column features
-* Assign colors to series
-* Extend features with plugins
+| Function | *Lens* | *TSVB*
 
-[role="screenshot"]
-image:dashboard/images/aggregation_based.png[Aggregation-based editor]
+| Counter rate
+| &check;
+| &check;
 
-Aggregation-based visualizations include the following limitations:
+| <<tsvb-function-reference, Filter ratio>>
+| Use <<lens-formulas, formula>>
+| &check;
 
-* Limited styling options
-* Math is unsupported
-* Multiple indices is unsupported
+| <<tsvb-function-reference, Positive only>>
+|
+| &check;
+
+| <<tsvb-function-reference, Series agg>>
+|
+| &check;
+
+| Static value
+|
+| &check;
+
+|===
 
 [float]
-[[timelion-editor]]
-=== Timelion
+[[metrics-aggregations]]
+=== Metrics aggregations
 
-*Timelion* is driven by a simple expression language that you use to:
+Metric aggregations are calculated from the values in the aggregated documents. The values are extracted from the document fields.
 
-* Retrieve time series data from one or more indices
-* Perform math across two or more time series
-* Visualize the results
+[options="header"]
+|===
 
-[role="screenshot"]
-image:dashboard/images/timelion.png[Timelion]
+| Aggregation | *Lens* | *TSVB* | *Aggregation-based* | *Vega*
+
+| Metrics with filters
+| &check;
+|
+|
+| &check;
+
+| Average, Sum, Max, Min
+| &check;
+| &check;
+| &check;
+| &check;
+
+| Unique count (Cardinality)
+| &check;
+| &check;
+| &check;
+| &check;
+
+| Percentiles and Median
+| &check;
+| &check;
+| &check;
+| &check;
+
+| Percentiles Rank
+|
+| &check;
+| &check;
+| &check;
+
+| Standard deviation
+|
+| &check;
+| &check;
+| &check;
+
+| Sum of squares
+|
+| &check;
+|
+| &check;
+
+| Top hit (Last value)
+| &check;
+| &check;
+| &check;
+| &check;
+
+| Value count 
+| 
+| 
+| &check;
+| &check;
+
+| Variance
+| 
+| &check;
+| 
+| &check;
+
+|===
+
+For information about {es} metrics aggregations, refer to {ref}/search-aggregations-metrics.html[Metrics aggregations].
+
+[float]
+[[bucket-aggregations]]
+=== Bucket aggregations
+
+Bucket aggregations group, or bucket, documents based on the aggregation type. To define the document buckets, bucket aggregations compute and return the number of documents for each bucket.
+
+[options="header"]
+|===
+| Aggregation | *Lens* | *TSVB* | *Aggregation-based* | *Vega*
+
+| Histogram
+| &check;
+| 
+| &check;
+| &check;
+
+| Date histogram
+| &check;
+| &check;
+| &check;
+| &check;
+
+| Date range
+| Use filters
+| 
+| &check;
+| &check;
+
+| Filter
+|
+| &check;
+|
+| &check;
+
+| Filters
+| &check;
+| &check;
+| &check;
+| &check;
+
+| GeoHash grid
+| 
+| 
+| &check;
+| &check;
+
+| IP range
+| Use filters
+| Use filters
+| &check;
+| &check;
+
+| Range
+| &check;
+| Use filters
+| &check;
+| &check;
+
+| Terms
+| &check;
+| &check;
+| &check;
+| &check;
+
+| Significant terms
+|
+|
+| &check;
+| &check;
+
+|===
+
+For information about {es} bucket aggregations, refer to {ref}/search-aggregations-bucket.html[Bucket aggregations].
+
+[float]
+[[pipeline-aggregations]]
+=== Pipeline aggregations
+
+Pipeline aggregations are dependent on the outputs calculated from other aggregations. Parent pipeline aggregations are provided with the output of the parent aggregation, and compute new buckets or aggregations that are added to existing buckets. Sibling pipeline aggregations are provided with the output of a sibling aggregation, and compute new aggregations for the same level as the sibling aggregation.
+
+[options="header"]
+|===
+
+| Aggregation | *Lens* | *TSVB* | *Aggregation-based* | *Vega*
+
+| Avg bucket  
+| <<lens-formulas, `overall_average` formula>>
+| &check;
+| &check;
+| &check;
+
+| Derivative  
+| &check;
+| &check;
+| &check;
+| &check;
+
+| Max bucket   
+| <<lens-formulas, `overall_max` formula>>
+| &check;
+| &check;
+| &check;
+
+| Min bucket   
+| <<lens-formulas, `overall_min` formula>>
+| &check;
+| &check;
+| &check;
+
+| Sum bucket  
+| <<lens-formulas, `overall_sum` formula>>
+| &check;
+| &check;
+| &check;
+ 
+| Moving average  
+| &check;
+| &check;
+| &check;
+| &check;
+
+| Cumulative sum 
+| &check;
+| &check;
+| &check;
+| &check;
+
+| Bucket script 
+| 
+| 
+| &check;
+| &check;
+
+| Bucket selector
+| 
+| 
+|
+| &check;
+
+| Serial differencing 
+| 
+| &check;
+| &check;
+| &check;
+
+|===
+
+For information about {es} pipeline aggregations, refer to {ref}/search-aggregations-pipeline.html[Pipeline aggregations].
 
 include::lens.asciidoc[]
 include::tsvb.asciidoc[]
 include::vega.asciidoc[]
 include::aggregation-based.asciidoc[]
-include::timelion.asciidoc[]
+include::timelion.asciidoc[]

docs/user/dashboard/dashboard.asciidoc

@@ -16,7 +16,7 @@ Panels display your data in charts, tables, maps, and more, which allow you to c
 [cols="2"]
 |===
 
-| <<create-panels-with-editors,Editors>>
+| <<aggregation-reference,Editors>>
 | Use the *Lens*, *TSVB*, *Vega*, and *Timelion* editors to create visualizations of your data, or create *Aggregation based* visualizations using {es} aggregations. 
 *Lens* is the recommended editor.
 
@@ -335,5 +335,3 @@ include::lens-advanced.asciidoc[]
 include::create-panels-with-editors.asciidoc[]
 
 include::make-dashboards-interactive.asciidoc[]
-
-include::aggregation-reference.asciidoc[]

docs/user/dashboard/lens-advanced.asciidoc

@@ -1,76 +1,66 @@
 [[create-a-dashboard-of-panels-with-ecommerce-data]]
-== Time series analysis with Lens
+== Analyze time series data
 
-The tutorial uses sample data from the perspective of a shop owner looking
-at sales trends, but this type of dashboard works on any type of data.
-To create dashboard panels of the data, open the *Lens* visualization builder, then  
-create the visualization panels that best display the data.
-Before using this tutorial, you should be familiar with the <<kibana-concepts-analysts>>.
+In this tutorial, you'll use the ecommerce sample data to analyze sales trends, but you can use any type of data to complete the tutorial.
+Before using this tutorial, review the <<kibana-concepts-analysts>>.
 
 [role="screenshot"]
-image::images/lens_advanced_result.png[Dashboard view]
+image::images/final_time_series_analysis_dashboard.png[Final dashboard with ecommerce sample data, width=50%]
 
 [discrete]
 [[add-the-data-and-create-the-dashboard-advanced]]
 === Add the data and create the dashboard
 
-If you are working with your own data, you should already have an <<index-patterns, index pattern>>.
-To install the sample sales data:
+Add the sample ecommerce data that you'll use to create the dashboard panels. 
 
-. From the {kib} *Home* page, click *Try our sample data*.
+. Go to the {kib} *Home* page, then click *Try our sample data*.
 
-. From *Sample eCommerce orders*, click *Add data*.
+. On the *Sample eCommerce orders* card, click *Add data*.
 
-Then create a new dashboard:
+Create the dashboard where you'll display the visualization panels.
 
 . Open the main menu, then click *Dashboard*.
 
 . On the *Dashboards* page, click *Create dashboard*.
 
-. Set the <<set-time-filter,time filter>> to *Last 30 days*.
-
 [float]
 [[open-and-set-up-lens-advanced]]
 === Open and set up Lens
 
-*Lens* is designed to help you quickly build visualizations for your dashboard, as shown in <<create-a-dashboard-of-panels-with-web-server-data,Build your first dashboard>>, while providing support for advanced usage as well.
-
-Open the *Lens* editor, then make sure the correct fields appear.
+Open *Lens*, then make sure the correct fields appear.
 
 . From the dashboard, click *Create visualization*.
 
 . Make sure the *kibana_sample_data_ecommerce* index appears.
++
+If you are using your own data, select the <<index-patterns, index pattern>> that contains your data.
 
 [discrete]
 [[custom-time-interval]]
 === View a date histogram with a custom time interval
 
 It is common to use the automatic date histogram interval, but sometimes you want a larger or smaller
-interval. *Lens* only lets you choose the minimum time interval, not the exact time interval, for
-performance reasons. The performance limit is controlled by the <<histogram-maxbars, `histogram:maxBars`>>
-advanced setting and the overall time range. To see hourly sales over a 30 day time period, choose
-one of these options:
+interval. For performance reasonse, *Lens* lets you choose the minimum time interval, not the exact time interval. The performance limit is controlled by the <<histogram-maxbars, `histogram:maxBars`>> setting and the <<set-time-filter,time range>>. 
 
-* View less than 30 days at a time, then use the time picker to select each day separately.
+If you are using your own data, use one of the following options to see hourly sales over the last 30 days:
 
-* Increase `histogram:maxBars` from 100 to at least 720, which the number of hours in 30 days.
-This affects all visualizations and can reduce performance.
+* View less than 30 days at a time, then use the time filter to select each day separately.
 
-* If approximation is okay, use the *Normalize unit* option. This can convert *Average sales per 12 hours*
-into *Average sales per 12 hours (per hour)* by dividing the number of hours.
+* Increase `histogram:maxBars` to at least 720, which is the number of hours in 30 days. This affects all visualizations and can reduce performance.
 
-For the sample data, approximation is okay. To use the *Normalize unit* option:
+If you are using the sample data, use *Normalize unit*, which converts *Average sales per 12 hours*
+into *Average sales per 12 hours (per hour)* by dividing the number of hours:
 
 . Set the <<set-time-filter,time filter>> to *Last 30 days*.
 
-. From the *Available fields* list, drag and drop *Records* to the visualization builder.
+. From the *Available fields* list, drag *Records* to the workspace.
+
+. To zoom in on the data you want to view, click and drag your cursor across the bars. 
 +
 [role="screenshot"]
 image::images/lens_advanced_1_1.png[Added records to the workspace]
 
-. Change the *Vertical axis* title and display the number of orders per day. 
-
-.. In the editor, click *Count of Records*.
+. In the layer pane, click *Count of Records*.
 
 .. In the *Display name* field, enter `Number of orders`.
 
@@ -80,9 +70,6 @@ image::images/lens_advanced_1_1.png[Added records to the workspace]
 
 . To hide the *Horizontal axis* label, open the *Bottom Axis* menu, then deselect *Show*.
 +
-[role="screenshot"]
-image::images/lens_advanced_1_1_2.png[Bottom axis menu]
-+
 You have a bar chart that shows you how many orders were made at your store every hour.
 +
 [role="screenshot"]
@@ -92,103 +79,89 @@ image::images/lens_advanced_1_2.png[Orders per day]
 
 [discrete]
 [[add-a-data-layer-advanced]]
-=== Monitor multiple series within a date histogram
+=== Monitor multiple series
 
-It is often required to monitor multiple series within a time interval. These series can be have similar configurations with few changes between one and another.
-*Lens* copies a function when you drag and drop it to the *Drop a field or click to add*
-field within the same group, or when you drag and drop to the *Duplicate* field on a different group.
-You can also drag and drop using your keyboard. For more information, refer to <<drag-and-drop-keyboard-navigation,Create visualization panels with keyboard navigation>>.
+It is often required to monitor multiple series within a time interval. These series can have similar configurations with minor differences.
+*Lens* copies a function when you drag it to the *Drop a field or click to add* field within the same group.
 
 To quickly create many copies of a percentile metric that shows distribution of price over time:
 
-. From the *Chart Type* dropdown, select *Line*.
-+
-[role="screenshot"]
-image::images/lens_advanced_2_1.png[Chart type menu with Line selected, width=50%]
+. On the dashboard, click *Create visualization*.
 
-. From the *Available fields* list, drag and drop *products.price* to the visualization builder.
+. Open the *Chart Type* dropdown, then select *Line*.
 
-. Create the 95th percentile.
+. From the *Available fields* list, drag *products.price* to the workspace.
 
-.. In the editor, click *Median of products.price*.
+Create the 95th percentile.
 
-.. From *Select a function*, click *Percentile*.
+. In the layer pane, click *Median of products.price*.
 
-.. In the *Display name* field, enter `95th`, then click *Close*.
+. Click the *Percentile* function.
 
-. To create the 90th percentile, duplicate the `95th` percentile.
+. In the *Display name* field, enter `95th`, then click *Close*.
 
-.. Drag and drop *95th* to *Drop a field or click to add*.
+To create the 90th percentile, duplicate the `95th` percentile.
 
-.. Click *95th [1]*, then enter `90` in the *Percentile* field.
-
-.. In the *Display name* field enter `90th`, then click *Close*.
+. Drag the *95th* field to the *Drop a field or click to add* field in the *Vertical axis* group.
 +
 [role="screenshot"]
 image::images/lens_advanced_2_2.gif[Easily duplicate the items with drag and drop]
 
-.. Repeat the duplication steps to create the `50th` and `10th` percentile, naming them accordingly.
+. Click *95th [1]*, then enter `90` in the *Percentile* field.
 
-. To change the left axis label, open the *Left Axis* menu, then enter `Percentiles for product prices` in the *Axis name* field.
-+
-[role="screenshot"]
-image::images/lens_advanced_2_2_1.png[Left Axis menu]
+. In the *Display name* field enter `90th`, then click *Close*.
+
+. Repeat the duplication steps to create the `50th` and `10th` percentiles.
+
+. Open the *Left Axis* menu, then enter `Percentiles for product prices` in the *Axis name* field.
 +
 You have a line chart that shows you the price distribution of products sold over time.
 +
 [role="screenshot"]
 image::images/lens_advanced_2_3.png[Percentiles for product prices chart]
 
-. Add the filter for the redirect codes. 
+. Click *Save and return*.
 
 [discrete]
 [[add-a-data-layer]]
-==== Multiple chart types or index patterns in one visualization
+==== Add multiple chart types or index patterns
 
-You can add multiple metrics to a single chart type, but if you want to overlay
-multiple chart types or index patterns, use a second layer. When building layered charts,
-it is important to match the data on the horizontal axis so that it uses the same
-scale. To add a line chart layer on top of an existing chart:
+To overlay visualization types or index patterns, add layers. When you create layered charts, match the data on the horizontal axis so that it uses the same scale. 
 
-To compare product prices with customers traffic:
+. On the dashboard, click *Create visualization*.
 
-. From the *Available fields* list, drag and drop *products.price* to the visualization builder.
+. From the *Available fields* list, drag *products.price* to the workspace.
 
-.. In the *KQL* field, enter `response.keyword>=500 AND response.keyword<600`. 
+. In the layer pane, click *Median of products.price*.
 
-.. From *Select a function*, click *Average*.
+.. Click the *Average* function.
 
 .. In the *Display name* field, enter `Average of prices`, then click *Close*.
 
-. From the *Chart Type* dropdown, select *Area*.
+. Open the *Chart Type* dropdown, then select *Area*.
 
-. Create a new layer to overlay with custom traffic.
+Create a new layer to overlay with custom traffic.
 
-. In the editor, click *+*.
-+
-[role="screenshot"]
-image::images/lens_advanced_3_1.png[Add new layer button]
+. In the layer pane, click *+*.
 
-. From the *Available fields* list, drag and drop *customer_id* to the *Vertical Axis* of the newly created layer.
+. From the *Available fields* list, drag *customer_id* to the *Vertical Axis* field in the second layer.
 
-.. In the editor, click *Unique count of customer_id*.
+. In the second layer, click *Unique count of customer_id*.
 
-.. In the *Display name* field, enter `Unique customers`, then click *Close*.
+.. In the *Display name* field, enter `Unique customers`.
 
-. In the *Series color* field, enter *#D36086*, then click *Close*.
+.. In the *Series color* field, enter *#D36086*.
 
-. For *Axis side*, click *Right*, then click *Close*.
+.. Click *Right* for the *Axis side*, then click *Close*.
 
-. From the *Available fields* list, drag and drop *order_date* to the *Horizontal Axis* of the newly created layer.
+. From the *Available fields* list, drag *order_date* to the *Horizontal Axis* field in the second layer.
 
-. From the new layer editor, click the *Chart type* dropdown, then click the line chart.
+. In the second layer pane, open the *Chart type* menu, then click the line chart.
 +
 [role="screenshot"]
 image::images/lens_advanced_3_2.png[Change layer type]
 
-The visualization is done, but the legend uses a lot of space. Change the legend position to the top of the chart.
-
-. From the *Legend* dropdown, select the top position.
+. Open the *Legend* menu, then select the arrow that points up.
 
 . Click *Save and return*.
 
@@ -198,47 +171,41 @@ The visualization is done, but the legend uses a lot of space. Change the legend
 
 By default, *Lens* shows *date histograms* using a stacked chart visualization, which helps understand how distinct sets of documents perform over time. Sometimes it is useful to understand how the distributions of these sets change over time.
 Combine *filters* and *date histogram* functions to see the change over time in specific
-sets of documents. To view this as a percentage, use a *stacked percentage* bar or area chart.
+sets of documents. To view this as a percentage, use a *Stacked percentage* bar or area chart.
 
-To see sales change of product by type over time:
+. On the dashboard, click *Create visualization*.
 
-. From the *Available fields* list, drag and drop *Records* to the visualization builder.
+. From the *Available fields* list, drag *Records* to the workspace.
 
-. Click *Bar vertical stacked*, then select *Area percentage*.
+. Open the *Chart type* dropdown, then select *Area percentage*.
 
-For each category type that you want to break down, create a filter. 
+For each category type, create a filter. 
 
-. In the editor, click the *Drop a field or click to add* field for *Break down by*.
+. In the layer pane, click the *Drop a field or click to add* field for *Break down by*.
 
-. From *Select a function*, click *Filters*.
+. Click the *Filters* function.
 
-. Add the filter for the clothing category. 
+. Click *All records*, enter the following, then press Return:
 
-.. Click *All records*.
+* *KQL* &mdash; `category.keyword : *Clothing`
 
-.. In the *KQL* field, enter `category.keyword : *Clothing`. 
+* *Label* &mdash; `Clothing`
 
-.. In the *Label* field, enter `Clothing`, then press Return.
+. Click *Add a filter*, enter the following, then press Return:
 
-. Add the filter for the shoes category. 
+* *KQL* &mdash; `category.keyword : *Shoes`
 
-.. Click *Add a filter*.
+* *Label* &mdash; `Shoes`
 
-.. In the *KQL* field, enter `category.keyword : *Shoes`. 
+. Click *Add a filter*, enter the following, then press Return:
 
-.. In the *Label* field, enter `Shoes`, then press Return.
+* *KQL* &mdash; `category.keyword : *Accessories`
 
-. Add the filter for the accessories category. 
+* *Label* &mdash; `Accessories`
 
-.. Click *Add a filter*.
+. Click *Close*.
 
-.. In the *KQL* field, enter `category.keyword : *Accessories`. 
-
-.. In the *Label* field, enter `Accessories`, then press Return.
-
-Change the legend position to the top of the chart.
-
-. From the *Legend* dropdown, select the top position.
+. Open the *Legend* menu, then select the arrow that points up.
 +
 [role="screenshot"]
 image::images/lens_advanced_4_1.png[Prices share by category]
@@ -251,43 +218,35 @@ image::images/lens_advanced_4_1.png[Prices share by category]
 
 To determine the number of orders made only on Saturday and Sunday, create an area chart, then add it to the dashboard.
 
-. Open *Lens*.
+. On the dashboard, click *Create visualization*.
 
-. From the *Chart Type* dropdown, select *Area*.
+. Open the *Chart Type* dropdown, then select *Area*.
 
-. Configure the cumulative sum of the store orders.
+Configure the cumulative sum of the store orders.
 
-.. From the *Available fields* list, drag and drop *Records* to the visualization builder.
+. From the *Available fields* list, drag *Records* to the workspace.
 
-.. From the editor, click *Count of Records*.
+. In the layer pane, click *Count of Records*.
 
-.. From *Select a function*, click *Cumulative sum*.
+. Click the *Cumulative sum* function.
 
-.. In the *Display name* field, enter `Cumulative orders during weekend days`, then click *Close*.
+. In the *Display name* field, enter `Cumulative orders during weekend days`, then click *Close*.
 
-. Filter the results to display the data for only Saturday and Sunday.
+Filter the results to display the data for only Saturday and Sunday.
 
-.. From the editor, click the *Drop a field or click to add* field for *Break down by*. 
+. In the layer pane, click the *Drop a field or click to add* field for *Break down by*. 
 
-.. From *Select a function*, click *Filters*.
+. Click the *Filters* function.
 
-.. Click *All records*.
+. Click *All records*, enter the following, then press Return:
 
-.. In the *KQL* field, enter `day_of_week : "Saturday" or day_of_week : "Sunday"`, then press Return.
+* *KQL* &mdash; `day_of_week : "Saturday" or day_of_week : "Sunday"`
+
+* *Label* &mdash; `Saturday and Sunday`
 +
 The <<kuery-query,KQL filter>> displays all documents where `day_of_week` matches `Saturday` or `Sunday`.
-+
-[role="screenshot"]
-image::images/lens_advanced_5_1.png[Filter aggregation to filter weekend days]
 
-. To hide the legend, open the *Legend* menu, then click *Hide*.
-+
-[role="screenshot"]
-image::images/lens_advanced_5_2_1.png[Legend menu]
-+
-You have an area chart that shows you how many orders your store received during the weekend.
-
-. Click *Bar vertical stacked*, then select *Area*.
+. Open the *Legend* menu, then click *Hide*.
 +
 [role="screenshot"]
 image::images/lens_advanced_5_2.png[Line chart with cumulative sum of orders made on the weekend]
@@ -298,34 +257,33 @@ image::images/lens_advanced_5_2.png[Line chart with cumulative sum of orders mad
 [[compare-time-ranges]]
 === Compare time ranges
 
-*Lens* allows you to compare the currently selected time range with historical data using the *Time shift* option. To calculate the percent
-change, use *Formula*.
+*Lens* allows you to compare the selected time range with historical data using the *Time shift* option. 
 
-If multiple time shifts are used in a single chart, a multiple of the date histogram interval should be chosen - otherwise data points might not line up in the chart and empty spots can occur.
-For example, if a daily interval is used, shifting one series by *36h*, and another one by *1d*, is not recommended. In this scenario, either reduce the interval to *12h*, or create two separate charts.
+If multiple time shifts are used in a single chart, a multiple of the date histogram interval should be chosen, or the data points might not line up and gaps can appear.
+For example, if a daily interval is used, shifting one series by *36h*, and another by *1d* is not recommended. You can reduce the interval to *12h*, or create two separate charts.
 
 To compare current sales numbers with sales from a week ago, follow these steps: 
 
-. Open *Lens*.
+. On the dashboard, click *Create visualization*.
 
-. From the *Chart Type* dropdown, select *Line*.
+. Open the *Chart Type* dropdown, then select *Line*.
 
-. From the *Available fields* list, drag and drop *Records* to the visualization builder.
+. From the *Available fields* list, drag *Records* to the workspace.
 
-. Copy the *Count of Records* series by dragging it to the empty drop target of the *Vertical axis* dimension group (*Drop a field or click to add*)
+. In the layer pane, drag *Count of Records* to the *Drop a field or click to add* field in the *Vertical axis* group.
 
-. Shift the second *Count of Records* series by one week to do a week-over-week comparison
+To create a week-over-week comparison, shift the second *Count of Records* by one week.
 
-.. Click the new *Count of Records [1]* dimension
+. In the layer pane, click *Count of Records [1]*.
 
-.. Click *Add advanced options* below the field selector
+. Open the *Add advanced options* dropdown, then select *Time shift*.
 
-.. Click *Time shift*
-
-.. Click the *1 week* option. You can also define custom shifts by typing amount followed by time unit (like *1w* for a one week shift), then hit enter.
+. Click *1 week ago*.
++
+To define custom time shifts, enter the time value, the time increment, then press Enter. For example, to use a one week time shift, enter *1w*.
 +
 [role="screenshot"]
-image::images/lens_time_shift.png[Line chart with week-over-week sales comparison, width=50%]
+image::images/lens_time_shift.png[Line chart with week-over-week sales comparison]
 
 . Click *Save and return*.
 
@@ -333,64 +291,63 @@ image::images/lens_time_shift.png[Line chart with week-over-week sales compariso
 [[compare-time-as-percent]]
 ==== Compare time ranges as a percent change
 
-To view the percent change in sales between the current time and the previous week, use a *Formula*:
+To view the percent change in sales between the current time and the previous week, create a *Formula*.
 
-. Open *Lens*.
+. On the dashboard, click *Create visualization*.
 
-. From the *Available fields* list, drag and drop *Records* to the visualization builder.
+. From the *Available fields* list, drag *Records* to the workspace.
 
-. Click *Count of Records*, then click *Formula*.
+. In the layer pane, click *Count of Records*.
 
-. Type `count() / count(shift='1w') - 1`. To learn more about the formula
-syntax, click *Help*.
+.. Click *Formula*, then enter `count() / count(shift='1w') - 1`.
 
-. Click *Value format* and select *Percent* with 0 decimals.
+.. Open the *Value format* dropdown, select *Percent*, then enter `0` in the *D*ecimals* field.
 
-. In the *Display name* field, enter `Percent change`, then click *Close*.
+.. In the *Display name* field, enter `Percent change`, then click *Close*.
++
+[role="screenshot"]
+image::images/lens_percent_chage.png[Bar chart with percent change in sales between the current time and the previous week]
 
 . Click *Save and return*.
 
 [discrete]
 [[view-customers-over-time-by-continents]]
-=== View table of customers by category over time
+=== Create a table of customers by category over time
 
-Tables are an alternative type of visualization for time series, useful when you want to read the actual values.
-You can build a date histogram table, and group the customer count metric by category, like the continent registered in their profile.
+Tables are useful when you want to display the actual field values.
+You can build a date histogram table, and group the customer count metric by category, such as the continent registered in user accounts.
 
 In *Lens* you can split the metric in a table leveraging the *Columns* field, where each data value from the aggregation is used as column of the table and the relative metric value is shown.
 
-To build a date histogram table:
+. On the dashboard, click *Create visualization*.
 
-. Open *Lens*.
+. Open the *Chart Type* dropdown, then click *Table*.
 
-. From the *Chart Type* dropdown, select *Table*.
+. From the *Available fields* list, drag *customer_id* to the *Metrics* field in the layer pane.
 
-.. From the *Available fields* list, drag and drop *customer_id* to the *Metrics* field of the editor.
+. In the layer pane, click *Unique count of customer_id*.
 
-.. From the editor, click *Unique count of customer_id*.
+. In the *Display name* field, enter `Customers`, then click *Close*.
 
-.. In the *Display name* field, enter `Customers`, then click *Close*.
+. From the *Available fields* list, drag *order_date* to the *Rows* field in the layer pane.
 
-.. From the *Available fields* list, drag and drop *order_date* to the *Rows* field of the editor.
+. In the layer pane, click the *order_date*.
 
-.. From the editor *Rows*, click the *order_date* field just dropped.
+.. Select *Customize time interval*.
 
-. Select *Customize time interval*.
-
-. Change the *Minimum interval* to `1 days`, then click *Close*.
+.. Change the *Minimum interval* to *1 days*.
 
 .. In the *Display name* field, enter `Sale`, then click *Close*.
 
-To split the customers count by continent:
+Add columns for each continent.
 
-. From the *Available fields* list, drag and drop *geoip.continent_name* to the *Columns* field of the editor.
+. From the *Available fields* list, drag *geoip.continent_name* to the *Columns* field in the layer pane.
 +
 [role="screenshot"]
-image::images/lens_advanced_6_1.png[Table with daily customers by continent configuration, width=50%]
+image::images/lens_table_over_time.png[Date histogram table with groups for the customer count metric]
 
 . Click *Save and return*.
 
-
 [discrete]
 === Save the dashboard
 
@@ -398,4 +355,8 @@ Now that you have a complete overview of your ecommerce sales data, save the das
 
 . In the toolbar, click *Save*.
 
-. On the *Save dashboard* window, enter `Ecommerce sales data`, then click *Save*.
+. On the *Save dashboard* window, enter `Ecommerce sales`, then click *Save*.
+
+. Select *Store time with dashboard*.
+
+. Click *Save*.

docs/user/dashboard/lens.asciidoc

@@ -1,8 +1,14 @@
 [[lens]]
 === Lens
 
-To create visualizations with *Lens*, you drag and drop data fields onto the visualization builder, 
-then *Lens* uses heuristics to apply each field. 
+To create visualization panels with *Lens*, you drag the data fields you want to visualize to the workspace, then *Lens* uses heuristics to apply each field and create a visualization for you. 
+
+With *Lens*, you can:
+
+* Create area, line, and bar charts with multiple layers, indices, and visualization types.
+* Change the aggregation function and labels to customize the data.
+* Perform math on aggregations using *Formula*.
+* Use time shifts to compare data for two time intervals, such as month over month.
 
 ++++
 <script type="text/javascript" async 
@@ -18,200 +24,216 @@ data-type="inline"
 </br>
 ++++
 
-[float]
-[[lens-required-choices]]
-==== Open and set up Lens
-
-Open *Lens*, then explore the fields in your data. The list of fields are determined by the index pattern and time filter.
-
-. On the dashboard, click *Create visualization*.
-
-. In *Lens*, <<set-time-filter,set the time filter>>. 
-
-. To view the fields in the a different index pattern, click the index pattern, then select a different index pattern from the dropdown.
-
-. Scan through the list of fields to see what’s in your data.
-+
-TIP: For sparse datasets, *Empty fields* can contain data, which you can use to create visualizations.
-
-. To filter the data fields, use the following options:
-
-* Enter the field name in the *Search field names* field. 
-
-* Click *Field by type*, then select the filter. To show all fields in the index pattern, deselect *Only show fields with data*.
-
-[float]
-[[view-the-data-summaries]]
-===== View the data summaries
-
-For each field, *Lens* displays a summary depending on the type of data. To analyze the fields, *Lens* uses a sample of 5,000 documents. 
-Each summary displays the percentage of sampled documents over all available documents.
-
-To view a data summary, click *i* next to the field.
-
-[role="screenshot"]
-image::images/lens_data_info_documents.png[Data summary analyzed documents]
-
-Each data type display the following summaries:
-
-* *Date* &mdash; Displays the time distribution.
-
-* *String* &mdash; Displays the top 10 values.
-
-* *Numeric* &mdash; Displays the top 10 values and a value distribution. When *Lens* displays the top 10 values distribution, the percentage of *Other* values is also displayed. 
-For array value fields, the percentage distribution considers each value in the array as separate.
-
-TIP: *Other* can equal more than 100% by a small amount.
-
 [float]
 [[create-the-visualization-panel]]
 ==== Create visualizations
 
-Drag and drop the fields on to the visualization builder, then customize the visualization.
+If you're unsure about the visualization type you want to use, or how you want to display the data, drag the fields you want to visualize onto the workspace, then let *Lens* choose for you. 
 
-. Drag and drop the fields on to the visualization builder.
+If you already know the visualization type you want to use, and how you want to display the data, use the following process:
 
-. To change the visualization type, use the following options:
-
-* Click the *Suggestions*.
-
-* From the *Chart Type* dropdown, click the visualization.
-
-. To configure the data, use the editor, then click *Close*.
-
-. To configure the visualization, use the dropdown menus.
+* *Choose the visualization type.* Open the *Chart type* dropdown, then select the visualization type before you drag any fields.  
 +
-[role="screenshot"]
-image::images/lens_value_labels_xychart_toggle.png[Lens Bar chart value labels menu]
+To view more visualizations that *Lens* automatically created for the fields, click the *Suggestions*. If one of the *Suggestions* meets your visualization needs, click *Save and return* to add it to the dashboard.
+
+* *Choose the data you want to visualize.* Drag the fields directly to the layer pane. *Lens* automatically selects the aggregation function.
++
+If you want to learn more about the data a field contains, click *i* next to the field.
+
+* *Edit and delete.* To change the *Quick function* and display options, click the field in the layer pane. To delete a field, close the configuration options, then click *X* next to the field.
 
 [float]
-[[add-fields-in-lens]]
-===== Add fields
+[[change-the-fields]]
+==== Change the fields list
 
-Add and define fields to the index pattern that you want to visualize using the {ref}/modules-scripting-painless.html[Painless scripting language].
-The fields that you are add are saved to the index pattern and appear in all visualizations, saved searches, and saved objects that use the index pattern. 
+Change the fields list to display a different index pattern, different time range, or add your own fields.
 
-. Click *...*, then select *Add field to index pattern*.
+* To create a visualization with fields in a different index pattern, open the *Change index pattern* dropdown, then select the index pattern. 
+
+* If the fields list is empty, change the <<set-time-filter,time filter>>.
+
+* To add fields, open the action menu (*...*) next to the *Change index pattern* dropdown, then select *Add field to index pattern*.
 +
 [role="screenshot"]
 image:images/runtime-field-menu.png[Dropdown menu located next to index pattern field with items for adding and managing fields, width=50%]
-
-. Enter a *Name* for the field, then select the field *Type*.
-
-. Select *Set value*, then define the field value by emitting a single value using the {ref}/modules-scripting-painless.html[Painless scripting language].
-
-. Click *Save*.
 +
-To manage the field, click the field, then click *Edit index pattern field* or *Remove index pattern field*.
-+
-[role="screenshot"]
-image:images/manage-runtime-field.gif[Field menu to edit or remove field from index pattern, width=50%]
+For more information about adding fields to index patterns and examples, refer to <<runtime-fields>>.
 
-For more information about adding fields to index patterns and Painless scripting language examples, refer to <<runtime-fields,Runtime fields>>.
+[float]
+[[lens-formulas]]
+==== Use formulas to perform math
+
+Formulas allow you to perform math on aggregated data. The most common formulas divide two values to produce a percent.
+
+. In the layer pane, click a field.
+
+. Click *Formula*, then enter the formula. 
++
+Filter ratio example:: Use `kql=''` to filter one set of documents, then compare the document set to other documents within the same grouping:
++
+See how the error rate changes over time:
++
+```
+count(kql='response.status_code > 400') / count()
+```
++
+Week over week example:: Use `shift='1w'` to get the value of each grouping from the previous week. Time shift should not be used with the *Top values* function.
++
+```
+percentile(system.network.in.bytes, percentile=99) /
+percentile(system.network.in.bytes, percentile=99, shift='1w')
+```
++
+Percent of total example:: Formulas can calculate `overall_sum` for all the groupings,
+which lets you convert each grouping into a percent of total:
++
+```
+sum(products.base_price) / overall_sum(sum(products.base_price))
+```
+TIP: For detailed information on formulas, click image:dashboard/images/formula_reference.png[Formula reference icon].
+
+. To accurately display the formula, select *Percent* from the *Value format* dropdown.
+
+[float]
+[[compare-data-with-time-offsets]]
+==== Compare differences over time
+
+Compare your real-time data set to the results that are offset by a time increment. For example, you can compare the real-time percentage of a user CPU time spent to the results offset by one hour. 
+
+. In the layer pane, click the field you want to offset.
+
+. From the *Add advanced options* dropdown, select *Time shift*.
+
+. Select the time offset increment. 
+
+For a time shift example, refer to <<compare-time-ranges>>.
+
+[float]
+[[create-custom-tables]]
+==== Create custom tables
+
+*Lens* tables are highly customizable, and provide you with text alignment, value formatting, coloring options, and more.
+
+. From the *Chart type* dropdown, select *Table*. 
+
+. Drag the fields you want to visualize to the workspace. 
+
+. To sort or hide the columns, click the arrow next to the column heading, then select an option.
++
+All columns that belong to the same layer pane group are sorted in the table.
+
+. To change the display options, click a *Metrics* field, then configure the following options:
+
+* *Display name* &mdash; Specifies the field display name. 
+
+* *Value format* &mdash; Specifies how the field value displays in the table. 
+
+* *Text alignment* &mdash; Aligns the values in the cell to the *Left*, *Center*, or *Right*.
+
+* *Hide column* &mdash; Hides the column for the field.
+
+* *Summary row* &mdash; Adds a row that displays the summary value. When specified, allows you to enter a *Summary label*.
+
+* *Color by value* &mdash; Applies color to the cell or text values. To change the color, click *Edit*. 
 
 [float]
 [[drag-and-drop-keyboard-navigation]]
-===== Create visualizations with keyboard navigation
+==== Create visualizations with keyboard navigation
 
-*Lens* has a fully accessible, continuously improved drag and drop system, which allows you to use a keyboard instead of a mouse.
+To use a keyboard instead of a mouse, use the *Lens* fully accessible and continuously improved drag system.
 
 [role="screenshot"]
 image::images/lens_drag_drop_1.gif[Presented Lens drag and drop]
 
-. Set a focus on the chosen item. Most of the draggable elements have two focus states. The inner focus state opens a panel with detailed information or options. 
-The outer focus state allows you to drag an item. Tab through the page until you get the outer focus state on the chosen item:
+. Select the field in the fields list or layer pane. Most fields have an inner and outer select state. The inner state opens a panel with detailed information or options. 
+The outer state allows you to drag the field. Tab through the fields until you get the outer state on the field.
 +
 [role="screenshot"]
 image::images/lens_drag_drop_2.png[Lens drag and drop focus state]
 
 . Complete the following actions:
 
-* To start dragging an item, press Space bar.
+* To select a field, press Space bar.
 
-* To select where you want to drop the item, use the Left and Right arrows.
+* To select where you want to drop the field, use the Left and Right arrows.
 
-* To reorder the fields in the group, use Up and Down arrows.
+* To reorder the fields on the layer pane, use the Up and Down arrows.
 
-* To duplicate an operation, use the Left and Right arrows to select the `Drop a field or click to add` in the same group.
+* To duplicate an action, use the Left and Right arrows, then select the *Drop a field or click to add* field you want to use.
 +
 [role="screenshot"]
 image::images/lens_drag_drop_3.gif[Using drag and drop to reorder]
 
-. Press Space bar to confirm, or to cancel, press Esc.
+. To confirm the action, press Space bar. To cancel, press Esc.
 
 [float]
-[[lens-formulas]]
-==== Use formulas to perform math
+[[configure-the-visualization-components]]
+==== Configure the visualization components
 
-Formulas let you perform math on aggregated data in Lens by typing
-math and quick functions. To access formulas,
-click the *Formula* tab in the dimension editor. Access the complete
-reference for formulas from the help menu.
+Each visualiztion type comes with a set of components that you can configure, such as data labels, legend, axes, and more.
 
-The most common formulas are dividing two values to produce a percent.
-To display accurately, set *Value format* to *Percent*.
+For example, to add data labels to bar and horizontal bar charts, use the *Values* menu.
 
-Filter ratio::
+[role="screenshot"]
+image::images/lens_value_labels_xychart_toggle.png[Lens Bar chart value labels menu]
 
-Use `kql=''` to filter one set of documents and compare it to other documents within the same grouping.
-For example, to see how the error rate changes over time:
-+
-```
-count(kql='response.status_code > 400') / count()
-```
+To add data labels to pie charts, donut charts, or treemaps, use the *Labels* menu.
 
-Week over week:: Use `shift='1w'` to get the value of each grouping from
-the previous week. Time shift should not be used with the *Top values* function.
-+
-```
-percentile(system.network.in.bytes, percentile=99) /
-percentile(system.network.in.bytes, percentile=99, shift='1w')
-```
+[role="screenshot"]
+image::images/lens_value_labels_partition_toggle.png[Lens Pie chart value labels menu]
 
-Percent of total:: Formulas can calculate `overall_sum` for all the groupings,
-which lets you convert each grouping into a percent of total:
-+
-```
-sum(products.base_price) / overall_sum(sum(products.base_price))
-```
+[float]
+[[filter-the-data]]
+==== Filter the data
+
+Apply filters to visualizations directly from the values in the legend. Only *Bar*, *Line and area*, and *Proportion* visualizations support legend filters.
+
+. In the legend, click the field.
+
+. Choose one of the following options:
+
+* *Filter for value* &mdash; Applies a filter that displays only the field data in the visualization.
+
+* *Filter out value* &mdash; Applies a filter that removes the field data from the visualization.
 
 [float]
 [[lens-faq]]
 ==== Frequently asked questions
 
-For the answers to common *Lens* questions, review the following. 
+For answers to common *Lens* questions, review the following. 
 
-[float]
-[[kql-]]
-===== When should I use the top filter bar, filters function, or "Filter by"?
+[discrete]
+[[kql]]
+.*When should I use KQL filters, the Filters function, or the Filter by option?*
+[%collapsible]
+====
+Use the <<semi-structured-search, KQL *Search*>> field to focus on a known set of data for the entire visualization. You can combine KQL filters with other filters using AND logic.
 
-Using the top <<semi-structured-search>> bar is best when you want to focus on a known set of
-data for all the visualization results. These top level filters are combined with other filters
-using AND logic.
+Use the *Filters* function to apply:
 
-Use the *Filters* function in the following scenarios:
+* More than one KQL filter.
 
-* When you want to apply more than one KQL filter to the visualization.
+* The KQL filter to a single layer, which allows you to visualize filtered and unfiltered data.
 
-* When you want to apply the KQL filter to a single layer, which allows you to visualize filtered and unfiltered data.
+Use the *Filter by* advanced option to:
 
-Use the *Filter by* advanced option in the following scenarios:
+* Assign a custom color to each filter group in a bar, line, or area chart.
 
-* When you want to assign a custom color to each filter in a bar, line or area chart.
+* Build a complex table. For example, to display the failure rate and overall data.
+====
 
-* When you want to build a complex table, such as showing both failure rate and overall.
-
-[float]
+[discrete]
 [[when-should-i-normalize-the-data-by-unit-or-use-a-custom-interval]]
-===== When should I normalize the data by unit or use a custom interval?
+.*When should I normalize the data by unit or use a custom interval?*
+[%collapsible]
+====
+* *Normalize by unit* &mdash; Calculates the average for the interval. When you normalize the data by unit, the data appears less granular, but *Lens* is able to calculate the data faster. 
 
-* *Normalize by unit* &mdash; Calculates the average for the specified interval. When you normalize the data by unit, the data appears less granular, but *Lens* is able to calculate the data faster. 
-
-* *Customize time interval* &mdash; Creates a bucket for each specified interval. When you customize the time interval, you can use a large time range, but *Lens* calculates the data slower.
+* *Customize time interval* &mdash; Creates a bucket for each interval. When you customize the time interval, you can use a large time range, but *Lens* calculates the data slower.
 
 To normalize the interval: 
 
-. In the editor, click a field.
+. In the layer pane, click a field.
 
 . Click *Add advanced options > Normalize by unit*. 
 
@@ -219,166 +241,154 @@ To normalize the interval:
 
 To create a custom interval:
 
-. In the editor, click a field.
+. In the layer pane, click a field.
 
 . Select *Customize time interval*.
 
 . Change the *Minimum interval*, then click *Close*.
+====
 
-[float]
-[[can-i-show-value-labels-for-my-chart]]
-===== How do I display value labels?
-
-A subset of *Lens* visualizations support value labels.
-
-* *Bar* and *Horizontal Bar*
-+
-[role="screenshot"]
-image::images/lens_value_labels_xychart_toggle.png[Lens Bar chart value labels menu]
-
-NOTE: In bar charts, you are unable to move the label positions.
-
-* *Pie*, *Donut*, and *Treemap*
-+
-[role="screenshot"]
-image::images/lens_value_labels_partition_toggle.png[Lens Pie chart value labels menu]
-
-[float]
+[discrete]
 [[what-is-the-other-category]]
-===== What data is categorized as Other?
-
+.*What data is categorized as Other?*
+[%collapsible]
+====
 The *Other* category contains all of the documents that do not match the specified criteria or filters. 
 Use *Other* when you want to compare a value, or multiple values, to a whole.
-By default, *Group other values as "Other"* is enabled when you select the *Top values* function. 
 
-To disable *Group other values as "Other"*:
+By default, *Group other values as "Other"* is enabled when you use the *Top values* function. 
 
-. In the editor, click *Advanced*. 
+To disable *Group other values as "Other"*, click a field in the layer pane, click *Advanced*, then deselect *Group other values as "Other"*.
+====
 
-. Deselect *Group other values as "Other"*.
-
-[float]
+[discrete]
 [[how-can-i-include-documents-without-the-field-in-the-operation]]
-===== How can I include documents without the field?
+.*How do I add documents without a field?*
+[%collapsible]
+====
+By default, *Lens* retrieves only the documents from the fields. 
+For bucket aggregations, such as *Top values*, you can add documents that do not contain the fields, 
+which is helpful when you want to make a comparison to the whole documentation set.
 
-By default, *Lens* retrieves only the documents from the specified field. 
-For bucket aggregations, such as *Top values*, you can choose to include documents that do not contain the specified field, 
-which is helpful when you want to compare to the whole documentation set.
+. In the layer pane, click a field. 
 
-. In the editor, click *Advanced*.
+. Click *Advanced*, then select *Include documents without this field*.
+====
 
-. Select *Include documents without this field*.
-+
-[role="screenshot"]
-image::images/lens_bucketed_aggregation_advanced_dropdown.png[Lens Advanced options for bucketed aggregations]
+[discrete]
+[[is-it-possible-to-have-more-than-one-Y-axis-scale]]
+.*Can I add more than one y-axis scale to a visualization?*
+[%collapsible]
+====
+For each y-axis, you can select *Left* and *Right*, and configure a different scale.
+====
 
-[float]
-[[is-it-possible-to-select-color-for-specific-bar-or-point]]
-===== How do I change the color for a single data point?
+[discrete]
+[[why-is-my-value-with-the-right-color-using-value-based-coloring]]
+.*Why is my value the incorrect color when I use value-based coloring?*
+[%collapsible]
+====
+Here's a short list of few different aspects to check:
 
-*Lens* provides you with color pallettes that you can apply to the entire visualization, but you are unable to change the color for a single data point, such as a bar or line.
+* Make sure the value falls within the desired color stop value defined in the panel. Color stop values are "inclusive".
 
-[float]
+* Make sure you have the correct value precision setup. Value formatters could round the numeric values up or down.
+
+* Make sure the correct color continuity option is selected. If the number is below the first color stop value, a continuity of type `Below` or `Above and below range` is required.
+
+* The default values set by the Value type are based on the current data range displayed in the data table.
+
+** If a custom `Number` configuration is used, check that the color stop values are covering the current data range.
+
+** If a `Percent` configuration is used, and the data range changes, the colors displayed are affected.
+====
+
+[discrete]
 [[can-i-sort-by-multiple-columns]]
-===== How do I sort by multiple columns?
-
-Multiple column sorting is unsupported in *Lens*, but is supported in *Discover*. For information on how to sort multiple columns in *Discover*, 
+.*How do I sort by multiple columns?*
+[%collapsible]
+====
+Multiple column sorting is unsupported, but is supported in *Discover*. For information on how to sort multiple columns in *Discover*, 
 refer to <<explore-fields-in-your-data,Explore the fields in your data>>.
-
-[float]
-[[is-it-possible-to-sort-dimensions-in-a-chart]]
-===== How do I sort the dimensions in a chart?
-
-Sorting dimensions in visualizations is unsupported in *Lens*.
-
-You can sort the dimensions for a single column in data tables: click the column header, then select the sorting criteria you want to use.
-If you use the dimension as `Columns`, then all the columns that belong to the same dimension are sorted in the table.
-
-[float]
-[[is-it-possible-to-use-saved-serches-in-lens]]
-===== How do I visualize saved searches?
-
-Visualizing saved searches in unsupported in *Lens*.
-
-[float]
-[[is-it-possible-to-decrease-or-increase-the-number-of-suggestions]]
-===== How do I change the number of suggestions?
-
-Configuring the *Suggestions* that *Lens* automatically populates is unsupported.
-
-[float]
-[[is-it-possible-to-use-different-indexpatterns-in-lens]]
-===== Can I visualize multiple index patterns in a single visualization?
-
-You can create *Bar*, *Line* and *Area* charts from multiple index patterns.
-
-Each *Layer* in a visualization is associated with an index pattern and mutiple *Layers* can be combined together within the same visualization. Each *Layer* also has a chart switcher button in order to select the best type of visualization for the specific dataset.
-You can also change the index pattern for a single *Layer*.
+====
 
 [float]
 [[why-my-field-is-missing-from-the-fields-list]]
-===== Why is my field missing from the fields list?
-
+.*Why is my field missing from the fields list?*
+[%collapsible]
+====
 Fields do not appear in the *Available fields* in the following scenarios:
+
 * The field is a full-text field.
 * The field is a `geo_point` field
 * The field is a `flattened` field.
 * The field is a `object` field.
 
 Verify if the field appears in the *Empty fields* list. *Lens* uses heuristics to determine if the fields contain values. For sparse data sets, the heuristics are less precise.
+====
 
 [float]
 [[how-to-handle-gaps-in-time-series-visualizations]]
-===== How do I handle gaps in time series visualizations?
+.*What do I do with gaps in time series visualizations?*
+[%collapsible]
+====
+When you create *Area* and *Line* charts with sparse time series data, open *Visual options* in the editor toolbar, then select a *Missing values* option.
+====
 
-*Lens* provides a set of features to handle missing values for *Area* and *Line* charts, which is useful for sparse data in time series data.
-
-To select a different way to represent missing values, open the *Visual options* menu, then select how to handle missing values. The default is to hide the missing values.
-+
-[role="screenshot"]
-image::images/lens_missing_values_strategy.png[Lens Missing values strategies menu]
-
-[float]
+[discrete]
 [[is-it-possible-to-change-the-scale-of-Y-axis]]
-===== Is it possible to statically define the scale of the y-axis in a visualization?
+.*Can I statically define the y-axis scale?*
+[%collapsible]
+====
+You can set the scale, or _bounds_, for area, bar, and line charts. You can configure the bounds for all functions, except *Percentile*. Logarithmic scales are unsupported.
 
-Yes, you can set the bounds on bar, line and area chart types in Lens, unless using percentage mode. Bar
-and area charts must have 0 in the bounds. Logarithmic scales are unsupported in *Lens*.
-To set the y-axis bounds, click the icon representing the axis you want to customize.
+To configure the bounds, use the menus in the editor toolbar. Bar and area charts required 0 in the scale between *Lower bound* and *Upper bound*. 
+====
 
-[float]
-[[is-it-possible-to-have-pagination-for-datatable]]
-===== Is it possible to have pagination in a data table?
-
-Pagination in a data table is unsupported in *Lens*. However, the <<types-of-visualizations,aggregation-based data table>> supports pagination.
-
-[float]
-[[is-it-possible-to-have-more-than-one-Y-axis-scale]]
-===== Is it possible to have more than one y-axis scale in visualizations?
-
-*Lens* lets you pick, for each Y dimension, up to two distinct axis: *left* and *right*. Each axis can have a different scale.
-
-[float]
-[[why-is-my-value-with-the-right-color-using-value-based-coloring]]
-===== Why is my value with the incorrect color when using value-based coloring?
-
-There could be various reasons for a specific value in the table to have a different color than expected.
-
-Here's a short list of few different aspects to check:
-* Make sure the value falls within the desired color stop value defined in the panel. Color stop values are "inclusive".
-
-* Make sure you have the right value precision setup: value formatters could round the numeric values up or down.
-
-* Make sure the right color continuity option is selected: if the number is below the first color stop value, a continuity of type `Below` or `Above and below range` is required.
-
-* The default values set by the Value type are based on the current data range displayed on the data table.
-
-** If a custom `Number` configuration is used, check that the color stop values are covering the current data range.
-
-** If a `Percent` configuration is used, and the data range changes, the colors displayed are affected.
-
-[float]
+[discrete]
 [[is-it-possible-to-show-icons-in-datatable]]
-===== Is it possible to display icons in data tables?
-
+.*Is it possible to display icons in data tables?*
+[%collapsible]
+====
 You can display icons with <<managing-index-patterns, field formatter>> in data tables.
+====
+
+[discrete]
+[[is-it-possible-to-use-saved-serches-in-lens]]
+.*How do I visualize saved searches?*
+[%collapsible]
+====
+Visualizing saved searches in unsupported.
+====
+
+[discrete]
+[[is-it-possible-to-decrease-or-increase-the-number-of-suggestions]]
+.*How do I change the number of suggestions?*
+[%collapsible]
+====
+Configuring the *Suggestions* is unsupported.
+====
+
+[discrete]
+[[is-it-possible-to-have-pagination-for-datatable]]
+.*Is it possible to have pagination in a data table?*
+[%collapsible]
+====
+Pagination in a data table is unsupported. To use pagination in data tables, create an <<types-of-visualizations,aggregation-based data table>>.
+====
+
+[discrete]
+[[is-it-possible-to-select-color-for-specific-bar-or-point]]
+.*How do I change the color for a single data point?*
+[%collapsible]
+====
+Specifying the color for a single data point, such as a single bar or line, is unsupported.
+====
+
+//[discrete]
+//[[when-do-i-use-runtime-fields-vs-formula]]
+//.*When do I use runtime fields vs. formula?*
+//[%collapsible]
+//====
+//
+//====

docs/user/dashboard/timelion.asciidoc

@@ -4,6 +4,15 @@
 To use *Timelion*, you define a graph by chaining functions together, using the *Timelion*-specific syntax. 
 The syntax enables some features that classical point series charts don't offer, such as pulling data from different indices or data sources into one graph.
 
+*Timelion* is driven by a simple expression language that you use to:
+
+* Retrieve time series data from one or more indices
+* Perform math across two or more time series
+* Visualize the results
+
+[role="screenshot"]
+image:dashboard/images/timelion.png[Timelion]
+
 deprecated::[7.0.0,"*Timelion* is still supported. The *Timelion app* is deprecated in 7.0, replaced by dashboard features. In 7.16 and later, the *Timelion app* is removed from {kib}. To prepare for the removal of *Timelion app*, you must migrate *Timelion app* worksheets to a dashboard. For information on how to migrate *Timelion app* worksheets, refer to the link:https://www.elastic.co/guide/en/kibana/7.10/release-notes-7.10.0.html#deprecation-v7.10.0[7.10.0 Release Notes]."]
 
 [float]

docs/user/dashboard/tsvb.asciidoc

@@ -1,18 +1,25 @@
 [[tsvb]]
 === TSVB
 
-*TSVB* enables you to visualize the data from multiple data series, supports <<aggregation-reference, 
-most {es} metric aggregations>>, multiple visualization types, custom functions, and some math. 
-To create *TSVB* visualization panels, your data must have a time field. 
+*TSVB* is a set of visualization types that you configure and display on dashboards.
+
+With *TSVB*, you can:
+
+* Combine an infinite number of <<aggregation-reference,aggregations>> to display your data.
+* Annotate time series data with timestamped events from an {es} index.
+* View the data in several types of visualizations, including charts, data tables, and markdown panels.
+* Display multiple <<index-patterns, index patterns>> in each visualization.
+* Use custom functions and some math on aggregations.
+* Customize the data with labels and colors.
 
 [role="screenshot"]
-image::visualize/images/tsvb-screenshot.png[TSVB overview]
+image::images/tsvb-screenshot.png[TSVB overview]
 
 [float]
 [[tsvb-required-choices]]
 ==== Open and set up TSVB
 
-Open *TSVB*, then make sure the required settings are configured.
+Open *TSVB*, then configure the required settings.
 
 . On the dashboard, click *All types*, then select *TSVB*.
 
@@ -20,7 +27,7 @@ Open *TSVB*, then make sure the required settings are configured.
 
 .. From the *Index pattern* dropdown, select the index pattern you want to visualize. 
 +
-To visualize an {es} index, open the *Index pattern select mode* menu, deselect *Use only {kib} index patterns*, then enter the {es} index.
+To visualize the data in an {es} index, open the *Index pattern selection mode* menu, deselect *Use only {kib} index patterns*, then enter the {es} index.
 
 .. From the *Time field* dropdown, select the field you want to visualize, then enter the field *Interval*.
 
@@ -28,7 +35,7 @@ To visualize an {es} index, open the *Index pattern select mode* menu, deselect
 +
 By default, *TSVB* drops the last bucket because the time filter intersects the time range of the last bucket. To view the partial data, select *No*.
 
-.. In the *Panel filter* field, enter <<kuery-query, KQL filters>> to view specific documents.
+.. To view a filtered set of documents, enter <<kuery-query, KQL filters>> in the *Panel filter* field.
 
 [float]
 [[tsvb-index-pattern-mode]]
@@ -222,4 +229,4 @@ To group with multiple fields, create runtime fields in the index pattern you ar
 [role="screenshot"]
 image::images/tsvb_group_by_multiple_fields.png[Group by multiple fields]
 
-. Create a new TSVB visualization and group by this field.
+. Create a *TSVB* visualization and group by this field.

docs/user/dashboard/tutorial-create-a-dashboard-of-lens-panels.asciidoc

@@ -13,13 +13,13 @@ image::images/lens_end_to_end_dashboard.png[Final dashboard vis]
 [[add-the-data-and-create-the-dashboard]]
 === Add the data and create the dashboard
 
-Install the sample web logs data that you'll use to create your dashboard.
+Add the sample web logs data that you'll use to create the dashboard panels.
 
-. On the {kib} *Home* page, click *Try our sample data*.
+. Go to the {kib} *Home* page, then click *Try our sample data*.
 
-. From *Sample web logs*, click *Add data*.
+. On the *Sample web logs* card, click *Add data*.
 
-Then create a new dashboard:
+Create the dashboard where you'll display the visualization panels.
 
 . Open the main menu, then click *Dashboard*.
 
@@ -33,234 +33,175 @@ Then create a new dashboard:
 
 . On the dashboard, click *Create visualization*.
 
-. Make sure the *kibana_sample_data_logs* index appears. You might need to select
-a different index pattern from the dropdown:
+. Make sure the *kibana_sample_data_logs* index appears.
 +
 [role="screenshot"]
 image::images/lens_end_to_end_1_2.png[Lens index pattern selector, width=50%]
 
-This tutorial uses `Records`, timestamp`, `bytes`, `clientip`, and `referer.keyword`.
-To see the most frequent values of a field, click the field name to view a summary.
-
-The main elements of *Lens* are named:
-
-Workspace panel:: Displays your visualization. You can drag and drop onto this area.
-Dimensions:: Each dimension is a function with extra options. Dimensions are grouped
-for each visualization type, for example the *Vertical axis* is a group that allows
-multiple dimensions. Each dimension starts empty with the label *Drop a field or click to add*.
-Functions:: There are two main types of functions: *buckets* and *metrics*, which are
-equivalent to what {es} provides.
+. To create the visualizations in this tutorial, you'll use the *Records*, *timestamp*, *bytes*, *clientip*, and *referer.keyword* fields. To see the most frequent values of a field, hover over the field name, then click *i*.
 
 [discrete]
 [[view-the-number-of-website-visitors]]
 === Create your first visualization
 
-Every time you build a visualization in *Lens*, you need to:
+Pick a field you want to analyze, such as *clientip*. If you want
+to analyze only this field, you can use the *Metric* visualization to display a big number.
+The only number function that you can use with *clientip* is *Unique count*.
+*Unique count*, also referred to as cardinality, approximates the number of unique values
+of the *clientip* field.
 
-* *Choose your visualization.* Do you know the type of visualization you'd like to use?
-If you do, select the type before dragging any fields. If you don't, you can change the
-visualization type after configuring your functions.
-
-* *Choose your field.* Do you know the dimension group you want to use the field in? If you do,
-drag and drop the field from the field list to your chosen dimension and Lens will pick a function for you.
-If you don't, drag and drop the field onto the workspace panel. Skip this step if you are
-using the *Filters* function.
-
-* *Edit and delete.* To change the function or styling options, click the dimension to open
-the configuration panel. To delete a specific dimension, close the configuration panel and click
-the delete button. To reset the entire visualization, click *Reset layer*.
-
-To put this into practice, pick a field you want to analyze, such as `clientip`. If you want
-to analyze only this field, you can use *Metric* to show a big number.
-The only number function that you can use with `clientip` is *Unique count*.
-*Unique count*, also known as cardinality, approximates the number of unique values
-of the `clientip` field.
-
-. To select the visualization type, click *Bar vertical stacked* to open the chart type dropdown, then select *Metric*.
+. To select the visualization type, open the *Chart type* dropdown, then select *Metric*.
 +
 [role="screenshot"]
 image::images/lens_end_to_end_1_2_1.png[Chart Type dropdown with Metric selected, width=50%]
 
-. From the *Available fields* list, drag and drop `clientip` to the workspace panel.
-Lens selects *Unique count* because it is the only numeric function
-that works for IP addresses. You can also drag and drop `clientip` onto
-the empty dimension for the same result.
+. From the *Available fields* list, drag *clientip* to the workspace.
 +
 [role="screenshot"]
 image::images/lens_end_to_end_1_3.png[Changed type and dropped clientip field]
++
+*Lens* selects the *Unique count* function because it is the only numeric function
+that works for IP addresses. You can also drag *clientip* to the layer pane for the same result.
 
-. In the editor, click *Unique count of clientip*.
+. In the layer pane, click *Unique count of clientip*.
 
 .. In the *Display name* field, enter `Unique visitors`.
 
 .. Click *Close*.
-+
-[role="screenshot"]
-image::images/lens_end_to_end_1_4.png[Flyout config open]
 
 . Click *Save and return*.
-
-. Customize the newly added panel:
-
-.. Drag the bottom corner of the panel until the metric takes up one quarter of the screen
-width. The row for the metric will have 4 items on it later.
-
-.. The metric visualization has its own label, so you do not need to add a panel title.
-
-. Click *Save* on the dashboard menu
-
-. In the *Title* field, enter `Logs dashboard`.
-
-. Select *Store time with dashboard* box, then click *Save*.
-
-. After the dashboard refreshes, click *Edit* again.
++
+The metric visualization has its own label, so you do not need to add a panel title.
 
 [discrete]
 [[mixed-multiaxis]]
 === View a metric over time
 
 *Lens* has two shortcuts that simplify viewing metrics over time. 
-If you drag and drop a numeric field to the workspace panel, *Lens* adds the default
-time field from the index pattern. If the *Date histogram* function is being used,
-quickly replace the time field by dragging and dropping on the workspace panel.
+If you drag a numeric field to the workspace, *Lens* adds the default
+time field from the index pattern. When you use the *Date histogram* function, you can
+replace the time field by dragging the field to the workspace.
 
-To visualize the `bytes` field over time without choosing a visualization type or function:
+To visualize the *bytes* field over time:
 
-. From the *Available fields* list, drag and drop `bytes` onto the workspace panel to have *Lens* automatically
-create a chart. *Lens* creates a bar chart with two dimensions, *timestamp* and *Median of bytes*.
+. On the dashboard, click *Create visualization*. 
 
-. *Lens* automatically chooses a date interval. To zoom in on the data you want to view,
-click and drag your cursor across the bars. 
+. From the *Available fields* list, drag *bytes* to the workspace. 
++
+*Lens* creates a bar chart with the *timestamp* and *Median of bytes* fields, and automatically chooses a date interval. 
 
+. To zoom in on the data you want to view, click and drag your cursor across the bars. 
++
 [role="screenshot"]
 image::images/lens_end_to_end_3_1_1.gif[Zoom in on the data]
 
-To emphasize the change in *Median of bytes* over time, use a line chart.
-To change the visualization type, use one of the following ways:
+To emphasize the change in *Median of bytes* over time, change to a line chart with one of the following options:
 
 * From the *Suggestions*, click the line chart.
-* Click *Bar vertical stacked*, then select *Line*.
-* Click the chart type icon above *Horizontal axis*, then click the line icon.
+* Open the *Chart type* dropdown in the editor toolbar, then select *Line*.
+* Open the *Chart type* menu in the layer pane, then click the line chart.
 
-Most users use the automatic time interval. You can increase and decrease
-the minimum interval that *Lens* uses, but you cannot decrease the interval
-below the {kib} advanced settings.  To set the minimum time interval:
+You can increase and decrease the minimum interval that *Lens* uses, but you are unable to decrease the interval
+below the <<advanced-options,*Advanced Settings*>>. 
 
-. In the editor, click *timestamp*.
+To set the minimum time interval:
 
-. Click *How it works* to learn about the *Lens* minimum interval
+. In the layer pane, click *timestamp*.
 
 . Select *Customize time interval*.
 
-. Increase the *Minimum interval* to `1 days`, then click *Close*.
-+
-[role="screenshot"]
-image::images/lens_end_to_end_3_1.png[Customize time interval]
+. Change the *Minimum interval* to *1 days*, then click *Close*.
 
-To save space on the dashboard, so to save space, hide the vertical and horizontal
-axis labels.
+To save space on the dashboard, hide the vertical and horizontal axis labels.
 
 . Open the *Left axis* menu, then deselect *Show*.
 +
 [role="screenshot"]
-image::images/lens_end_to_end_4_3.png[Turn off axis name]
+image::images/lens_end_to_end_4_3.png[Turn off axis label]
 
 . Open the *Bottom axis* menu, then deselect *Show*.
 
 . Click *Save and return*
 
-. On the dashboard, move the panel so that it is in the same row as the *Metric* visualization panel. The two should
-take up half the screen width.
+Add a panel title to explain the panel, which is necessary because you removed the axis labels.
 
-. Add a panel title to explain the panel, which is necessary because you removed the axis labels.
+.. Open the panel menu, then select *Edit panel title*.
 
-.. Open the panel menu and choose *Edit panel title*.
-
-.. In the *Title* field, enter `Median of bytes`, then click *Save*.
-
-. In the toolbar, click *Save*.
+.. In the *Panel title* field, enter `Median of bytes`, then click *Save*.
 
 [discrete]
 [[view-the-distribution-of-visitors-by-operating-system]]
 === View the top values of a field
 
-The *Top values* function ranks the unique values of a field by another dimension.
-The values are the most frequent when ranked by a *Count* dimension.
-The values are the largest when ranked by a *Sum* dimension.
+The *Top values* function ranks the unique values of a field by another function.
+The values are the most frequent when ranked by a *Count* function, and the largest when ranked by the *Sum* function.
 
-When you drag and drop a text or IP address field onto the workspace panel,
-*Lens* adds a *Top values* function ranked by *Count of records* to show the most frequent values.
-
-For this tutorial, you have picked a field and function, but not a visualization type.
-You want to see the most frequent values of `request.keyword` on your website, ranked by the unique visitors.
-This means that you want to use *Top values of request.keyword* ranked by *Unique count of clientip*, instead of
+Create a visualization that displays the most frequent values of *request.keyword* on your website, ranked by the unique visitors.
+To create the visualization, use *Top values of request.keyword* ranked by *Unique count of clientip*, instead of
 being ranked by *Count of records*.
 
-. From the *Available fields* list, drag and drop `clientip` onto the *Vertical axis*.
-*Lens* chooses the function for you when you drop onto a dimension, which is *Unique count* here.
-Do not drop the field into the main workspace because `clientip` will be added to the wrong axis.
+. On the dashboard, click *Create visualization*. 
 
-. Drag and drop `request.keyword` to the main workspace. *Lens* adds *Top values of request.keyword*
-to the *Horizontal axis*.
+. From the *Available fields* list, drag *clientip* to the *Vertical axis* field in the layer pane. 
++
+*Lens* automatically chooses the *Unique count* function. If you drag *clientip* to the workspace, *Lens* adds the field to the incorrect axis.
++
+When you drag a text or IP address field to the workspace,
+*Lens* adds the *Top values* function ranked by *Count of records* to show the most frequent values.
+
+. Drag *request.keyword* to the workspace.
 +
 [role="screenshot"]
 image::images/lens_end_to_end_2_1_1.png[Vertical bar chart with top values of request.keyword by most unique visitors]
++
+*Lens* adds *Top values of request.keyword* to the *Horizontal axis*.
 
-This chart is hard to read because the `request.keyword` field contains long text. You could try
-using one of the *Suggestions*, but the suggestions also have issues with long text. Instead, switch
-to the *Table* visualization.
+The chart is hard to read because the *request.keyword* field contains long text. You could try
+using one of the *Suggestions*, but the suggestions also have issues with long text. Instead, create a *Table* visualization.
 
-Click *Bar vertical stacked*, then select *Table*.
+. Open the *Chart type* dropdown, then select *Table*.
 +
 [role="screenshot"]
 image::images/lens_end_to_end_2_1_2.png[Table with top values of request.keyword by most unique visitors]
 
-Next, customize the table.
+. In the layer pane, click *Top values of request.keyword*.
 
-. Click the *Top values of request.keyword* dimension.
+.. In the *Number of values* field, enter `10`.
 
-.. Increase the *Number of values*. The maximum allowed value is 1000.
+.. In the *Display name* field, enter `Page URL`.
 
-.. In the *Display name* field, enter `Page URL`, then click *Close*.
+.. Click *Close*.
 
 . Click *Save and return*.
-
-. Move the table panel so that it has its own row, but do not change the size.
-
-NOTE: You do not need a panel title because the table columns are clearly labeled.
++
+The table does not need a panel title because the columns are clearly labeled.
 
 [discrete]
 [[custom-ranges]]
 === Compare a subset of documents to all documents
 
-To compare a field on subset of documents to all documents, you need to select two or more sets of documents that add up to 100%.
-For this example, we are comparing documents where the `bytes` field is under 10 Kb to documents where `bytes` is over 10 Kb,
-which are two sets that do not overlap.
+Create a proportional visualization that helps you to determine if your users transfer more bytes from documents under 10KB versus documents over 10 Kb.
 
-Use *Intervals* to select documents based on the number range of a field. Use *Filters* when your criteria
-is not numeric, or when your query needs multiple clauses.
+. On the dashboard, click *Create visualization*. 
 
-Use a proportion chart to display the values as a percentage of the sum of all values. Lens has 5 types of proportion charts:
-pie, donut, treemap, percentage bar and percentage area.
+. From the *Available fields* list, drag *bytes* to the *Vertical axis* field in the layer pane.
 
-To determine if your users transfer more `bytes` from small files versus large files,
-configure dimensions with *Intervals* and *Sum*, then switch to a pie chart to display as a percentage:
+. Click *Median of bytes*, click the *Sum* function, then click *Close*.
 
-. From the *Available fields* list, drag and drop `bytes` to *Vertical axis* in the editor.
+. From the *Available fields* list, drag *bytes* to the *Break down by* field in the layer pane.
 
-. Click *Median of bytes*, select *Sum*, then click *Close*.
+Use the *Intervals* function to select documents based on the number range of a field. 
+If the ranges were non numeric, or if the query required multiple clauses, you could use the *Filters* function.
 
-. From the *Available fields* list, drag and drop `bytes` to *Break down by* in the editor, then specify the file size ranges.
+. To specify the file size ranges, click *bytes* in the layer pane.
 
-.. In the editor, click *bytes*.
-
-.. Click *Create custom ranges*, enter the following, then press Return:
+. Click *Create custom ranges*, enter the following, then press Return:
 
 * *Ranges* &mdash; `0` -> `10240`
 
 * *Label* &mdash; `Below 10KB`
 
-.. Click *Add range*, enter the following, then press Return:
+. Click *Add range*, enter the following, then press Return:
 
 * *Ranges* &mdash; `10240` -> `+∞`
 
@@ -269,53 +210,59 @@ configure dimensions with *Intervals* and *Sum*, then switch to a pie chart to d
 [role="screenshot"]
 image::images/lens_end_to_end_6_1.png[Custom ranges configuration]
 
-.. From the *Value format* dropdown, select *Bytes (1024)*, then click *Close*.
+. From the *Value format* dropdown, select *Bytes (1024)*, then click *Close*.
 
-. From the *Chart Type* dropdown, select *Pie*.
+To display the values as a percentage of the sum of all values, use the *Pie* chart. 
+
+. Open the *Chart Type* dropdown, then select *Pie*.
 
 . Click *Save and return*.
 
+. Add a panel title.
+
+.. Open the panel menu, then select *Edit panel title*.
+
+.. In the *Panel title* field, enter `Sum of bytes from large requests`, then click *Save*.
+
 [discrete]
 [[histogram]]
-=== View a the distribution of a number field
+=== View the distribution of a number field
 
-Knowing the distribution of a number helps to find patterns. For example, you could
-look at the website traffic per hour to find the best time to do routine maintenance.
-Use *Intervals* to see an evenly spaced distribution of a number field.
+Knowing the distribution of a number helps you find patterns. For example, you can analyze the website traffic per hour to find the best time to do routine maintenance.
 
-. From the *Available fields* list, drag and drop `bytes` to *Vertical axis* in the editor.
+. On the dashboard, click *Create visualization*. 
 
-. Click *Median of bytes*, then select *Sum*.
+. From the *Available fields* list, drag *bytes* to *Vertical axis* field in the layer pane.
 
-. In the *Display name* field, enter `Transferred bytes`.
+. In the layer pane, click *Median of bytes*
 
-. From the *Value format* dropdown, select `Bytes (1024)`, then click *Close*.
+.. Click the *Sum* function.
 
-. From the *Available fields* list, drag and drop *hour_of_day* to *Horizontal axis* in the editor.
+.. In the *Display name* field, enter `Transferred bytes`.
 
-. Click *hour_of_day*, and then slide the *Intervals granularity* slider until the horizontal axis displays hourly intervals.
+.. From the *Value format* dropdown, select *Bytes (1024)*, then click *Close*.
+
+. From the *Available fields* list, drag *hour_of_day* to *Horizontal axis* field in the layer pane.
+
+. In the layer pane, click *hour_of_day*, then slide the *Intervals granularity* slider until the horizontal axis displays hourly intervals.
 +
-[role="screenshot"]
-image::images/lens_end_to_end_5_2.png[Create custom ranges]
+The *Intervals* function displays an evenly spaced distribution of the field.
 
 . Click *Save and return*.
 
-. Decrease the panel size, then drag and drop it to the first row next to the `Median of bytes` panel. There
-should be four panels in a row.
-
-. You do not need a panel title because the axis labels are self-explanatory.
-
 [discrete]
 [[treemap]]
 === Create a multi-level chart
 
-*Lens* lets you use multiple functions in the data table and proportion charts. For example,
+You can use multiple functions in data tables and proportion charts. For example,
 to create a chart that breaks down the traffic sources and user geography, use *Filters* and
 *Top values*.
 
-. Click *Bar vertical stacked*, then select *Treemap*.
+. On the dashboard, click *Create visualization*. 
 
-. From the *Available fields* list, drag and drop *Records* to the *Size by* field in the editor. 
+. Open the *Chart type* dropdown, then select *Treemap*.
+
+. From the *Available fields* list, drag *Records* to the *Size by* field in the layer pane. 
 
 . In the editor, click the *Drop a field or click to add* field for *Group by*, then create a filter for each website traffic source.
 
@@ -341,31 +288,44 @@ to create a chart that breaks down the traffic sources and user geography, use *
 
 .. Click *Close*.
 
-Add the next break down by geography:
+Add a geography grouping:
 
-. From the *Available fields* list, drag and drop *geo.src* to the main workspace.
+. From the *Available fields* list, drag *geo.src* to the workspace.
 
-. To change the *Group by* order, click and drag *Top values of geo.src* so that it appears first in the editor.
+. To change the *Group by* order, drag *Top values of geo.src* so that it appears first.
 +
 [role="screenshot"]
-image::images/lens_end_to_end_7_2.png[Treemap vis]
+image::images/lens_end_to_end_7_2.png[Treemap visualization]
 
 . To view only the Facebook and Twitter data, remove the *Other* category. 
 
-.. In the editor, click *Top values of geo.src*.
+.. In the layer pane, click *Top values of geo.src*.
 
-.. From the *Advanced* dropdown, deselect *Group other values as "Other"*, then click *Close*.
-+
-[role="screenshot"]
-image::images/lens_end_to_end_7_3.png[Group other values as Other]
+.. Open the *Advanced* dropdown, deselect *Group other values as "Other"*, then click *Close*.
 
 . Click *Save and return*.
 
-. Arrange the panel so that it is in the same row as the table.
+. Add a panel title.
 
-.. Click the gear icon and choose *Edit panel title*.
+.. Open the panel menu, then select *Edit panel title*.
 
-.. Enter "Page views by location and referer" as the panel title, then click *Save*.
+.. In the *Panel title* field, enter `Page views by location and referrer`, then click *Save*.
+
+[float]
+[[arrange-the-lens-panels]]
+=== Arrange the dashboard panels
+
+Resize and move the panels so they all appear on the dashboard without scrolling.
+
+Decrease the size of the following panels, then move them to the first row:
+
+* *Unique visitors* 
+
+* *Median of bytes*
+
+* *Sum of bytes from large requests*
+
+* *hour_of_day*
 
 [discrete]
 === Save the dashboard
@@ -374,6 +334,8 @@ Now that you have a complete overview of your web server data, save the dashboar
 
 . In the toolbar, click *Save*.
 
-. On the *Save dashboard* window, enter `Web server data`, then click *Save*.
+. On the *Save dashboard* window, enter `Logs dashboard` in the *Title* field.
 
-. If this was not the first time you saved the dashboard, click *Switch to view mode*
+. Select *Store time with dashboard*.
+
+. Click *Save*.

docs/user/dashboard/vega-reference.asciidoc

@@ -363,7 +363,7 @@ results from {es}. To troubleshoot these requests, click *Inspect*, which shows
 In case your specification has more than one request, you can switch between the views using the *View* dropdown.
 
 [role="screenshot"]
-image::visualize/images/vega_tutorial_inspect_requests.png[]
+image::images/vega_tutorial_inspect_requests.png[]
 
 [float]
 [[vega-debugging]]
@@ -375,7 +375,7 @@ The runtime data is read from the
 https://vega.github.io/vega/docs/api/debugging/#scope[runtime scope].
 
 [role="screenshot"]
-image::visualize/images/vega_tutorial_inspect_data_sets.png[]
+image::images/vega_tutorial_inspect_data_sets.png[]
 
 To debug more complex specs, access to the `view` variable.  For more information, refer to
 the <<vega-browser-debugging-console, Vega browser debugging process>>.
@@ -389,7 +389,7 @@ Because of the dynamic nature of the data in {es}, it is hard to help you with
 then select *Spec*.
 
 [role="screenshot"]
-image::visualize/images/vega_tutorial_getting_help.png[]
+image::images/vega_tutorial_getting_help.png[]
 
 To copy the response, click *Copy to clipboard*. Paste the copied data to
 https://gist.github.com/[gist.github.com], possibly with a .json extension. Use the [raw] button,

docs/user/dashboard/vega.asciidoc

@@ -1,10 +1,26 @@
 [[vega]]
 === Vega
 
-*Vega* and *Vega-Lite* are both grammars for creating custom visualizations.
-They are recommended for advanced users who are comfortable writing {es} queries manually.
-*Vega-Lite* is a good starting point for users who are new to both grammars, but they are
-not compatible.
+*Vega* and *Vega-Lite* are both grammars for creating custom visualizations. They are recommended for advanced users who are comfortable writing {es} queries manually.
+*Vega-Lite* is a good starting point for users who are new to both grammars, but they are not compatible.
+
+*Vega* and *Vega-Lite* panels can display one or more data sources, including {es}, Elastic Map Service,
+URL, or static data, and support <<reference-for-kibana-extensions,{kib} extensions>> that allow you to embed the panels on your dashboard and add interactive tools.
+
+Use *Vega* or *Vega-Lite* when you want to create visualizations with:
+
+* Aggregations that use `nested` or `parent/child` mapping
+* Aggregations without an index pattern
+* Queries that use custom time filters
+* Complex calculations
+* Extracted data from _source instead of aggregations
+* Scatter charts, sankey charts, and custom maps
+* An unsupported visual theme
+
+These grammars have some limitations: they do not support tables, and can't run queries conditionally.
+
+[role="screenshot"]
+image::images/vega.png[Vega UI]
 
 Both *Vega* and *Vega-Lite* use JSON, but {kib} has made this simpler to type by integrating
 https://hjson.github.io/[HJSON]. HJSON supports the following:
@@ -213,12 +229,12 @@ To debug the warning, compare `source_0` and `data_0`.
 . From the dropdown, select *source_0*.
 +
 [role="screenshot"]
-image::visualize/images/vega_lite_tutorial_4.png[Table for data_0 with columns key, doc_count and array of time_buckets]
+image::images/vega_lite_tutorial_4.png[Table for data_0 with columns key, doc_count and array of time_buckets]
 
 . To compare to the visually encoded data, select *data_0* from the dropdown.
 +
 [role="screenshot"]
-image::visualize/images/vega_lite_tutorial_5.png[Table for data_0 where the key is NaN instead of a string]
+image::images/vega_lite_tutorial_5.png[Table for data_0 where the key is NaN instead of a string]
 +
 *key* is unable to convert because the property is category (`Men's Clothing`, `Women's Clothing`, etc.) instead of a timestamp.
 
@@ -247,7 +263,7 @@ In the *Vega-Lite* spec, add the `encoding` block:
 . From the dropdown, select *data_0*.
 +
 [role="screenshot"]
-image::visualize/images/vega_lite_tutorial_6.png[Table for data_0 showing that the column time_buckets.buckets.key is undefined]
+image::images/vega_lite_tutorial_6.png[Table for data_0 showing that the column time_buckets.buckets.key is undefined]
 
 *Vega-Lite* is unable to extract the `time_buckets.buckets` inner array.
 
@@ -271,7 +287,7 @@ In the *Vega-Lite* spec, add a `transform` block, then click *Update*:
 . From the dropdown, select *data_0*.
 +
 [role="screenshot"]
-image::visualize/images/vega_lite_tutorial_7.png[Table showing data_0 with multiple pages of results, but undefined values in the column time_buckets.buckets.key]
+image::images/vega_lite_tutorial_7.png[Table showing data_0 with multiple pages of results, but undefined values in the column time_buckets.buckets.key]
 +
 Vega-Lite displays *undefined* values because there are duplicate names. 
 
@@ -396,7 +412,7 @@ Move your cursor around the stacked area chart. The points are able to
 indicate the nearest point.
 
 [role="screenshot"]
-image::visualize/images/vega_lite_tutorial_2.png[Vega-Lite tutorial selection enabled]
+image::images/vega_lite_tutorial_2.png[Vega-Lite tutorial selection enabled]
 
 The selection is controlled by a signal. To view the signal, click *Inspect* in the toolbar.
 
@@ -649,7 +665,7 @@ Add the `key` and `doc_count` fields as the X- and Y-axis values, then click *Up
 ```
 
 [role="screenshot"]
-image::visualize/images/vega_tutorial_3.png[]
+image::images/vega_tutorial_3.png[]
 
 [float]
 ===== Add a block to the `marks` section
@@ -740,7 +756,7 @@ then update the `point` and add `cursor: { value: "pointer" }` to
 To allow users to filter based on a time range, add a drag interaction, which requires additional signals and a rectangle overlay.
 
 [role="screenshot"]
-image::visualize/images/vega_tutorial_4.png[]
+image::images/vega_tutorial_4.png[]
 
 In the *Vega* spec, add a `signal` to track the X position of the cursor:
 

docs/user/discover.asciidoc

@@ -257,8 +257,7 @@ image:images/discover-visualize.png[Discover sidebar field popover with visualiz
 +
 {kib} creates a visualization best suited for this field.
 
-. Drag `manufacturer.keyword` from the field list and drop it on
-the visualization builder pane.
+. From the *Available fields* list, drag and drop `manufacturer.keyword` onto the workspace.
 +
 [role="screenshot"]
 image:images/discover-from-visualize.png[Visualization that opens from Discover based on your data]