Visualizar dados de análise geoespacial usando um notebook do Colab

Criar um notebook do Colab

Este tutorial cria um notebook do Colab para visualizar dados de análise geoespacial. Para abrir uma versão pré-criada do notebook no Colab, no Colab Enterprise ou no BigQuery Studio, clique nos links na parte de cima da versão do tutorial no GitHub: Visualização geoespacial do BigQuery no Colab.

1. Abra o Colab.

   Abrir o Colab

2. Na caixa de diálogo Abrir notebook, clique em Novo notebook.

3. Clique em Untitled0.ipynb e mude o nome do notebook para bigquery-geo.ipynb.

4. Selecione Arquivo > Salvar.

Autenticar com Google Cloud e o Google Maps

Neste tutorial, consultamos conjuntos de dados do BigQuery e usamos a API JavaScript do Google Maps. Para usar esses recursos, autentique o tempo de execução do Colab com Google Cloud e a API Maps.

Autenticar com Google Cloud

1. Para inserir uma célula de código, clique em add Código.

2. Para autenticar com seu projeto, insira o seguinte código:

   # REQUIRED: Authenticate with your project.
   GCP_PROJECT_ID = "PROJECT_ID"  #@param {type:"string"}
   
   from google.colab import auth
   from google.colab import userdata
   
   auth.authenticate_user(project_id=GCP_PROJECT_ID)
   
   # Set GMP_API_KEY to none
   GMP_API_KEY = None

   Substitua PROJECT_ID pela ID do seu projeto.

3. Clique em play_circle_filled Executar célula.

4. Quando solicitado, clique em Permitir para dar acesso às suas credenciais ao Colab, se você concordar.

5. Na página Fazer login com o Google, escolha sua conta.

6. Na página Fazer login no código do notebook criado por terceiros, clique em Continuar.

7. Em Selecione o que o código do notebook criado por terceiros pode acessar, clique em Selecionar tudo e em Continuar.

   Depois de concluir o fluxo de autorização, nenhuma saída será gerada no notebook do Colab. A marca de seleção ao lado da célula indica que o código foi executado corretamente.

Opcional: autenticar com o Google Maps

Se você usar a Plataforma Google Maps como provedor de mapas básicos, será necessário fornecer uma chave de API da Plataforma Google Maps. O notebook recupera a chave dos seus secrets do Colab.

Esta etapa só é necessária se você estiver usando a API Maps. Se você não se autenticar com a Plataforma Google Maps, o pydeck vai usar o mapa carto.

1. Siga as instruções na página Usar chaves de API da documentação do Google Maps para gerar sua chave de API Google Maps.

2. Mude para o bloco do Colab e clique em vpn_key Secrets.

3. Clique em Adicionar novo secret.

4. Em Nome, insira GMP_API_KEY.

5. Em Valor, insira o valor da chave de API Maps que você gerou anteriormente.

6. Feche o painel Secrets.

7. Para inserir uma célula de código, clique em add Código.

8. Para autenticar com a API Maps, insira o seguinte código:

   # Authenticate with the Google Maps JavaScript API.
   GMP_API_SECRET_KEY_NAME = "GMP_API_KEY" #@param {type:"string"}
   
   if GMP_API_SECRET_KEY_NAME:
     GMP_API_KEY = userdata.get(GMP_API_SECRET_KEY_NAME) if GMP_API_SECRET_KEY_NAME else None
   else:
     GMP_API_KEY = None

9. Quando solicitado, clique em Conceder acesso para dar ao notebook acesso à sua chave, se você concordar.

10. Clique em play_circle_filled Executar célula.

    Depois de concluir o fluxo de autorização, nenhuma saída será gerada no notebook do Colab. A marca de seleção ao lado da célula indica que o código foi executado corretamente.

Instalar pacotes Python e importar bibliotecas de ciência de dados

Além dos módulos Python colabtools (google.colab), este tutorial usa vários outros pacotes Python e bibliotecas de ciência de dados.

Nesta seção, você vai instalar os pacotes pydeck e h3. O pydeck oferece renderização espacial em grande escala no Python, com tecnologia deck.gl. O h3-py oferece o sistema de indexação geoespacial hierárquica hexagonal H3 da Uber em Python.

Em seguida, importe as bibliotecas h3 e pydeck e as seguintes bibliotecas geoespaciais do Python:

• geopandas para estender os tipos de dados usados por pandas e permitir operações espaciais em tipos geométricos.
• shapely para manipulação e análise de objetos geométricos planares individuais.
• branca para gerar mapas de cores HTML e JavaScript.
• geemap.deck para visualização com pydeck e earthengine-api.

Depois de importar as bibliotecas, ative as tabelas interativas para DataFrames pandas no Colab.

Instale os pacotes pydeck e h3.

1. Para inserir uma célula de código, clique em add Código.

2. Para instalar os pacotes pydeck e h3, insira o seguinte código:

   # Install pydeck and h3.
   !pip install pydeck>=0.9 h3>=4.2

3. Clique em play_circle_filled Executar célula.

   Depois de concluir a instalação, nenhuma saída será gerada no seu bloco de notas do Colab. A marca de seleção ao lado da célula indica que o código foi executado corretamente.

Importar as bibliotecas do Python

1. Para inserir uma célula de código, clique em add Código.

2. Para importar as bibliotecas do Python, insira o seguinte código:

   # Import data science libraries.
   import branca
   import geemap.deck as gmdk
   import h3
   import pydeck as pdk
   import geopandas as gpd
   import shapely

3. Clique em play_circle_filled Executar célula.

   Depois de executar o código, nenhuma saída será gerada no notebook do Colab. A marca de seleção ao lado da célula indica que o código foi executado com sucesso.

Ativar tabelas interativas para DataFrames pandas

1. Para inserir uma célula de código, clique em add Código.

2. Para ativar os DataFrames do pandas, insira o seguinte código:

   # Enable displaying pandas data frames as interactive tables by default.
   from google.colab import data_table
   data_table.enable_dataframe_formatter()

3. Clique em play_circle_filled Executar célula.

   Depois de executar o código, nenhuma saída será gerada no notebook do Colab. A marca de seleção ao lado da célula indica que o código foi executado com sucesso.

Criar uma rotina compartilhada

Nesta seção, você vai criar uma rotina compartilhada que renderiza camadas em um mapa de base.

1. Para inserir uma célula de código, clique em add Código.

2. Para criar uma rotina compartilhada para renderizar camadas em um mapa, insira o seguinte código:

   # Set Google Maps as the base map provider.
   MAP_PROVIDER_GOOGLE = pdk.bindings.base_map_provider.BaseMapProvider.GOOGLE_MAPS.value
   
   # Shared routine for rendering layers on a map using geemap.deck.
   def display_pydeck_map(layers, view_state, **kwargs):
     deck_kwargs = kwargs.copy()
   
     # Use Google Maps as the base map only if the API key is provided.
     if GMP_API_KEY:
       deck_kwargs.update({
         "map_provider": MAP_PROVIDER_GOOGLE,
         "map_style": pdk.bindings.map_styles.GOOGLE_ROAD,
         "api_keys": {MAP_PROVIDER_GOOGLE: GMP_API_KEY},
       })
   
     m = gmdk.Map(initial_view_state=view_state, ee_initialize=False, **deck_kwargs)
   
     for layer in layers:
       m.add_layer(layer)
     return m

3. Clique em play_circle_filled Executar célula.

   Depois de executar o código, nenhuma saída será gerada no notebook do Colab. A marca de seleção ao lado da célula indica que o código foi executado com sucesso.

Criar um gráfico de dispersão

Nesta seção, você cria um diagrama de dispersão de todas as estações aluguel de bicicletas no conjunto de dados público do Ford GoBike Share de São Francisco recuperando dados da tabela bigquery-public-data.san_francisco_bikeshare.bikeshare_station_info. O gráfico de dispersão é criado usando uma camada e uma camada de gráfico de dispersão do framework deck.gl.

Os gráficos de dispersão são úteis quando você precisa analisar um subconjunto de pontos individuais (também conhecido como verificação pontual).

O exemplo a seguir demonstra como usar uma camada e uma camada de dispersão para renderizar pontos individuais como círculos.

1. Para inserir uma célula de código, clique em add Código.

2. Para consultar o conjunto de dados público do San Francisco Ford GoBike Share, insira o código a seguir. Este código usa a função mágica %%bigquery para executar a consulta e retornar os resultados em um DataFrame:

   # Query the station ID, station name, station short name, and station
   # geometry from the bike share dataset.
   # NOTE: In this tutorial, the denormalized 'lat' and 'lon' columns are
   # ignored. They are decomposed components of the geometry.
   %%bigquery gdf_sf_bikestations --project {GCP_PROJECT_ID} --use_geodataframe station_geom
   
   SELECT
     station_id,
     name,
     short_name,
     station_geom
   FROM
     `bigquery-public-data.san_francisco_bikeshare.bikeshare_station_info`

3. Clique em play_circle_filled Executar célula.

   O resultado será assim:

   Job ID 12345-1234-5678-1234-123456789 successfully executed: 100%

4. Para inserir uma célula de código, clique em add Código.

5. Para receber um resumo do DataFrame, incluindo colunas e tipos de dados, insira o seguinte código:

   # Get a summary of the DataFrame
   gdf_sf_bikestations.info()

6. Clique em play_circle_filled Executar célula.

   A saída será semelhante a esta:

   <class 'geopandas.geodataframe.GeoDataFrame'>
   RangeIndex: 472 entries, 0 to 471
   Data columns (total 4 columns):
   #   Column        Non-Null Count  Dtype
   ---  ------        --------------  -----
   0   station_id    472 non-null    object
   1   name          472 non-null    object
   2   short_name    472 non-null    object
   3   station_geom  472 non-null    geometry
   dtypes: geometry(1), object(3)
   memory usage: 14.9+ KB
   

7. Para inserir uma célula de código, clique em add Código.

8. Para visualizar as cinco primeiras linhas do DataFrame, insira o seguinte código:

   # Preview the first five rows
   gdf_sf_bikestations.head()

9. Clique em play_circle_filled Executar célula.

   O resultado será assim:

   

Para renderizar os pontos, extraia a longitude e a latitude como coordenadas x e y da coluna station_geom no conjunto de dados de aluguel de bicicletas.

Como gdf_sf_bikestations é um geopandas.GeoDataFrame, as coordenadas são acessadas diretamente da coluna de geometria station_geom. É possível recuperar a longitude usando o atributo .x da coluna e a latitude usando o atributo .y. Em seguida, armazene-os em novas colunas de longitude e latitude.

1. Para inserir uma célula de código, clique em add Código.

2. Para extrair os valores de longitude e latitude da coluna station_geom, insira o seguinte código:

   # Extract the longitude (x) and latitude (y) from station_geom.
   gdf_sf_bikestations["longitude"] = gdf_sf_bikestations["station_geom"].x
   gdf_sf_bikestations["latitude"] = gdf_sf_bikestations["station_geom"].y

3. Clique em play_circle_filled Executar célula.

   Depois de executar o código, nenhuma saída será gerada no notebook do Colab. A marca de seleção ao lado da célula indica que o código foi executado com sucesso.

4. Para inserir uma célula de código, clique em add Código.

5. Para renderizar o diagrama de dispersão das estações de aluguel de bicicletas com base nos valores de longitude e latitude extraídos anteriormente, insira o seguinte código:

   # Render a scatter plot using pydeck with the extracted longitude and
   # latitude columns in the gdf_sf_bikestations geopandas.GeoDataFrame.
   scatterplot_layer = pdk.Layer(
     "ScatterplotLayer",
     id="bike_stations_scatterplot",
     data=gdf_sf_bikestations,
     get_position=['longitude', 'latitude'],
     get_radius=100,
     get_fill_color=[255, 0, 0, 140],  # Adjust color as desired
     pickable=True,
   )
   
   view_state = pdk.ViewState(latitude=37.77613, longitude=-122.42284, zoom=12)
   display_pydeck_map([scatterplot_layer], view_state)

6. Clique em play_circle_filled Executar célula.

   O resultado será assim:

   

Visualizar polígonos

Com a análise geoespacial, é possível analisar e visualizar dados geoespaciais no BigQuery usando tipos de dados GEOGRAPHY e funções geográficas do GoogleSQL.

O tipo de dados GEOGRAPHY na análise geoespacial é uma coleção de pontos, linestrings e polígonos, que é representada como um conjunto de pontos ou um subconjunto da superfície da Terra. Um tipo GEOGRAPHY pode conter objetos como os seguintes:

• Pontos
• Linhas
• Polígonos
• Multipolígonos

Para uma lista de todos os objetos compatíveis, consulte a documentação do tipo GEOGRAPHY.

Se você receber dados geoespaciais sem saber os formatos esperados, poderá visualizar os dados para descobrir os formatos. É possível visualizar formas convertendo os dados geográficos para o formato GeoJSON. Em seguida, é possível visualizar os dados GeoJSON usando uma camada GeoJSON do framework deck.gl.

Nesta seção, você vai consultar dados geográficos no conjunto de dados "Bairros de São Francisco" e visualizar os polígonos.

1. Para inserir uma célula de código, clique em add Código.

2. Para consultar os dados geográficos da tabela bigquery-public-data.san_francisco_neighborhoods.boundaries no conjunto de dados San Francisco Neighborhoods, insira o código a seguir. Este código usa a função mágica %%bigquery para executar a consulta e retornar os resultados em um DataFrame:

   # Query the neighborhood name and geometry from the San Francisco
   # neighborhoods dataset.
   %%bigquery gdf_sanfrancisco_neighborhoods --project {GCP_PROJECT_ID} --use_geodataframe geometry
   
   SELECT
     neighborhood,
     neighborhood_geom AS geometry
   FROM
     `bigquery-public-data.san_francisco_neighborhoods.boundaries`

3. Clique em play_circle_filled Executar célula.

   O resultado será assim:

   Job ID 12345-1234-5678-1234-123456789 successfully executed: 100%

4. Para inserir uma célula de código, clique em add Código.

5. Para receber um resumo do DataFrame, insira o seguinte código:

   # Get a summary of the DataFrame
   gdf_sanfrancisco_neighborhoods.info()

6. Clique em play_circle_filled Executar célula.

   Os resultados vão ter a aparência abaixo:

   <class 'geopandas.geodataframe.GeoDataFrame'>
   RangeIndex: 117 entries, 0 to 116
   Data columns (total 2 columns):
   #   Column        Non-Null Count  Dtype
   ---  ------        --------------  -----
   0   neighborhood  117 non-null    object
   1   geometry      117 non-null    geometry
   dtypes: geometry(1), object(1)
   memory usage: 2.0+ KB
   

7. Para visualizar a primeira linha do DataFrame, insira o seguinte código:

   # Preview the first row
   gdf_sanfrancisco_neighborhoods.head(1)

8. Clique em play_circle_filled Executar célula.

   O resultado será assim:

   

   Nos resultados, observe que os dados são um polígono.

9. Para inserir uma célula de código, clique em add Código.

10. Para visualizar os polígonos, insira o seguinte código. pydeck é usado para converter cada instância de objeto shapely na coluna de geometria para o formato GeoJSON:

    # Visualize the polygons.
    geojson_layer = pdk.Layer(
        'GeoJsonLayer',
        id="sf_neighborhoods",
        data=gdf_sanfrancisco_neighborhoods,
        get_line_color=[127, 0, 127, 255],
        get_fill_color=[60, 60, 60, 50],
        get_line_width=100,
        pickable=True,
        stroked=True,
        filled=True,
      )
    view_state = pdk.ViewState(latitude=37.77613, longitude=-122.42284, zoom=12)
    display_pydeck_map([geojson_layer], view_state)

11. Clique em play_circle_filled Executar célula.

    O resultado será assim:

    

Criar um mapa coroplético

Se você estiver explorando dados com polígonos difíceis de converter para o formato GeoJSON, use uma camada de polígonos do framework deck.gl. Uma camada de polígonos pode processar dados de entrada de tipos específicos, como uma matriz de pontos.

Nesta seção, você usa uma camada de polígonos para renderizar uma matriz de pontos e usa os resultados para renderizar um mapa coroplético. O mapa coroplético mostra a densidade de estações de aluguel de bicicletas por bairro, combinando dados do conjunto de dados de bairros de São Francisco com o conjunto de dados de bicicletas compartilhadas Ford GoBike de São Francisco.

1. Para inserir uma célula de código, clique em add Código.

2. Para agregar e contar o número de estações por bairro e criar uma coluna polygon que contenha uma matriz de pontos, insira o seguinte código:

   # Aggregate and count the number of stations per neighborhood.
   gdf_count_stations = gdf_sanfrancisco_neighborhoods.sjoin(gdf_sf_bikestations, how='left', predicate='contains')
   gdf_count_stations = gdf_count_stations.groupby(by='neighborhood')['station_id'].count().rename('num_stations')
   gdf_stations_x_neighborhood = gdf_sanfrancisco_neighborhoods.join(gdf_count_stations, on='neighborhood', how='inner')
   
   # To simulate non-GeoJSON input data, create a polygon column that contains
   # an array of points by using the pandas.Series.map method.
   gdf_stations_x_neighborhood['polygon'] = gdf_stations_x_neighborhood['geometry'].map(lambda g: list(g.exterior.coords))

3. Clique em play_circle_filled Executar célula.

   Depois de executar o código, nenhuma saída será gerada no notebook do Colab. A marca de seleção ao lado da célula indica que o código foi executado com sucesso.

4. Para inserir uma célula de código, clique em add Código.

5. Para adicionar uma coluna fill_color a cada um dos polígonos, insira o seguinte código:

   # Create a color map gradient using the branch library, and add a fill_color
   # column for each of the polygons.
   colormap = branca.colormap.LinearColormap(
     colors=["lightblue", "darkred"],
     vmin=0,
     vmax=gdf_stations_x_neighborhood['num_stations'].max(),
   )
   gdf_stations_x_neighborhood['fill_color'] = gdf_stations_x_neighborhood['num_stations'] \
     .map(lambda c: list(colormap.rgba_bytes_tuple(c)[:3]) + [0.7 * 255])   # force opacity of 0.7

6. Clique em play_circle_filled Executar célula.

   Depois de executar o código, nenhuma saída será gerada no notebook do Colab. A marca de seleção ao lado da célula indica que o código foi executado com sucesso.

7. Para inserir uma célula de código, clique em add Código.

8. Para renderizar a camada de polígonos, insira o seguinte código:

   # Render the polygon layer.
   polygon_layer = pdk.Layer(
     'PolygonLayer',
     id="bike_stations_choropleth",
     data=gdf_stations_x_neighborhood,
     get_polygon='polygon',
     get_fill_color='fill_color',
     get_line_color=[0, 0, 0, 255],
     get_line_width=50,
     pickable=True,
     stroked=True,
     filled=True,
   )
   view_state = pdk.ViewState(latitude=37.77613, longitude=-122.42284, zoom=12)
   display_pydeck_map([polygon_layer], view_state)

9. Clique em play_circle_filled Executar célula.

   O resultado será assim:

   

Criar um mapa de calor

Os mapas coropléticos são úteis quando você tem limites significativos conhecidos. Se você tiver dados sem limites significativos conhecidos, use uma camada de mapa de calor para renderizar a densidade contínua.

No exemplo a seguir, você consulta dados na tabela bigquery-public-data.san_francisco_sfpd_incidents.sfpd_incidents do conjunto de dados de relatórios do Departamento de Polícia de São Francisco (SFPD, na sigla em inglês). Os dados são usados para visualizar a distribuição de incidentes em 2015.

Para mapas de calor, é recomendável quantizar e agregar os dados antes da renderização. Neste exemplo, os dados são quantizados e agregados usando a indexação espacial H3 do Carto. O mapa de calor é criado usando uma camada de mapa de calor do framework deck.gl.

Neste exemplo, a quantização é feita usando a biblioteca Python h3 para agregar os pontos de incidentes em hexágonos. A função h3.latlng_to_cell é usada para mapear a posição do incidente (latitude e longitude) para um índice de célula H3. Uma resolução H3 de nove fornece hexágonos agregados suficientes para o mapa de calor. A função h3.cell_to_latlng é usada para determinar o centro de cada hexágono.

1. Para inserir uma célula de código, clique em add Código.

2. Para consultar os dados no conjunto de dados de relatórios do Departamento de Polícia de São Francisco (SFPD), insira o seguinte código. Este código usa a função mágica %%bigquery para executar a consulta e retornar os resultados em um DataFrame:

   # Query the incident key and location  data from the SFPD reports dataset.
   %%bigquery gdf_incidents --project {GCP_PROJECT_ID} --use_geodataframe location_geography
   
   SELECT
     unique_key,
     location_geography
   FROM (
     SELECT
       unique_key,
       SAFE.ST_GEOGFROMTEXT(location) AS location_geography, # WKT string to GEOMETRY
       EXTRACT(YEAR FROM timestamp) AS year,
     FROM `bigquery-public-data.san_francisco_sfpd_incidents.sfpd_incidents` incidents
   )
   WHERE year = 2015

3. Clique em play_circle_filled Executar célula.

   O resultado será assim:

   Job ID 12345-1234-5678-1234-123456789 successfully executed: 100%

4. Para inserir uma célula de código, clique em add Código.

5. Para calcular a célula de latitude e longitude de cada incidente, agregue os incidentes de cada célula, crie um DataFrame geopandas e adicione o centro de cada hexágono para a camada de mapa de calor. Insira o seguinte código:

   # Compute the cell for each incident's latitude and longitude.
   H3_RESOLUTION = 9
   gdf_incidents['h3_cell'] = gdf_incidents.geometry.apply(
       lambda geom: h3.latlng_to_cell(geom.y, geom.x, H3_RESOLUTION)
   )
   
   # Aggregate the incidents for each hexagon cell.
   count_incidents = gdf_incidents.groupby(by='h3_cell')['unique_key'].count().rename('num_incidents')
   
   # Construct a new geopandas.GeoDataFrame with the aggregate results.
   # Add the center of each hexagon for the HeatmapLayer to render.
   gdf_incidents_x_cell = gpd.GeoDataFrame(data=count_incidents).reset_index()
   gdf_incidents_x_cell['h3_center'] = gdf_incidents_x_cell['h3_cell'].apply(h3.cell_to_latlng)
   gdf_incidents_x_cell.info()

6. Clique em play_circle_filled Executar célula.

   O resultado será assim:

   <class 'geopandas.geodataframe.GeoDataFrame'>
   RangeIndex: 969 entries, 0 to 968
   Data columns (total 3 columns):
   #   Column         Non-Null Count  Dtype
   --  ------         --------------  -----
   0   h3_cell        969 non-null    object
   1   num_incidents  969 non-null    Int64
   2   h3_center      969 non-null    object
   dtypes: Int64(1), object(2)
   memory usage: 23.8+ KB
   

7. Para inserir uma célula de código, clique em add Código.

8. Para visualizar as cinco primeiras linhas do DataFrame, insira o seguinte código:

   # Preview the first five rows.
   gdf_incidents_x_cell.head()

9. Clique em play_circle_filled Executar célula.

   O resultado será assim:

   

10. Para inserir uma célula de código, clique em add Código.

11. Para converter os dados em um formato JSON que pode ser usado pelo HeatmapLayer, insira o seguinte código:

    # Convert to a JSON format recognized by the HeatmapLayer.
    def _make_heatmap_datum(row) -> dict:
      return {
          "latitude": row['h3_center'][0],
          "longitude": row['h3_center'][1],
          "weight": float(row['num_incidents']),
      }
    
    heatmap_data = gdf_incidents_x_cell.apply(_make_heatmap_datum, axis='columns').values.tolist()

12. Clique em play_circle_filled Executar célula.

    Depois de executar o código, nenhuma saída será gerada no notebook do Colab. A marca de seleção ao lado da célula indica que o código foi executado com sucesso.

13. Para inserir uma célula de código, clique em add Código.

14. Para renderizar o mapa de calor, insira o seguinte código:

    # Render the heatmap.
    heatmap_layer = pdk.Layer(
      "HeatmapLayer",
      id="sfpd_heatmap",
      data=heatmap_data,
      get_position=['longitude', 'latitude'],
      get_weight='weight',
      opacity=0.7,
      radius_pixels=99,  # this limitation can introduce artifacts (see above)
      aggregation='MEAN',
    )
    view_state = pdk.ViewState(latitude=37.77613, longitude=-122.42284, zoom=12)
    display_pydeck_map([heatmap_layer], view_state)

15. Clique em play_circle_filled Executar célula.

    O resultado será assim: