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..88d21c1b23 --- /dev/null +++ b/guide/04-feature-data-and-analysis/introduction-to-feature-analysis.ipynb @@ -0,0 +1,321 @@ +{ + "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 analysis operations help you can 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 many 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`](https://developers.arcgis.com/python/latest/api-reference/arcgis.features.analysis.html) module and other submodules of [`features`](https://developers.arcgis.com/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](https://developers.arcgis.com/python/latest/api-reference/) for that tool.\n", + "\n", + "1. [`FeatureCollection`](https://developers.arcgis.com/python/latest/api-reference/arcgis.features.toc.html#arcgis.features.FeatureCollection) - an in-memory collection of [`Feature`](https://developers.arcgis.com/python/latest/api-reference/arcgis.features.toc.html#arcgis.features.Feature) objects with rendering information.\n", + "2. [`FeatureLayer`](https://developers.arcgis.com/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`](https://developers.arcgis.com/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`](https://developers.arcgis.com/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` - hosted feature layer in the ArcGIS Organization you have authenticated into, if `output_name` is provided.\n", + "2. `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 us take a look at an example involving fetching specific data of interest, finding hot spots within that data and then seeing 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 that Feature Layer Collection." + ] + }, + { + "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 we have extracted `FeatureLayer` object from the item and proceed to run this tool by providing the desired name for the resultant layer that will be generated 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": [ + "map1 = gis.map(\"Washington, DC\")\n", + "map1.content.add(hot_spots_result)\n", + "map1.basemap.basemap = 'arcgis-dark-gray'\n", + "map1" + ] + }, + { + "cell_type": "markdown", + "id": "6f6b39e7-4980-4438-a352-97206f7a13ca", + "metadata": {}, + "source": [ + "Using the feature analysis tools is both easy and effective to analyze the data hosted in your WebGIS Organization. \n", + "\n", + "Here are a few more feature analysis guides and samples to explore this subject further:\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/)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "06a6f7fe-d401-4a5e-ad04-f4a7f643f647", + "metadata": {}, + "outputs": [], + "source": [] + } + ], + "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.12.11" + } + }, + "nbformat": 4, + "nbformat_minor": 5 +}