From d72a8f8026b606ebd9793932bbc679c5feb59d93 Mon Sep 17 00:00:00 2001
From: Lisa Cawley <lcawley@elastic.co>
Date: Fri, 19 May 2017 11:09:39 -0700
Subject: [PATCH] [DOCS] Add ML geographic functions
 (elastic/x-pack-elasticsearch#1357)

* [DOCS] Add ML geographic functions

* [DOCS] Add script_fields info to ML geo functions

* [DOCS] Remove summary count from ML geographic functions

* [DOCS] Added example title to geographic functions

* [DOCS] Remove list from ML geographic functions

Original commit: elastic/x-pack-elasticsearch@a8e495657fbbe794434f6baa572e3777707d6b58
---
 docs/en/ml/functions/geo.asciidoc | 74 ++++++++++++++++++++++++++-----
 1 file changed, 64 insertions(+), 10 deletions(-)

diff --git a/docs/en/ml/functions/geo.asciidoc b/docs/en/ml/functions/geo.asciidoc
index 7c9d8ac1f9b..bf619d9c28d 100644
--- a/docs/en/ml/functions/geo.asciidoc
+++ b/docs/en/ml/functions/geo.asciidoc
@@ -1,23 +1,77 @@
 [[ml-geo-functions]]
 === Geographic Functions
 
-The {xpackml} features include the following geographic functions:
-
-* `lat_long`
-
 The geographic functions detect anomalies in the geographic location of the
 input data.
 
-The `field_name` that you supply must be a string of the form
-`latitude,longitude`. The `latitude` and `longitude` must be in the range -180
-to 180 and represent a point on the surface of the Earth.
+The {xpackml} features include the following geographic function: `lat_long`.
 
+[float]
+[[ml-lat-long]]
+==== Lat_long
 
-////
+The `lat_long` function detects anomalies in the geographic location of the
+input data.
+
+This function supports the following properties:
+
+* `field_name` (required)
+* `by_field_name` (optional)
+* `over_field_name` (optional)
+* `partition_field_name` (optional)
+
+For more information about those properties,
+see <<ml-detectorconfig,Detector Configuration Objects>>.
+
+.Example 1: Analyzing transactions with the lat_long function
+[source,js]
+--------------------------------------------------
+{
+  "function" : "lat_long",
+  "field_name" : "transactionCoordinates",
+  "by_field_name" : "creditCardNumber"
+}
+--------------------------------------------------
+
+If you use this `lat_long` function in a detector in your job, it
+detects anomalies where the geographic location of a credit card transaction is
+unusual for a particular customer’s credit card. An anomaly might indicate fraud.
+
+IMPORTANT: The `field_name` that you supply must be a single string that contains
+two comma-separated numbers of the form `latitude,longitude`. The `latitude` and
+`longitude` must be in the range -180 to 180 and represent a point on the
+surface of the Earth.
+
+For example, JSON data might contain the following transaction coordinates:
 
 [source,js]
 --------------------------------------------------
-{ "function" : "lat_long", "fieldName" : "transactionCoordinates", "byFieldName" : "creditCardNumber" }
+{
+  "time": 1460464275,
+  "transactionCoordinates": "40.7,-74.0",
+  "creditCardNumber": "1234123412341234"
+}
 --------------------------------------------------
 
-////
+In {es}, location data is likely to be stored in `geo_point` fields. For more
+information, see {ref}/geo-point.html[Geo-point datatype]. This data type is not
+supported natively in {xpackml} features. You can, however, use Painless scripts
+in `script_fields` in your {dfeed} to transform the data into an appropriate
+format. For example, the following Painless script transforms
+`"coords": {"lat" : 41.44, "lon":90.5}` into `"lat-lon": "41.44,90.5"`:
+
+[source,js]
+--------------------------------------------------
+{
+  "script_fields": {
+    "lat-lon": {
+      "script": {
+        "inline": "doc['coords'].lat + ',' + doc['coords'].lon",
+        "lang": "painless"
+      }
+    }
+  }
+}
+--------------------------------------------------
+
+For more information about `script_fields`, see <<ml-datafeed-resource>>.