Refactor sync.py module

README.md

@@ -81,10 +81,12 @@ dataset_ids = get_experiment_list_from_gene("Pvalb", axis='sagittal')
 
 - One can download any dataset from a dataset ID:
 ```python
-from atldld.sync import download_dataset_parallel
-dataset = download_dataset(dataset_id=DATASET_ID, **kwargs)
+from atldld.sync import download_parallel_dataset
+dataset = download_parallel_dataset(dataset_id=DATASET_ID, **kwargs)
 image_id, section_number, img, df = next(dataset)
 ```
+Note that this functionality makes a simplifying assumption that
+the slices are perfectly parallel to one of the 3 axes.
 
 - One can obtain metadata of a dataset:
 ```python

docs/source/allen.rst

@@ -70,20 +70,21 @@ Single image download
 
 Full-blown registration
 ~~~~~~~~~~~~~~~~~~~~~~~
-The most useful function is the :code:`download_dataset`. It expects the user to specify the unique
-:code:`dataset_id`. It returns a generator. Each iteration then yields
+The most useful function is the :code:`download_parallel_dataset`.
+It expects the user to specify the unique :code:`dataset_id`. It returns a
+generator. Each iteration then yields
 
 1. **Image id** (unique identifier)
 2. **Coronal section** (a number in [0, 13200])
 3. **Original image** (high resolution before registration)
-4. **Displacement field** (its shape depends on the :code:`ds_f` downsampling factor)
+4. **Displacement field** (its shape depends on the :code:`downsample_ref` downsampling factor)
 
 .. testcode::
 
-    from atldld.sync import download_dataset
+    from atldld.sync import download_parallel_dataset
 
     dataset_id = 909
-    data_gen = download_dataset(dataset_id, ds_f=25, verbose=False)
+    data_gen = download_parallel_dataset(dataset_id, downsample_ref=25)
 
     image_id, p, img, df = next(iter(data_gen))
     img_reg = df.warp(img)
@@ -92,6 +93,6 @@ To register the image one simply warps the original image with the displacement
 facts about the logic of :code:`download_dataset`.
 
 - Coronal section is approximate and is implied by a single point :code:`p_detection_xy`
-- The downsampling factor :code:`ds_f` determined the final shape the displacement field. By default its 25
+- The downsampling factor :code:`downsample_ref` determined the final shape the displacement field. By default its 25
 - The registration process is implemented locally to avoid extremely slow per pixel API calls