Repository: dask/dask

Issue:
Naming divisions vs partitions
Is there a reason to refer to these by different names going forward? They're conceptually the same thing right, or am I missing something? I know the API has been in-flight, so maybe this is already on the radar.



Discussion:
My intent here was to use the term "partitions" to mean the Pandas dataframes that constitute the dask dataframe and the term "divisions" to mean the values that separate the indices of the partitions.  People do tend to mix the two though.  Thoughts on how to improve the situation?

That sounds reasonable. The method to return a 'partition' is `get_division`, which is a bit tricky. Makes sense both ways I think. Probably just documenting this as convention (if it's not) would clear things up, though I wonder if people would be confused if it was just one or the other. I was mainly just wondering if the current state reflected a transition from one to the other.

Ah, you're right that `get_division` should probably be renamed.  Improved documentation is probably also a very good idea.


Resolving patch:
diff --git a/dask/dataframe/core.py b/dask/dataframe/core.py
--- a/dask/dataframe/core.py
+++ b/dask/dataframe/core.py
@@ -246,9 +246,13 @@ def known_divisions(self):
         return len(self.divisions) > 0 and self.divisions[0] is not None
 
     def get_division(self, n):
-        """ Get nth division of the data """
+        warnings.warn("Deprecation warning: use `get_partition` instead")
+        return get_partition(self, n)
+
+    def get_partition(self, n):
+        """Get a dask DataFrame/Series representing the `nth` partition."""
         if 0 <= n < self.npartitions:
-            name = 'get-division-%s-%s' % (str(n), self._name)
+            name = 'get-partition-%s-%s' % (str(n), self._name)
             dsk = {(name, 0): (self._name, n)}
             divisions = self.divisions[n:n+2]
             return self._constructor(merge(self.dask, dsk), name,
@@ -1180,7 +1184,7 @@ def _get_numeric_data(self, how='any', subset=None):
     @derived_from(pd.Series)
     def iteritems(self):
         for i in range(self.npartitions):
-            s = self.get_division(i).compute()
+            s = self.get_partition(i).compute()
             for item in s.iteritems():
                 yield item
 
@@ -1864,14 +1868,14 @@ def append(self, other):
     @derived_from(pd.DataFrame)
     def iterrows(self):
         for i in range(self.npartitions):
-            df = self.get_division(i).compute()
+            df = self.get_partition(i).compute()
             for row in df.iterrows():
                 yield row
 
     @derived_from(pd.DataFrame)
     def itertuples(self):
         for i in range(self.npartitions):
-            df = self.get_division(i).compute()
+            df = self.get_partition(i).compute()
             for row in df.itertuples():
                 yield row
 


Test patch:
diff --git a/dask/dataframe/tests/test_categorical.py b/dask/dataframe/tests/test_categorical.py
--- a/dask/dataframe/tests/test_categorical.py
+++ b/dask/dataframe/tests/test_categorical.py
@@ -34,19 +34,19 @@ def test_categorical_set_index():
     with dask.set_options(get=get_sync):
         b = a.set_index('y')
         df2 = df.set_index('y')
-        d1, d2 = b.get_division(0), b.get_division(1)
+        d1, d2 = b.get_partition(0), b.get_partition(1)
         assert list(d1.index.compute()) == ['a']
         assert list(sorted(d2.index.compute())) == ['b', 'b', 'c']
 
         b = a.set_index(a.y)
         df2 = df.set_index(df.y)
-        d1, d2 = b.get_division(0), b.get_division(1)
+        d1, d2 = b.get_partition(0), b.get_partition(1)
         assert list(d1.index.compute()) == ['a']
         assert list(sorted(d2.index.compute())) == ['b', 'b', 'c']
 
         b = a.set_partition('y', ['a', 'b', 'c'])
         df2 = df.set_index(df.y)
-        d1, d2 = b.get_division(0), b.get_division(1)
+        d1, d2 = b.get_partition(0), b.get_partition(1)
         assert list(d1.index.compute()) == ['a']
         assert list(sorted(d2.index.compute())) == ['b', 'b', 'c']
 
diff --git a/dask/dataframe/tests/test_dataframe.py b/dask/dataframe/tests/test_dataframe.py
--- a/dask/dataframe/tests/test_dataframe.py
+++ b/dask/dataframe/tests/test_dataframe.py
@@ -526,36 +526,36 @@ def test_set_partition_compute():
     assert len(d4.dask) > len(d5.dask)
 
 
-def test_get_division():
+def test_get_partition():
     pdf = pd.DataFrame(np.random.randn(10, 5), columns=list('abcde'))
     ddf = dd.from_pandas(pdf, 3)
     assert ddf.divisions == (0, 4, 8, 9)
 
     # DataFrame
-    div1 = ddf.get_division(0)
+    div1 = ddf.get_partition(0)
     assert isinstance(div1, dd.DataFrame)
     assert eq(div1, pdf.loc[0:3])
-    div2 = ddf.get_division(1)
+    div2 = ddf.get_partition(1)
     assert eq(div2, pdf.loc[4:7])
-    div3 = ddf.get_division(2)
+    div3 = ddf.get_partition(2)
     assert eq(div3, pdf.loc[8:9])
     assert len(div1) + len(div2) + len(div3) == len(pdf)
 
     # Series
-    div1 = ddf.a.get_division(0)
+    div1 = ddf.a.get_partition(0)
     assert isinstance(div1, dd.Series)
     assert eq(div1, pdf.a.loc[0:3])
-    div2 = ddf.a.get_division(1)
+    div2 = ddf.a.get_partition(1)
     assert eq(div2, pdf.a.loc[4:7])
-    div3 = ddf.a.get_division(2)
+    div3 = ddf.a.get_partition(2)
     assert eq(div3, pdf.a.loc[8:9])
     assert len(div1) + len(div2) + len(div3) == len(pdf.a)
 
     with tm.assertRaises(ValueError):
-        ddf.get_division(-1)
+        ddf.get_partition(-1)
 
     with tm.assertRaises(ValueError):
-        ddf.get_division(3)
+        ddf.get_partition(3)
 
 
 def test_ndim():
diff --git a/dask/dataframe/tests/test_demo.py b/dask/dataframe/tests/test_demo.py
--- a/dask/dataframe/tests/test_demo.py
+++ b/dask/dataframe/tests/test_demo.py
@@ -29,6 +29,6 @@ def test_no_overlaps():
     df = dd.demo.make_timeseries('2000', '2001', {'A': float},
                                  freq='3H', partition_freq='3M')
 
-    assert all(df.get_division(i).index.max().compute()
-             < df.get_division(i + 1).index.min().compute()
+    assert all(df.get_partition(i).index.max().compute()
+             < df.get_partition(i + 1).index.min().compute()
              for i in range(df.npartitions - 2))