<commit_before>pydeck.Layer API Documentation
==========

## pydeck.Layer

```python
class pydeck.Layer(
    self,
    type,
    data,
    id=None,
    get_position='[lng,lat]',
    **kwargs)
```

Constructs a geospatial layer for plotting.

A catalog of available layers is viewable [here](https://github.com/uber/deck.gl/tree/master/docs/layers#deckgl-layer-catalog-overview).
Note that this is Javascript documentation and parameters in pydeck usually will be snake-cased according to Python convention.

#### Parameters

`type` : `str`
    Type of layer to render, e.g., `HexagonLayer`. See the layer catalog above.
`data` : `str` or `list` of `dict` or `pandas.DataFrame`
    A URL of data to load in, a list of dictionaries,
`id` : `str`, default `None`
    Unique name for the layer. Will autopopulate with a UUID if no ID is provided.
`get_position` : `str`, default `'[lng,lat]'`
    Name of position field, with some expression parsing, e.g., `'[lng,lat]'` is provided, the position field will be assumed to be the common case where a flat file has separate columns `lat` and `lng`.
`**kwargs` : `int` or `str` or `float` or `bool` or `list`
    Various other keyword arguments can be provided as well, provided they exist in the layer documentation.
    For examples, `extruded=True` will extrude the underlying layer if this is a property it can have.
    Fill color can be specified with `get_fill_color` as of RGBA values, e.g., `get_fill_color=[0, 0, 0]` for an all-black fill,
    or as the name of a field of color values in the data, e.g., `get_fill_color='fill_color'`.

#### Returns
    `pdk.Layer` : Layer object
<commit_msg>Update pydeck layer docs (#3655)<commit_after>pydeck.Layer API Documentation
==========

## pydeck.Layer

```python
class pydeck.Layer(
    self,
    type,
    data,
    id=None,
    **kwargs)
```

This class represents a kind of data visualization, like a scatterplot or a hexbin chart. The full deck.gl layer catalog is accessible via pydeck.

## Understand keyword arguments in pydeck layers

Keyword arguments vary by layer. A catalog of available layers in deck.gl is viewable [here](https://github.com/uber/deck.gl/tree/master/docs/layers#deckgl-layer-catalog-overview).

A few important observations:

- Not all layers have all parameters. For instance, `get_position` is available for a `ScatterplotLayer` but not `ArcLayer`. Be sure to refer to the deck.gl layer catalog.
- Styling conventions differ between deck.gl and pydeck. The deck.gl layer catalog documentation adheres to Javascript documentation standards; in pydeck, functions and class names follow Python conventions:
    - Parameters are `snake_case` (e.g., `getPosition` in deck.gl is `get_position` in pydeck)
    - Class names in deck.gl are treated as class names in pydeck, (e.g., `HexagonLayer` remains `HexagonLayer` in both libraries)
    
Currently in its beta version pydeck will not raise an error on incorrect or omitted layer positional arguments–if nothing renders in your viewport after changing the arguments, check your browser's developer console or review the layer catalog.

## The `type` positional argument

In the `pydeck.Layer` object, `type` is a required argument and where you pass the desired layer's deck.gl class name–that is, you should set it to the deck.gl layer you wish to plot. For example, notice how `type` below gives you a [deck.gl HexagonLayer](https://deck.gl/#/examples/core-layers/hexagon-layer):

```python
import pydeck as pdk

UK_ACCIDENTS_DATA = 'https://raw.githubusercontent.com/uber-common/deck.gl-data/master/examples/3d-heatmap/heatmap-data.csv'

layer = pdk.Layer(
    'HexagonLayer',  # `type` positional argument is here
    UK_ACCIDENTS_DATA,
    get_position='[lng, lat]',
    auto_highlight=True,
    elevation_scale=50,
    pickable=True,
    elevation_range=[0, 3000],
    extruded=True,                 
    coverage=1)

# Set the viewport location
view_state = pdk.ViewState(
    longitude=-1.415,
    latitude=52.2323,
    zoom=6,
    min_zoom=5,
    max_zoom=15,
    pitch=40.5,
    bearing=-27.36)

# Combined all of it and render a viewport
r = pdk.Deck(layers=[layer], initial_view_state=view_state)
r.to_html('hexagon-example.html')
```
<img src="https://i.imgur.com/kPYIKUl.png" alt="pydeck HexagonLayer" height=500></img>

Try changing `type` above to `ScatterplotLayer` and add some `ScatterplotLayer` attributes, `get_fill_color` and `radius`:

```python
layer = pdk.Layer(
    'ScatterplotLayer',                 # Change the `type` positional argument here
    UK_ACCIDENTS_DATA,
    get_position='[lng, lat]',
    auto_highlight=True,
    radius=1000,                        # Radius is given in meters
    get_fill_color=[180, 0, 200, 140],  # Set an RGBA value for fill
    pickable=True)
```
<img src="https://i.imgur.com/54a7buL.png" alt="pydeck ScatterplotLayer" height=500></img>

## Expression parsers in pydeck layer arguments

One particularly powerful feature of pydeck is an in-built Javascript expression parser that can process a limited subset of Javascript–no functions are allowed, but data accessors, boolean conditions, inline logical statements, arithmetic operations, and arrays are available.

To demonstrate the expression parser, change the color input in `get_fill_color` to a string:

```python
layer = pdk.Layer(
    'ScatterplotLayer',
    UK_ACCIDENTS_DATA,
    get_position='[lng, lat]',
    auto_highlight=True,
    radius=1000,
    get_fill_color='[180, 0, 200, 140]',
    pickable=True)
```

The result of the render will be the same as the last image. The expression parser in deck.gl processes the `get_fill_color` argument of `'[180, 0, 200, 140]'` and converts it to a list of constants.

The expression parser has access to the variables in your data, so these operations can be combined:

```python
layer = pdk.Layer(
    'ScatterplotLayer',
    UK_ACCIDENTS_DATA,
    get_position='[lng, lat]',
    auto_highlight=True,
    radius=1000,
    get_fill_color='[255, lng > 0 ? 200 * lng : -200 * lng, lng, 140]',
    pickable=True)
```

In particular, `get_position` takes `[lng, lat]` in many of these examples. This is deck.gl's expression parser reading the data passed to pydeck and extracting longitude and latitude as a coordinate pair.

Suppose you have a CSV as follows, where the location in the first field in the CSV (here, "coordinates")–

```csv
coordinates,classification
"[0.0, 0.0]",A
"[0.0, 0.0]",A
"[0.0, 1.0]",B
"[0.0, 1.0]",C
```

`get_position` here should be specified as `get_position='coordinates'`

If your coordinates are flattened, you will specify your position as `get_position='[lng,lat]'`

```csv
lng,lat,classification
0.0,0.0,A
0.0,0.0,A
0.0,1.0,B
0.0,1.0,C
```

# Example: Vancouver property values

```python
import pydeck

DATA_URL = "https://raw.githubusercontent.com/uber-common/deck.gl-data/master/examples/geojson/vancouver-blocks.json"
LAND_COVER = [[[-123.0, 49.196], [-123.0, 49.324], [-123.306, 49.324], [-123.306, 49.196]]]

INITIAL_VIEW_STATE = pydeck.ViewState(
  latitude=49.254,
  longitude=-123.13,
  zoom=11,
  max_zoom=16,
  pitch=45,
  bearing=0
)

polygon = pydeck.Layer(  
    'PolygonLayer',
    LAND_COVER,
    stroked=False,
    get_polygon='-',  # processes the data as a flat longitude-latitude pair
    get_fill_color=[0, 0, 0, 0]
)
geojson = pydeck.Layer(
    'GeoJsonLayer',
    DATA_URL,
    opacity=0.8,
    stroked=False,
    filled=True,
    extruded=True,
    wireframe=True,
    get_elevation="properties.valuePerSqm / 20",
    get_fill_color="[255, 255, properties.growth * 255]",
    get_line_color=[255, 255, 255],
    pickable=True
)

r = pydeck.Deck(
    layers=[polygon, geojson],
    initial_view_state=INITIAL_VIEW_STATE)
r.to_html()
```
<img src="https://i.imgur.com/M3toZK8.png" alt="pydeck Vancouver visualization" height=500></img>

{'fraction_non_alphanumeric': 0.11527671512369293, 'fraction_numerical': 0.02818158633001785, 'mean_word_length': 4.056737588652482, 'pattern_counts': {'":': 0, '<': 9, '<?xml version=': 0, '>': 10, 'https://': 8, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6628856', 'n_tokens_mistral': 2720, 'n_tokens_neox': 2487, 'n_words': 852}