Data Workflows

class cartoframes.data.Dataset(data, credentials=None, schema=None)

Generic data class for cartoframes data operations. A Dataset instance can be created from a dataframe, geodataframe, a table hosted on a CARTO account, an arbitrary query against a CARTO account, or a local or hosted GeoJSON source. If hosted, the data can be retrieved as a pandas DataFrame. If local or as a query, a new table can be created in a CARTO account off of the Dataset instance.

Examples

Dataframe:

from pandas
from cartoframes.data import Dataset

df = pandas.DataFrame(...)
Dataset(df)

GeoDataframe:

from geopandas
from cartoframes.data import Dataset

gdf = geopandas.DataFrame(...)
Dataset(gdf)

GeoJSON file:

from cartoframes.data import Dataset

Dataset('path/to/geojsonfile')

Table from CARTO

from cartoframes.auth import set_default_credentials
from cartoframes.data import Dataset

set_default_credentials(
    base_url='https://your_user_name.carto.com',
    api_key='your api key'
)

Dataset('table_name')

Query usign CARTO stuff

from cartoframes.auth import set_default_credentials
from cartoframes.data import Dataset

set_default_credentials(
    base_url='https://your_user_name.carto.com',
    api_key='your api key'
)

Dataset('select * from table_name WHERE ...')
credentials

Dataset Context

table_name

Dataset table name

schema

Dataset schema

query

Dataset query

dataframe

Dataset DataFrame

get_geodataframe()

Converts DataFrame into GeoDataFrame if possible

is_saved_in_carto

Property on whether Dataset is saved in CARTO account

dataset_info

DatasetInfo associated with Dataset instance

Note

This method only works for Datasets created from tables.

Example

from cartoframes.auth import set_default_credentials
from cartoframes.data import Dataset

set_default_credentials(
    base_url='https://your_user_name.carto.com/',
    api_key='your api key'
)

d = Dataset('tablename')
d.dataset_info
update_dataset_info(privacy=None, table_name=None)

Update/change Dataset privacy and name

Parameters:

Example

from cartoframes.data import Dataset, DatasetInfo
from cartoframes.auth import set_default_credentials

set_default_credentials(
    base_url='https://your_user_name.carto.com/',
    api_key='your api key'
)

d = Dataset('tablename')
d.update_dataset_info(privacy=DatasetInfo.LINK)
download(limit=None, decode_geom=False, retry_times=3)

Download / read a Dataset (table or query) from CARTO account associated with the Dataset’s instance of Context. :param limit: The number of rows of the Dataset to

download. Default is to download all rows. This value must be >= 0.
Parameters:
  • decode_geom (bool, optional) – Decode Dataset geometries into Shapely geometries from EWKB encoding.
  • retry_times (int, optional) – Number of time to retry the download in case it fails. Default is Dataset.DOWNLOAD_RETRY_TIMES.

Example

upload(with_lnglat=None, if_exists='fail', table_name=None, schema=None, credentials=None)

Upload Dataset to CARTO account associated with credentials. :param with_lnglat: Two columns that have the longitude

and latitude information. If used, a point geometry will be created upon upload to CARTO. Example input: (‘long’, ‘lat’). Defaults to None.
Parameters:
  • if_exists (str, optional) – Behavior for adding data from Dataset. Options are ‘fail’, ‘replace’, or ‘append’. Defaults to ‘fail’, which means that the Dataset instance will not overwrite a table of the same name if it exists. If the table does not exist, it will be created.
  • table_name (str) – Desired table name for the dataset on CARTO. If name does not conform to SQL naming conventions, it will be ‘normalized’ (e.g., all lower case, adding _ in place of spaces and other special characters.
  • credentials (Context, optional) – credentials of user account to send Dataset to. If not provided, a default credentials (if set with set_default_credentials) will attempted to be used.

Example

Send a pandas DataFrame to CARTO. .. code:

from cartoframes.auth import set_default_credentials
from cartoframes.data import Dataset
import pandas as pd
set_default_credentials(
    base_url='https://your_user_name.carto.com',
    api_key='your api key'
)
df = pd.DataFrame({
    'lat': [40, 45, 50],
    'lng': [-80, -85, -90]
})
d = Dataset(df)
d.upload(with_lnglat=('lng', 'lat'), table_name='sample_table')
delete()

Delete table on CARTO account associated with a Dataset instance

Example

from cartoframes.data import Dataset
from cartoframes.auth import set_default_credentials

set_default_credentials(
    base_url='https://your_user_name.carto.com',
    api_key='your api key'
)

d = Dataset('table_name')
d.delete()
Returns:True if deletion is successful, False otherwise.
Return type:bool
exists()

Checks to see if table exists

is_public()

Checks to see if table or table used by query has public privacy

is_local()

Checks if the Dataset is local (DataFrameDataset)

is_remote()

Checks if the Dataset is local (TableDataset or QueryDataset)

compute_geom_type()

Compute the geometry type from the data

get_table_column_names(exclude=None)

Get column names and types from a table

get_table_names()

Get table names used by Dataset instance