# IPython/Jupyter Extensions

The `pyrasterframes.rf_ipython` module injects a number of visualization extensions into the IPython environment, enhancing visualization of `DataFrame`s and `Tile`s.

By default, the last expression's result in a IPython cell is passed to the `IPython.display.display` function. This function in turn looks for a [`DisplayFormatter`](https://ipython.readthedocs.io/en/stable/api/generated/IPython.core.formatters.html#IPython.core.formatters.DisplayFormatter) associated with the type, which in turn converts the instance to a display-appropriate representation, based on MIME type. For example, each `DisplayFormatter` may `plain/text` version for the IPython shell, and a `text/html` version for a Jupyter Notebook.

This will be our setup for the following examples:

```python setup

from pyrasterframes import *

from pyrasterframes.rasterfunctions import *

from pyrasterframes.utils import create_rf_spark_session

import pyrasterframes.rf_ipython

from IPython.display import display

import os.path

spark = create_rf_spark_session()

def scene(band):

b = str(band).zfill(2) # converts int 2 to '02'

return 'https://modis-pds.s3.amazonaws.com/MCD43A4.006/11/08/2019059/' \

'MCD43A4.A2019059.h11v08.006.2019072203257_B{}.TIF'.format(b)

rf = spark.read.raster(scene(2), tile_dimensions=(256, 256))

```

## Tile Samples

We have some convenience methods to quickly visualize tiles (see discussion of the RasterFrame @ref:[schema](raster-read.md#single-raster) for orientation to the concept) when inspecting a subset of the data in a Notebook.

In an IPython or Jupyter interpreter, a `Tile` object will be displayed as an image with limited metadata.

```python, sample_tile

sample_tile = rf.select(rf_tile('proj_raster').alias('tile')).first()['tile']

sample_tile # or `display(sample_tile)`

```

## DataFrame Samples

Within an IPython or Jupyter interpreter, a Spark and Pandas DataFrames containing a column of _tiles_ will be rendered as the samples discussed above. Simply import the `rf_ipython` submodule to enable enhanced HTML rendering of these DataFrame types.

```python display_samples

rf # or `display(rf)`, or `rf.display()`

```

### Changing Number of Rows

By default the RasterFrame sample display renders 5 rows. Because the `IPython.display.display` function doesn't pass parameters to the underlying rendering functions, we have to provide a different means of passing parameters to the rendering code. Pandas approach to this is to use global settings via `set_option`/`get_option`. We take a more functional approach and have the user invoke an explicit `display` method:

```python custom_display, evaluate=False

rf.display(num_rows=1, truncate=True)

```

```python custom_display_mime, echo=False

rf.display(num_rows=1, truncate=True, mimetype='text/markdown')

```

### Pandas

There is similar rendering support injected into the Pandas by the `rf_ipython` module, for Pandas Dataframes having Tiles in them:

```python pandas_dataframe

# Limit copy of data from Spark to a few tiles.

pandas_df = rf.select(rf_tile('proj_raster'), rf_extent('proj_raster')).limit(4).toPandas()

pandas_df # or `display(pandas_df)`

```

## Sample Colorization

RasterFrames uses the "Viridis" color ramp as the default color profile for tile column. There are other options for reasoning about how color should be applied in the results.

### Color Composite

As shown in @ref:[Writing Raster Data section](raster-write.md) section, composites can be constructed for visualization:

```python, png_color_composite

from IPython.display import Image # For telling IPython how to interpret the PNG byte array

# Select red, green, and blue, respectively

three_band_rf = spark.read.raster(source=[[scene(1), scene(4), scene(3)]])

composite_rf = three_band_rf.withColumn('png',

rf_render_png('proj_raster_0', 'proj_raster_1', 'proj_raster_2'))

png_bytes = composite_rf.select('png').first()['png']

Image(png_bytes)

```

```python, png_render, echo=False

from IPython.display import display_markdown

display_markdown(pyrasterframes.rf_ipython.binary_to_html(png_bytes), raw=True)

```

### Custom Color Ramp

You can also apply a different color ramp to a single-channel Tile using the @ref[`rf_render_color_ramp_png`](reference.md#rf-render-color-ramp-png) function. See the function documentation for information about the available color maps.

```python, color_map

rf.select(rf_render_color_ramp_png('proj_raster', 'Magma'))

```