Merge pull request #1220 from CartoDB/carto-data-frame-replace

Fix CartoDataFrame docs

cartoframes/auth/defaults.py

@@ -14,7 +14,6 @@ def set_default_credentials(
     against a CARTO account. CARTOframes methods
     :py:class:`cartoframes.viz.Layer` (and helper layers in
     :py:mod:`cartoframes.viz.helpers`),
-    :py:class:`cartoframes.data.Dataset`,
     :py:class:`cartoframes.data.clients.SQLClient`, and others.
 
     Args:

cartoframes/core/cartodataframe.py

@@ -4,17 +4,66 @@
 
 
 class CartoDataFrame(GeoDataFrame):
-
     def __init__(self, *args, **kwargs):
+        """
+        The CartoDataFrame class is an extension of the `geopandas.GeoDataFrame
+        <http://geopandas.org/reference/geopandas.GeoDataFrame.html>`_ class. It provides
+        powerful cartographic visualizations, geometry detection and decoding, and read / write
+        access to the CARTO platform.
+        """
+
         super(CartoDataFrame, self).__init__(*args, **kwargs)
 
     @staticmethod
     def from_carto(*args, **kwargs):
+        """
+        Alternate constructor to create a CartoDataFrame from a table or SQL query in CARTO.
+        It is needed to set up the :py:class:`cartoframes.auth.Credentials`.
+        Equivalent to :py:meth:`read_carto <cartoframes.io.read_carto>`.
+
+        Examples:
+
+            Using a table name:
+
+            .. code::
+
+                from cartoframes import CartoDataFrame
+                from cartoframes.auth import set_default_credentials
+
+                set_default_credentials('your_user_name', 'your api key')
+
+                cdf = CartoDataFrame.from_carto('table_name')
+
+            Using a SQL query:
+
+            .. code::
+
+                from cartoframes import CartoDataFrame
+                from cartoframes.auth import set_default_credentials
+
+                set_default_credentials('your_user_name', 'your api key')
+
+                cdf = CartoDataFrame.from_carto('SELECT * FROM table_name WHERE value > 100')
+        """
+
         from ..io.carto import read_carto
         return read_carto(*args, **kwargs)
 
     @classmethod
     def from_file(cls, filename, **kwargs):
+        """
+        Alternate constructor to create a CartoDataFrame from a file.
+        Extends from the GeoDataFrame.from_file method.
+
+        Examples:
+
+            .. code::
+
+                from cartoframes import CartoDataFrame
+
+                cdf = CartoDataFrame.from_file('nybb.shp')
+        """
+
         gdf = GeoDataFrame.from_file(filename, **kwargs)
         return cls(gdf)
 
@@ -24,20 +73,115 @@ def _constructor(self):
 
     @classmethod
     def from_features(cls, features, **kwargs):
+        """
+        Alternate constructor to create a CartoDataframe from GeoJSON features.
+        Extends from the GeoDataFrame.from_features method.
+
+        Examples:
+
+            .. code::
+
+                from cartoframes import CartoDataFrame
+
+                cdf = CartoDataFrame.from_features('nybb.shp')
+        """
+
         gdf = GeoDataFrame.from_features(features, **kwargs)
         return cls(gdf)
 
     def to_carto(self, *args, **kwargs):
+        """
+        Upload a CartoDataFrame to CARTO. It is needed to set up the
+        :py:class:`cartoframes.auth.Credentials`.
+        Equivalent to :py:meth:`to_carto <cartoframes.io.to_carto>`.
+
+        Examples:
+
+            .. code::
+                from cartoframes import CartoDataFrame
+                from cartoframes.auth import set_default_credentials
+
+                set_default_credentials('your_user_name', 'your api key')
+
+                cdf = CartoDataFrame.from_file('nybb.shp')
+                cdf.to_carto('table_name', if_exists='replace')
+        """
+
         from ..io.carto import to_carto
         return to_carto(self, *args, **kwargs)
 
     def convert(self, index_column=None, geom_column=None, lnglat_columns=None,
                 drop_index=True, drop_geom=True, drop_lnglat=True):
-        # Magic function
+        """ For internal usage only.
+        Tries to decode the geometry automatically as a `shapely https://pypi.org/project/Shapely/_.`
+        object by looking for coordinates in columns.
+
+        Args:
+            index_column (str, optional):
+                Name of the index column. If it is `None`, it is generated automatically.
+            geom_column (str, optional):
+                Name of the geometry column to be used to generate the decoded geometry.
+                If it is None, it tries to find common geometry column names, but if there is
+                no geometry column it will leave it empty.
+            lnglat_columns ([str, str], optional):
+                Tuple with the longitude and latitude column names to be used to generate
+                the decoded geometry.
+            drop_index (bool, optional):
+                Defaults to True. Removes the index column.
+            drop_geom (bool, optional):
+                Defaults to True. Removes the geometry column.
+            drop_lnglat (bool, optional):
+                Defaults to True. Removes the lnglat column.
+
+        Returns:
+            The CartoDataFrame itself
+
+        Examples:
+
+            Decode the geometry automatically:
+
+            .. code::
+                from cartoframes import CartoDataFrame
+
+                cdf = CartoDataFrame.from_file('filename.csv').convert()
+
+            Passing the geometry column explicitly:
+
+            .. code::
+
+                from cartoframes import CartoDataFrame
+
+                cdf = CartoDataFrame.from_file('filename.csv')
+                cdf.convert(geom_column='my_geom_column')
+
+            Passing lnglat_columns explicitly:
+
+            .. code::
+
+                from cartoframes import CartoDataFrame
+
+                cdf = CartoDataFrame.from_file('filename.csv')
+                cdf.convert(lnglat_columns=['longitude', 'latitude'])
+
+            Passing the index column explicitly:
+
+            .. code::
+
+                from cartoframes import CartoDataFrame
+
+                cdf = CartoDataFrame.from_file('filename.csv')
+                cdf.convert(index_column='my_index')
+
+        """
+
         generate_index(self, index_column, drop_index)
         generate_geometry(self, geom_column, lnglat_columns, drop_geom, drop_lnglat)
         return self
 
     def viz(self, *args, **kwargs):
+        """
+        Creates a :py:class:`Map <cartoframes.viz.Map>` visualization
+        """
+
         from ..viz import Map, Layer
         return Map(Layer(self, *args, **kwargs))

cartoframes/data/clients/auth_api_client.py

@@ -11,10 +11,9 @@ class AuthAPIClient(object):
 
     Args:
         credentials (:py:class:`Credentials <cartoframes.auth.Credentials>`, optional):
-              credentials of user account to send Dataset to. If not provided,
-              a default credentials (if set with :py:meth:`set_default_credentials
-              <cartoframes.auth.set_default_credentials>`) will attempted to be
-              used.
+              credentials of user account. If not provided, a default credentials
+              (if set with :py:meth:`set_default_credentials <cartoframes.auth.set_default_credentials>`)
+              will attempted to be used.
     """
     def __init__(self, credentials=None):
         credentials = credentials or get_default_credentials()

cartoframes/data/clients/data_obs_client.py

@@ -20,7 +20,7 @@ class DataObsClient(object):
     <https://carto.com/developers/data-observatory/>`__.
 
     This class provides the following methods to interact with Data Observatory:
-        - boundary: returns a :py:class:`CartoDataFrame <cartoframes.CartoDataFrame>` with
+        - boundaries: returns a :py:class:`CartoDataFrame <cartoframes.CartoDataFrame>` with
             the geographic boundaries (geometries) or their metadata.
         - discovery: returns a pandas.DataFrame with the measures found.
         - augment: returns a :py:class:`CartoDataFrame <cartoframes.CartoDataFrame>` with the augmented data.

cartoframes/data/observatory/enrichment/enrichment.py

@@ -19,7 +19,7 @@ def __init__(self, credentials=None):
         super(Enrichment, self).__init__(credentials)
 
     def enrich_points(self, dataframe, variables, geom_column='geometry', filters={}):
-        """Enrich your dataframe with columns from our data, intersecting your points with our
+        """Enrich your dataframe with columns from our data, intersecting the points with our
         geographies. Extra columns as area and population will be provided with the aims of normalize
         these columns.
 
@@ -36,7 +36,8 @@ def enrich_points(self, dataframe, variables, geom_column='geometry', filters={}
             A :py:class:`CartoDataFrame <cartoframes.CartoDataFrame>` with the variables to enrich appended to it.
 
             Note that if the geometry of the `data` you provide intersects with more than one geometry
-            in the enrichment dataframe, the number of rows of the returned CartoDataFrame could be different
+            in the enrichment dataframe, the number of rows of the returned
+            :py:class:`CartoDataFrame <cartoframes.CartoDataFrame>` could be different
             than the `data` argument number of rows.
 
         Examples:
@@ -124,7 +125,7 @@ def enrich_points(self, dataframe, variables, geom_column='geometry', filters={}
 
     def enrich_polygons(self, dataframe, variables, geom_column='geometry', filters=[],
                         aggregation=AGGREGATION_DEFAULT):
-        """Enrich your dataframe with columns from our data, intersecting your polygons with our geographies.
+        """Enrich a dataframe with columns from our data, intersecting the polygons with our geographies.
         When a polygon intersects with multiple geographies of our dataframe, the proportional part of the
         intersection will be used to interpolate the quantity of the polygon value intersected, aggregating them
         with the operator provided by `agg_operators` argument.
@@ -142,25 +143,25 @@ def enrich_polygons(self, dataframe, variables, geom_column='geometry', filters=
             aggregation (str, str, list, optional): set the data aggregation. Your polygons can intersect with one or
             more polygons from the DO. With this method you can select how to aggregate the variables data from the
             intersected polygons. Options are:
-                - :py:attr:`Enrichment.AGGREGATION_DEFAULT` (default): Every `<cartoframes.data.observatory> Variable`
+                :py:attr:`Enrichment.AGGREGATION_DEFAULT` (default): Every `<cartoframes.data.observatory> Variable`
                 has an aggregation method in the Variable `agg_method` property and it will be used to aggregate the
                 data. In case it is not defined, `array_agg` function will be used.
-                - :py:attr:`Enrichment.AGGREGATION_NONE`: use this option to do the aggregation locally by yourself.
+                :py:attr:`Enrichment.AGGREGATION_NONE`: use this option to do the aggregation locally by yourself.
                 you will receive an array with all the data from each polygon instersected.
-                - list of `<cartoframes.data.observatory> VariableAggregation`: if you want to overwrite some default
+                list of `<cartoframes.data.observatory> VariableAggregation`: if you want to overwrite some default
                 aggregation methods from your selected variables, you can do it using a list of
                 `<cartoframes.data.observatory> VariableAggregation`. Example: [VariableAggregation(variable, 'SUM')]
-                - str: if you want to overwrite every default aggregation method, you can pass a string with the
+                str: if you want to overwrite every default aggregation method, you can pass a string with the
                 aggregation method to use.
 
         Returns:
+
             A :py:class:`CartoDataFrame <cartoframes.CartoDataFrame>` with the variables to enrich appended to it.
 
             Note that if the geometry of the `data` you provide intersects with more than one geometry
             in the enrichment dataframe, the number of rows of the returned CartoDataFrame could be different
             than the `data` argument number of rows.
 
-
         Examples:
 
             Enrich a polygons dataframe with one Variable: