v1.0.0 Migration

This migration guide aims to provide useful information about these pieces that might be affected when upgrading to the v1.0.0 CARTOframes version.

Migration notes for previous beta versions: v1.0b3, v1.0b4, v1.0b5, v1.0b6, and v1.0b7 to v1.0.0
- Dataset (< v1.0b6)
- CartoDataFrame (>= v1.0b6)
- CatalogDataset
- Style
- Popups
- Widgets
- Legends
Migration notes from last stable version v0.10.1 to v1.0.0
- Context
- Read
- Write
- Delete
- Query
- Visualization
- Data Observatory

Beta Versions

Dataset

Dataset class

The Dataset class for reading and writing data is not needed anymore. Now there's a different Dataset class used in the Data Observatory, and they are different things.

Visualize a dataframe:

From:

from cartoframes.data import Dataset
from cartoframes.viz import Map, Layer

ds = Dataset(df)
Map(Layer(ds))

To:

from cartoframes.viz import Map, Layer

Map(Layer(df))

Download data:

From:

from cartoframes.data import Dataset

ds = Dataset('table_name')
df = ds.download()

To:

from cartoframes import read_carto

gdf = read_carto('table_name')

Use a SQL query:

From:

from cartoframes.data import Dataset

ds = Dataset("SELECT * FROM global_power_plants WHERE country IN ('Brazil')")
df = ds.download()

To:

from cartoframes import read_carto

gdf = read_carto("SELECT * FROM global_power_plants WHERE country IN ('Brazil')")

Upload data:

From:

from cartoframes.data import Dataset

ds = Dataset(gdf)

ds.upload(
    table_name='table',
    with_lnglat=('longitude', 'latitude'),
    if_exists=Dataset.IF_EXISTS_REPLACE
)

To:

from cartoframes import to_carto

to_carto(
    gdf,
    table_name='table',
    if_exists='replace'
)

Change Dataset privacy:

From

from cartoframes.data import Dataset

ds = Dataset('table_name')

ds.update_dataset_info(privacy=Dataset.PRIVACY_PRIVATE)

To:

from cartoframes import update_privacy_table

update_privacy_table('table_name', 'private')

CatalogDataset

CatalogDataset class

This class is now named Dataset:

From:

from cartoframes.data.observatory import CatalogDataset

dataset = CatalogDataset.get('carto-do.ags.demographics_retailpotential_usa_blockgroup_2015_yearly_2018')

To:

from cartoframes.data.observatory import Dataset

dataset = Dataset.get('carto-do.ags.demographics_retailpotential_usa_blockgroup_2015_yearly_2018')

CartoDataFrame

Geometry management

From:

from cartoframes import CartoDataFrame

cdf = CartoDataFrame(df, geometry='the_geom')

To:

from geopandas import GeoDataFrame
from cartoframes.utils import decode_geometry

gdf = GeoDataFrame(df, geometry=decode_geometry(df['the_geom']))

From:

from cartoframes import CartoDataFrame

cdf = CartoDataFrame(df)
cdf.set_geometry_from_xy('lng', 'lat', inplace=True)

To:

from geopandas import GeoDataFrame, points_from_xy

gdf = GeoDataFrame(df, geometry=points_from_xy(df['lng'], df['lat']))

Load data from CARTO

From:

from cartoframes import CartoDataFrame

cdf = CartoDataFrame.from_carto('global_power_plants', limit=100)

To (as we already could):

from cartoframes import read_carto

gdf = read_carto('global_power_plants', limit=100)

Upload data to CARTO

From:

cdf.to_carto(
    table_name='global_power_plants',
    if_exists='replace'
)

To (as we already could):

from cartoframes import to_carto

to_carto(
    gdf,
    table_name='global_power_plants',
    if_exists='replace'
)

Visualization

From:

cdf.viz()

To (as we already could):

from cartoframes.viz import Map, Layer

Map(Layer(gdf))

# or Layer(gdf)

Style

Use basic_style over "string syntax"

Replace CARTO VL style syntax by using style helpers.

From:

from cartoframes.viz import Map, Layer, Style

Map(
  Layer(
    'table_name',
    style='color: blue strokeColor: white'
  )
)

To:

from cartoframes.viz import Map, Layer, basic_style

Map(
  Layer(
    'table_name',
    style=basic_style(color='blue', stroke_color='white')
  )
)

Replace layer helpers with style helpers

From:

from cartoframes.viz.helpers import size_category_layer

size_category_layer(
  'roads',
  'type',
  title='Roads sized by category'
)

To:

from cartoframes.viz import Layer, size_category_style

Layer(
  'roads',
  size_category_style('type'),
  title='Roads sized by category'
)

Layer Helpers

Layer helpers have been replaced by style helpers. Now every layer is made by using the Layer class.

From:

from cartoframes.viz.helpers import color_category_layer

color_category_layer('table', 'column', palette='sunset', legends=False, widgets=True, popups=True, title='Title')

To:

from cartoframes.viz.helpers import Layer, color_category_style

Layer(
    'table',
    color_category_style('column', palette='sunset'),
    default_legend=False,
    default_widget=True,
    default_popup_hover=True,
    default_popup_click=True  # New feature
    title='Title'
)

Popups

Hover Popup

Simple hover popup, now popup_hover is a Layer parameter that contains an array of popup_element

From:

from cartoframes.viz import Layer

Layer(
    'populated_places'
    popup={
        'hover': '$name'
    }
)

To:

from cartoframes.viz import Layer, popup_element

Layer(
    'populated_places',
    popup_hover=[
        popup_element('name')
    ]
)

Click Popup

Click popup with two values, now popup_click is also a Layer parameter that contains an array of popup_element

From:

from cartoframes.viz import Layer

Layer(
    'populated_places'
    popup={
        'click': ['$name', '$pop_max']
    }
)

To:

from cartoframes.viz import Layer, popup_element

Layer(
    'populated_places',
    popup_click=[
        popup_element('name'),
        popup_element('pop_max')
    ]
)

Multiple Popups

Multiple popups with custom titles

From:

from cartoframes.viz import Layer

Layer(
    'populated_places'
    popup={
        'click': [{
            'value': '$name',
            'title': 'Name'
        }, {
            'value': '$pop_max',
            'title': 'Pop Max'
        }],
        'hover': [{
            'value': '$name',
            'title': 'Name'
        }]
    }
)

To:

from cartoframes.viz import Layer, popup_element

Layer(
    'populated_places',
    popup_hover=[
        popup_element('name', title='Name'),
    ],
    popup_click=[
        popup_element('name', title='Name'),
        popup_element('pop_max', title='Pop Max')
    ]
)

Widgets

Namespace

From:

from cartoframes.viz.widgets import formula_widget

To:

from cartoframes.viz import formula_widget

Widget class

Don't create widgets through the Widget class anymore, extend the built-in widgets

Legends

Namespace

From:

from cartoframes.viz import Legend

To:

from cartoframes.viz import color_bins_legend

Add legends to a class

Don't create widgets through the Legend class anymore, extend the built-in legends
legend parameter in Layer now is legends (plural)
From:

from cartoframes.viz import Map, Layer, Legend
Map(
  Layer(
    'table_name',
    style='...',
    legend=Legend('color-bins', title='Legend Title')
  )
)

To:

from cartoframes.viz import Map, Layer, color_bins_style, color_bins_legend, 
Map(
  Layer(
    'table_name',
    style=color_bins_style('column_name'),
    legends=color_bins_legend(title='Legend Title')
  )
)

# or

from cartoframes.viz import Map, Layer, color_bins_style, default_legend
Map(
  Layer(
    'table_name',
    style=color_bins_style('column_name'),
    legends=default_legend(title='Legend Title')
  )
)

Using multiple legends:

from cartoframes.viz import Map, Layer, color_bins_style, basic_legend, default_legend
Map(
  Layer(
    'table_name',
    style=color_bins_style('column_name')
    legends=[
      basic_legend(title='Legend Title 1'),
      default_legend(title='Legend Title 2')
    ]
  )
)

Legend properties

Available properties for legends are changed to:

"color" -> "color"
"strokeColor" -> "stroke_color"
"width" -> "size"
"strokeWidth" -> "stroke_width"
From:

from cartoframes.viz import Map, Layer, Legend
Map(
  Layer(
    'table_name',
    style='...',
    legend=Legend('color-category', title='Legend Title', prop='strokeColor')
  )
)

To:

from cartoframes.viz import color_category_style, color_category_legend
Map(
  Layer(
    'table_name',
    style=color_category_style('column_name'),
    legends=color_category_legend('color-bins', title='Legend Title', prop='stroke_color')
  )
)

Stable

The most important thing to take into account is that CARTOframes v1.0.0 approach is based on v0.10.1, but it's not compatible with v0* versions.

Context

CartoContext

The CartoContext concept does not exist anymore to set the CARTO credentials.

From:

from cartoframes.context import CartoContext

cc = CartoContext(
    base_url='https://johnsmith.carto.com',
    api_key='abcdefg'
)

To:

from cartoframes.auth import set_default_credentials

set_default_credentials(
    base_url='https://johnsmith.carto.com',
    api_key='abcdefg'
)

From:

from cartoframes import Credentials

Credentials(
    username='johnsmith',
    api_key='abcdefg'
)

To:

from cartoframes.auth import Credentials

credentials = Credentials(
    username='johnsmith',
    api_key='abcdefg'
)

Also, it is possible, and we recomend this option, to read credentials from a .json file:

from cartoframes.auth import set_default_credentials

set_default_credentials('creds.json')

{
  "username": "johnsmith",
  "api_key": "abcdefg"
}

Read

Read data from CARTO

From:

import cartoframes

cc = cartoframes.CartoContext('https://johnsmith.carto.com', 'abcdefg')
df = cc.read('dataset_name')

To:

from cartoframes.auth import set_default_credentials
from cartoframes import read_carto

set_default_credentials('johnsmith', 'abcdefg')
gdf = read_carto('table_name')

Write

Write data to CARTO

From:

import cartoframes

cc = cartoframes.CartoContext('https://johnsmith.carto.com', 'abcdefg')
cc.write(df, 'table_name')

To:

from cartoframes.auth import set_default_credentials
from cartoframes import to_carto

set_default_credentials('johnsmith', 'abcdefg')
to_carto(df, 'table_name')

Delete

Delete data from CARTO

From:

import cartoframes

cc = cartoframes.CartoContext('https://johnsmith.carto.com', 'abcdefg')
cc.delete('table_name')

To:

from cartoframes.auth import set_default_credentials
from cartoframes import delete_table

set_default_credentials('johnsmith', 'abcdefg')
delete_table('table_name')

Query

Run a SQL query to a table

From:

import cartoframes

cc = cartoframes.CartoContext('https://johnsmith.carto.com', 'abcdefg')
df = cc.query(
    '''
      SELECT * FROM
      my_table
      ORDER BY value_column DESC
      LIMIT 10
    ''',
    table_name='table_name'
)

To:

from cartoframes.auth import set_default_credentials
from cartoframes import read_carto

set_default_credentials('johnsmith', 'abcdefg')
gdf = read_carto('''
        SELECT * FROM
        my_table
        ORDER BY value_column DESC
        LIMIT 10
    ''')

Visualization

Create a Map visualization

CARTOframes visualization has changed significantly, and we highly recommend to read the Visualization Guide

From:

import cartoframes

cc = cartoframes.CartoContext('https://johnsmith.carto.com', 'abcdefg')
cc.map(
    layers=Layer('table_name', color='category'),
    zoom=14,
    lng=-68,
    lat=45)

To:

from cartoframes.auth import set_default_credentials
from cartoframes.viz import Map, Layer, color_category_style

set_default_credentials('johnsmith', 'abcdefg')

Map(
  Layer(
    'table_name',
    color_category_style('category')
  ),
  viewport={zoom: 14, lat: 45, lng: -68}
)

Data Observatory

Discover datasets in the Data Observatory

We've a full integration with the Data Observatory and new functionality. We recommend go through the Data Discovery and Data Enrichment guides.

From:

import cartoframes

cc = cartoframes.CartoContext('https://johnsmith.carto.com', 'abcdefg')
meta = cc.data_discovery('USA', keywords='demographics', time='2010')
print(meta['numer_name'].values)

To:

from cartoframes.data.observatory import Catalog

Catalog().country('usa').category('demographics').datasets

From:

To:

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

1.0.0.md

1.0.0.md

v1.0.0 Migration

Beta Versions

Dataset

CatalogDataset

CartoDataFrame

Style

Popups

Widgets

Legends

Stable

Context

Read

Write

Delete

Query

Visualization

Data Observatory

Files

1.0.0.md

Latest commit

History

1.0.0.md

File metadata and controls

v1.0.0 Migration

Beta Versions

Dataset

CatalogDataset

CartoDataFrame

Style

Popups

Widgets

Legends

Stable

Context

Read

Write

Delete

Query

Visualization

Data Observatory