diff --git a/guide/04-feature-data-and-analysis/introduction-to-feature-analysis.ipynb b/guide/04-feature-data-and-analysis/introduction-to-feature-analysis.ipynb new file mode 100644 index 0000000000..7aee1100bc --- /dev/null +++ b/guide/04-feature-data-and-analysis/introduction-to-feature-analysis.ipynb @@ -0,0 +1,318 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "9b28f3b5-d82e-41bd-947d-16841b8da621", + "metadata": {}, + "source": [ + "# Introduction to Feature Analysis" + ] + }, + { + "cell_type": "markdown", + "id": "acdcf167-e51c-4d26-a1c9-e2933d3cacd3", + "metadata": {}, + "source": [ + "Feature analysis is the process of performing server-side spatial analysis operations on feature data such as points, lines or polygons. These operations can be used to find features, merge or overlay features, calculate feature statistics, or find patterns and relationships in feature data. The operation you use depends on the type of problem you are trying to solve.\n", + "\n", + "Feature analysis can help solve different types of problems. For example, you can use it to:\n", + "\n", + "* Understand where features are or where multiple features exist.\n", + "* Measure sizes, shapes, and distributions of features.\n", + "* Analyze relationships and interactions between features.\n", + "* Detect and quantify patterns and relationships between features.\n", + "* Make predictions based on existing or theoretical patterns and relationships.\n" + ] + }, + { + "cell_type": "markdown", + "id": "654be976-2d23-4004-be4a-b285a3aa59e3", + "metadata": {}, + "source": [ + "### Performing Feature Analysis using the ArcGIS API for Python" + ] + }, + { + "cell_type": "markdown", + "id": "93d93f04-1e73-4bc7-a656-1e2b8659826e", + "metadata": {}, + "source": [ + "\n", + "To perform an analysis, you can use a hosted feature layer as input for the analysis tool. The feature analysis service can access this hosted data and execute operations and store results either as a hosted feature layer or features in-memory. \n", + "\n", + "Within the context of the ArcGIS API for Python, these analysis tools can be found under the [`features.analysis`](/python/latest/api-reference/arcgis.features.analysis.html) submodule as well as other [`submodules of the _features_ module](/python/latest/api-reference/arcgis.features.toc.html#submodules). The following are valid __input formats__ for analysis tools, unless mentioned otherwise for a specific tool in the [API reference](/python/latest/api-reference/) for that tool.\n", + "\n", + "1. [`FeatureCollection`](/python/latest/api-reference/arcgis.features.toc.html#arcgis.features.FeatureCollection) - an in-memory collection of [`Feature`](python/latest/api-reference/arcgis.features.toc.html#arcgis.features.Feature) objects with rendering information.\n", + "2. [`FeatureLayer`](/python/latest/api-reference/arcgis.features.toc.html#arcgis.features.FeatureLayer) - represents an individual layer within a [feature service](https://doc.esri.com/en/arcgis-enterprise/latest/administer/what-is-a-feature-service-.html).\n", + "3. [`FeatureLayerCollection`](/python/latest/api-reference/arcgis.features.toc.html#arcgis.features.FeatureLayerCollection) - a collection of feature layers and tables, the Python API representation of a feature service.\n", + "4. [`Item`](/python/latest/api-reference/arcgis.gis.toc.html#arcgis.gis.Item) of type `FeatureCollection` or `FeatureLayerCollection` where only the first layer is used.\n", + "\n", + "\n", + "The feature analysis tools usually return results of the following __output formats__, unless mentioned otherwise for a specific tool. \n", + "\n", + "1. [`FeatureLayer`](/python/latest/api-reference/arcgis.features.toc.html#featurelayer) - hosted feature layer in the ArcGIS Organization you have authenticated into, if `output_name` is provided.\n", + "2. [`FeatureCollection`](python/latest/api-reference/arcgis.features.toc.html#featurecollection) - result can be accessed in-memory. " + ] + }, + { + "cell_type": "markdown", + "id": "5b0497c1-d1a9-4a0e-b66e-c119e5ada242", + "metadata": {}, + "source": [ + "### Types of Feature Analysis" + ] + }, + { + "cell_type": "markdown", + "id": "beef51fb-91b8-452f-8621-fa42b9e3d540", + "metadata": {}, + "source": [ + "| Category | Description | Tools |
Example
|\n", + "| --- | --- | --- | --- |\n", + "| Analyze Patterns | Identifies spatial patterns and relationships in feature data. | [`calculate_composite_index()`](https://developers.arcgis.com/python/latest/api-reference/arcgis.features.analyze_patterns.html#calculate-composite-index), [`calculate_density()`](https://developers.arcgis.com/python/latest/api-reference/arcgis.features.analyze_patterns.html#calculate-density), [`find_hot_spots()`](https://developers.arcgis.com/python/latest/api-reference/arcgis.features.analyze_patterns.html#find-hot-spots), [`find_outliers()`](https://developers.arcgis.com/python/latest/api-reference/arcgis.features.analyze_patterns.html#find-outliers), [`find_point_clusters()`](https://developers.arcgis.com/python/latest/api-reference/arcgis.features.analyze_patterns.html#find-point-clusters), [`interpolate_points()`](https://developers.arcgis.com/python/latest/api-reference/arcgis.features.analyze_patterns.html#interpolate-points) | ![find_hot_spots](https://developers.arcgis.com/documentation/static/243bc401de0de1cf52e6737592331afd/78e79/find-hot-spots.png)\n", + "| Enrich Data | Adds demographic and landscape data to input features. | [`enrich_layer()`](https://developers.arcgis.com/python/latest/api-reference/arcgis.features.enrich_data.html#enrich-layer) | ![enrich_layer](https://developers.arcgis.com/rest/services-reference/enterprise/static/68603b9692b9418591788e1a98d4b890/78e79/GUID-5B2D9742-AFD2-4054-8D05-ED6A80EDAF4D-web.png)\n", + "| Find Locations | Selects a subset of features that meet a number of different criteria you specify. | [`find_existing_locations()`](https://developers.arcgis.com/python/latest/api-reference/arcgis.features.find_locations.html#find-existing-locations), [`derive_new_locations()`](https://developers.arcgis.com/python/latest/api-reference/arcgis.features.find_locations.html#derive-new-locations), [`find_similar_locations()`](https://developers.arcgis.com/python/latest/api-reference/arcgis.features.find_locations.html#find-similar-locations), [`find_centroids()`](https://developers.arcgis.com/python/latest/api-reference/arcgis.features.find_locations.html#find-centroids), [`choose_best_facilities()`](https://developers.arcgis.com/python/latest/api-reference/arcgis.features.find_locations.html#choose-best-facilities), [`create_viewshed()`](https://developers.arcgis.com/python/latest/api-reference/arcgis.features.find_locations.html#create-viewshed), [`create_watersheds()`](https://developers.arcgis.com/python/latest/api-reference/arcgis.features.find_locations.html#create-watersheds), [`trace_downstream()`](https://developers.arcgis.com/python/latest/api-reference/arcgis.features.find_locations.html#trace-downstream) | ![find__existing_locations](https://developers.arcgis.com/documentation/static/363db76c78e819244231f95b57d23b29/78e79/find-existing-locations.png)\n", + "| Manage Data | Day-to-day management and combining geographical data prior to analysis. | [`dissolve_boundaries()`](https://developers.arcgis.com/python/latest/api-reference/arcgis.features.manage_data.html#dissolve-boundaries), [`extract_data()`](https://developers.arcgis.com/python/latest/api-reference/arcgis.features.manage_data.html#extract-data), [`merge_layers()`](https://developers.arcgis.com/python/latest/api-reference/arcgis.features.manage_data.html#merge-layers), [`overlay_layers()`](https://developers.arcgis.com/python/latest/api-reference/arcgis.features.manage_data.html#overlay-layers), [`create_route_layers()`](https://developers.arcgis.com/python/latest/api-reference/arcgis.features.manage_data.html#create-route-layers), [`generate_tessellation()`](https://developers.arcgis.com/python/latest/api-reference/arcgis.features.manage_data.html#generate-tessellation) | ![dissolve_boundaries](https://developers.arcgis.com/documentation/static/2e0b635d25bedfa43b42f88e15ce79ba/78e79/dissolve-boundaries.png)\n", + "| Summarize Data | Aggregates or summarizes feature data and creates statistics. | [`aggregate_points()`](https://developers.arcgis.com/python/latest/api-reference/arcgis.features.summarize_data.html#aggregate-points), [`join_features()`](https://developers.arcgis.com/python/latest/api-reference/arcgis.features.summarize_data.html#join-features), [`summarize_nearby()`](https://developers.arcgis.com/python/latest/api-reference/arcgis.features.summarize_data.html#summarize-nearby), [`summarize_center_and_dispersion()`](https://developers.arcgis.com/python/latest/api-reference/arcgis.features.summarize_data.html#summarize-center-and-dispersion), [`summarize_within()`](https://developers.arcgis.com/python/latest/api-reference/arcgis.features.summarize_data.html#summarize-within) | ![aggregate_points](https://developers.arcgis.com/documentation/static/1abe2c0527ed596c6c8c6dc6cd941bd0/78e79/aggregate-points.png)\n", + "| Use Proximity | Helps answer the spatial analysis question \"What is near what?\" | [`connect_origins_to_destinations()`](https://developers.arcgis.com/python/latest/api-reference/arcgis.features.use_proximity.html#connect-origins-to-destinations), [`create_buffers()`](https://developers.arcgis.com/python/latest/api-reference/arcgis.features.use_proximity.html#create-buffers), [`create_drive_time_areas()`](https://developers.arcgis.com/python/latest/api-reference/arcgis.features.use_proximity.html#create-drive-time-areas), [`find_nearest()`](https://developers.arcgis.com/python/latest/api-reference/arcgis.features.use_proximity.html#find-nearest) [`plan_routes()`](https://developers.arcgis.com/python/latest/api-reference/arcgis.features.use_proximity.html#plan-routes) | ![create_buffers](https://developers.arcgis.com/documentation/static/09327060922018b089f6e44ced616c64/78e79/create-buffers.png)" + ] + }, + { + "cell_type": "markdown", + "id": "b2c453a1-e6bc-4156-8081-7bd221d9a932", + "metadata": {}, + "source": [ + "### Example of using the tools and visualizing results" + ] + }, + { + "cell_type": "markdown", + "id": "87a28142-5985-4fd0-90a9-4e95b6df0c60", + "metadata": {}, + "source": [ + "Let's look at an example that finds specific data of interest, finding hot spots within that data, and displays the results of the analysis on a map. " + ] + }, + { + "cell_type": "code", + "execution_count": 23, + "id": "f5d8a97f-3a12-4763-a44a-fdfbbadfa496", + "metadata": {}, + "outputs": [], + "source": [ + "from arcgis.gis import GIS\n", + "from arcgis.features.analyze_patterns import find_hot_spots" + ] + }, + { + "cell_type": "code", + "execution_count": 3, + "id": "3aba3a1f-2119-4099-9d31-e02e3e572fd7", + "metadata": {}, + "outputs": [], + "source": [ + "gis = GIS(profile='your_online_profile')" + ] + }, + { + "cell_type": "markdown", + "id": "3887f075-9b9f-4e6c-b3cb-5e46041d78f0", + "metadata": {}, + "source": [ + "We access data for Crime incidents in Washington, DC for the first half of 2026 through the itemid for the hosted *feature layer item*, represented in the Python API as a [Feature Layer Collection](/python/latest/api-reference/arcgis.features.toc.html#featurelayercollection)." + ] + }, + { + "cell_type": "code", + "execution_count": 38, + "id": "e467abc0-f2c8-4a50-9d95-5edb2e6a393c", + "metadata": {}, + "outputs": [ + { + "data": { + "text/html": [ + "
\n", + "
\n", + " \n", + " \n", + " \n", + "
\n", + "\n", + "
\n", + " Crime_Incidents___2026\n", + " \n", + "

Feature Layer Collection by MMajumdar_geosaurus\n", + "
Last Modified: June 10, 2026\n", + "
0 comments, 66 views\n", + "
\n", + "
\n", + " " + ], + "text/plain": [ + "" + ] + }, + "execution_count": 38, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "input_data = gis.content.get(\"5173a6923bc140a58afcab50356c3439\")\n", + "input_data" + ] + }, + { + "cell_type": "code", + "execution_count": 22, + "id": "6f67db8c-5173-45d0-aa9a-a1a805302d57", + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "arcgis.features.layer.FeatureLayer" + ] + }, + "execution_count": 22, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "input_data_layer = input_data.layers[0]\n", + "type(input_data_layer)" + ] + }, + { + "cell_type": "markdown", + "id": "49b48d18-d9a1-47c5-9f09-d3ef7389d631", + "metadata": {}, + "source": [ + "We verify that a [`FeatureLayer`](/python/latest/api-reference/arcgis.features.toc.html#featurelayer] object was extracted from the item. Then we run this tool with a desired name for the resultant layer as the *output_name* argument. The output item will be created in our GIS Organization." + ] + }, + { + "cell_type": "code", + "execution_count": 30, + "id": "c2cc98d4-4170-4f0e-830f-5ac8c278e5d6", + "metadata": {}, + "outputs": [ + { + "data": { + "text/html": [ + "
\n", + "
\n", + " \n", + " \n", + " \n", + "
\n", + "\n", + "
\n", + " crime_incidents_dc_2026_hotspots\n", + " \n", + "

Feature Layer Collection by MMajumdar_geosaurus\n", + "
Last Modified: July 09, 2026\n", + "
0 comments, 5 views\n", + "
\n", + "
\n", + " " + ], + "text/plain": [ + "" + ] + }, + "execution_count": 30, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "output_name = \"crime_incidents_dc_2026_hotspots\"\n", + "hot_spots_result = find_hot_spots(analysis_layer = input_data_layer, output_name = output_name)\n", + "hot_spots_result" + ] + }, + { + "cell_type": "markdown", + "id": "580453cb-8860-4e99-9898-c89389f840f9", + "metadata": {}, + "source": [ + "We will now visualize these results in a map. " + ] + }, + { + "cell_type": "code", + "execution_count": 37, + "id": "b3f80c6f-471d-412b-8f27-ec783f72cdce", + "metadata": {}, + "outputs": [ + { + "data": { + "text/html": [ + "" + ], + "text/plain": [ + "" + ] + }, + "execution_count": 37, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "# Create a map centered on Washington DC\n", + "map1 = gis.map(\"Washington, DC\")\n", + "\n", + "# Add results to the map\n", + "map1.content.add(hot_spots_result)\n", + "# Set the basemap \n", + "map1.basemap.basemap = 'arcgis-dark-gray'\n", + "# Visualize\n", + "map1" + ] + }, + { + "cell_type": "markdown", + "id": "6f6b39e7-4980-4438-a352-97206f7a13ca", + "metadata": {}, + "source": [ + "Using the feature analysis tools is an effective method to analyze data hosted in your Web GIS Organization. \n", + "\n", + "To learn more, explore other feature analysis guides and samples:\n", + "\n", + "* [Analyzing patterns in feature data](https://developers.arcgis.com/python/latest/guide/analyzing-patterns-in-feature-data/)\n", + "* [Performing proximity analysis on feature data](https://developers.arcgis.com/python/latest/guide/performing-proximity-analysis-on-feature-data/)\n", + "* [Summarize feature data](https://developers.arcgis.com/python/latest/guide/summarizing-feature-data/)\n", + "* [Find downstream path from a location](https://developers.arcgis.com/python/latest/guide/discovering-suitable-locations-in-feature-data/)\n", + "\n", + "And a few samples:\n", + "* [Designate bike routes for commuting professionals](https://developers.arcgis.com/python/latest/samples/designate-bike-routes-for-commuting-professionals/)\n", + "* [Locating a new retirement community](https://developers.arcgis.com/python/latest/samples/locating-a-new-retirement-community/)\n", + "* [Drive time analysis for opioid epidemic](https://developers.arcgis.com/python/latest/samples/drive-time-analysis-for-opioid-epidemic/)" + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3 (ipykernel)", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.13.15" + } + }, + "nbformat": 4, + "nbformat_minor": 5 +}