RFC: public/private separation

.flake8

@@ -1,4 +1,4 @@
 [flake8]
 max-line-length=100
-application-import-names = starfish, examples
+application-import-names = starfish
 import-order-style = smarkets

docs/source/_static/data_formatting_examples/format_imc_data.py

@@ -8,13 +8,13 @@
 import os
 from typing import List, Mapping, Tuple, Union
 
+import click
 import numpy as np
 from skimage.io import imread
 from slicedimage import ImageFormat
 
 from starfish.experiment.builder import FetchedTile, TileFetcher, write_experiment_json
 from starfish.types import Axes, Coordinates, Features, Number
-from starfish.util import click
 
 
 class ImagingMassCytometryTile(FetchedTile):

docs/source/_static/data_formatting_examples/format_osmfish.py

@@ -11,13 +11,13 @@
 import re
 from typing import Mapping, Tuple, Union
 
+import click
 import numpy as np
 from slicedimage import ImageFormat
 
 import starfish.util.try_import
 from starfish.experiment.builder import FetchedTile, TileFetcher, write_experiment_json
 from starfish.types import Axes, Coordinates, Features, Number
-from starfish.util import click
 
 
 # We use this to cache images across tiles.  In the case of the osmFISH data set, volumes are saved

docs/source/_static/data_formatting_examples/format_starmap.py

@@ -11,14 +11,14 @@
 import os
 from typing import Mapping, Tuple, Union
 
+import click
 import numpy as np
 from skimage.io import imread
 from slicedimage import ImageFormat
 
 from starfish import Codebook
 from starfish.experiment.builder import FetchedTile, TileFetcher, write_experiment_json
 from starfish.types import Axes, Coordinates, Features
-from starfish.util import click
 
 
 # We use this to cache images. This allows us to write a separate function to extract the data's

docs/source/api/data_structures/codebook.rst

@@ -3,5 +3,5 @@
 Codebook
 ========
 
-.. automodule:: starfish.codebook.codebook
+.. autoclass:: starfish.core.codebook.codebook.Codebook
    :members:

docs/source/api/data_structures/experiment.rst

@@ -3,5 +3,5 @@
 Experiment
 ==========
 
-.. autoclass:: starfish.experiment.experiment.Experiment
+.. autoclass:: starfish.core.experiment.experiment.Experiment
     :members:

docs/source/api/data_structures/expression_matrix.rst

@@ -7,5 +7,5 @@ Expression Matrix is a wrapper for xarray.DataArray that provides serialization
 loom, and AnnData to enable it to be used with single-cell analysis software packages such as
 scanpy (python) and seurat (R).
 
-.. automodule:: starfish.expression_matrix.expression_matrix
+.. autoclass:: starfish.core.expression_matrix.expression_matrix.ExpressionMatrix
    :members:

docs/source/api/data_structures/field_of_view.rst

@@ -3,5 +3,5 @@
 Field of View
 =============
 
-.. autoclass:: starfish.experiment.experiment.FieldOfView
+.. autoclass:: starfish.core.experiment.experiment.FieldOfView
     :members:

docs/source/api/data_structures/image_stack.rst

@@ -3,5 +3,5 @@
 ImageStack
 ==========
 
-.. automodule:: starfish.imagestack.imagestack
+.. autoclass:: starfish.core.imagestack.imagestack.ImageStack
    :members:

docs/source/api/data_structures/intensity_table.rst

@@ -3,8 +3,8 @@
 IntensityTable
 ==============
 
-.. automodule:: starfish.intensity_table.intensity_table
+.. autoclass:: starfish.core.intensity_table.intensity_table.IntensityTable
    :members:
 
-.. automodule:: starfish.intensity_table.intensity_table_coordinates
+.. automodule:: starfish.core.intensity_table.intensity_table_coordinates
    :members:

docs/source/api/data_structures/pipeline_component.rst

@@ -3,5 +3,5 @@
 Pipeline Component
 ==================
 
-.. automodule:: starfish.pipeline.pipelinecomponent
+.. automodule:: starfish.core.pipeline.pipelinecomponent
    :members:

docs/source/api/recipe/index.rst

@@ -3,5 +3,5 @@
 Recipe
 ======
 
-.. autoclass:: starfish.recipe.Recipe
+.. autoclass:: starfish.core.recipe.Recipe
    :members:

docs/source/api/types/index.rst

@@ -16,13 +16,13 @@ Coordinates holds constants that store with the physical coordinates of a field
 a field of view's relative location to some global scale parameter, and identify how to stitch or
 combine multiple fields of view.
 
-.. autoclass:: starfish.types.Coordinates
+.. autoclass:: starfish.core.types.Coordinates
     :members:
     :undoc-members:
 
 Physical Coordinates
 ---------------------
-.. autoclass:: starfish.types.PhysicalCoordinateTypes
+.. autoclass:: starfish.core.types.PhysicalCoordinateTypes
     :members:
     :undoc-members:
 
@@ -36,7 +36,7 @@ Axes holds constants that represent indexers into the dimensions of the :py:clas
 2. :py:class:`Codebook`, which stores expected image intensities across imaging rounds and
    channels
 
-.. autoclass:: starfish.types.Axes
+.. autoclass:: starfish.core.types.Axes
     :members:
     :undoc-members:
 
@@ -46,7 +46,7 @@ Features
 Features holds constants that represent characteristics of detected image features (most often
 spots, but sometimes also individual pixels).
 
-.. autoclass:: starfish.types.Features
+.. autoclass:: starfish.core.types.Features
     :members:
     :undoc-members:
 
@@ -58,13 +58,13 @@ SpotAttributes defines the minimum amount of information required by starfish to
 a spot. It also contains methods to save these attributes to files that can be used to visualize
 detected spots.
 
-.. autoclass:: starfish.types.SpotAttributes
+.. autoclass:: starfish.core.types.SpotAttributes
     :members:
 
 Clip
 _____
 
-.. autoclass:: starfish.types.Clip
+.. autoclass:: starfish.core.types.Clip
     :members:
     :undoc-members:
 

docs/source/api/validation/index.rst

@@ -8,7 +8,7 @@ Validators are provided for validating a SpaceTx fileset against the :ref:`schem
 Validators
 ----------
 
-.. autoclass:: starfish.spacetx_format.util.SpaceTxValidator
+.. autoclass:: starfish.core.spacetx_format.util.SpaceTxValidator
    :members:
    :exclude-members: fuzz_object
 
@@ -19,7 +19,7 @@ In addition, the starfish.spacetx_format.validate_sptx module contains helpers t
 iterating over the tree of json files and their respective schemas.
 
 
-.. automodule:: starfish.spacetx_format.validate_sptx
+.. automodule:: starfish.core.spacetx_format.validate_sptx
    :members:
 
 
@@ -31,7 +31,7 @@ For example:
 
 ::
 
-    starfish/starfish/spacetx_format/util.py:82: UserWarning:
+    starfish/starfish/core/spacetx_format/util.py:82: UserWarning:
      'contents' is a required property
             Schema:                 https://github.com/spacetx/starfish/starfish/file-format/schema/fov-manifest.json
             Subschema level:        0

docs/source/getting_started/formatting_data/index.rst

@@ -110,10 +110,10 @@ SpaceTx-Format :py:class:`Experiment`.
 
 These are the abstract classes that must be subclassed for each set of naming conventions:
 
-.. literalinclude:: /../../starfish/experiment/builder/providers.py
+.. literalinclude:: /../../starfish/core/experiment/builder/providers.py
     :pyobject: FetchedTile
 
-.. literalinclude:: /../../starfish/experiment/builder/providers.py
+.. literalinclude:: /../../starfish/core/experiment/builder/providers.py
     :pyobject: TileFetcher
 
 To create a formatter object for in-situ sequencing, we subclass the ``TileFetcher`` and

notebooks/ISS.ipynb

@@ -356,7 +356,7 @@
    "outputs": [],
    "source": [
     "from starfish.spots import AssignTargets\n",
-    "from starfish.expression_matrix.expression_matrix import ExpressionMatrix\n",
+    "from starfish import ExpressionMatrix\n",
     "\n",
     "al = AssignTargets.Label()\n",
     "labeled = al.run(masks, decoded)\n",

notebooks/STARmap.ipynb

@@ -58,8 +58,7 @@
     "rounds. Ideally, these should form fairly coherent spots, indicating that the\n",
     "data are well registered. By contrast, if there are patterns whereby pairs of\n",
     "spots are consistently present at small shifts, that can indicate systematic\n",
-    "registration offsets which should be corrected prior to analysis.\n",
-    ""
+    "registration offsets which should be corrected prior to analysis."
    ]
   },
   {
@@ -92,8 +91,7 @@
     "----------------------\n",
     "The STARmap codebook maps pixel intensities across the rounds and channels to\n",
     "the corresponding barcodes and genes that those pixels code for. For this\n",
-    "dataset, the codebook specifies 160 gene targets.\n",
-    ""
+    "dataset, the codebook specifies 160 gene targets."
    ]
   },
   {
@@ -185,8 +183,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Show the effect of registration.\n",
-    ""
+    "Show the effect of registration."
    ]
   },
   {
@@ -234,8 +231,7 @@
     "Note that this type of histogram matching has an implied assumption that each\n",
     "channel has relatively similar numbers of spots. In the case of this data\n",
     "this assumption is reasonably accurate, but for other datasets it can be\n",
-    "problematic to apply filters that match this stringently.\n",
-    ""
+    "problematic to apply filters that match this stringently."
    ]
   },
   {
@@ -294,8 +290,7 @@
     "zero. Note that many of the spots do _not_ identify spots in other rounds and\n",
     "channels and will therefore fail decoding. Because of the stringency built\n",
     "into the STARmap codebook, it is OK to be relatively permissive with the spot\n",
-    "finding parameters for this assay.\n",
-    ""
+    "finding parameters for this assay."
    ]
   },
   {
@@ -324,8 +319,7 @@
     "------------\n",
     "Next, spots are decoded. There is really no good way to display 3-d spot\n",
     "detection in 2-d planes, so we encourage you to grab this notebook and\n",
-    "uncomment the below lines.\n",
-    ""
+    "uncomment the below lines."
    ]
   },
   {

notebooks/py/ISS.py

@@ -232,7 +232,7 @@
 
 # EPY: START code
 from starfish.spots import AssignTargets
-from starfish.expression_matrix.expression_matrix import ExpressionMatrix
+from starfish import ExpressionMatrix
 
 al = AssignTargets.Label()
 labeled = al.run(masks, decoded)

setup.py

@@ -16,7 +16,7 @@
     },
     entry_points={
         'console_scripts': [
-            "starfish=starfish.starfish:starfish",
+            "starfish=starfish:starfish",
         ]
     },
     include_package_data=True,

starfish/__init__.py

@@ -1,37 +1,26 @@
-# deal with numpy import warnings due to cython
-# See: https://stackoverflow.com/questions/40845304/
-#      runtimewarning-numpy-dtype-size-changed-may-indicate-binary-incompatibility)
-import warnings
-warnings.filterwarnings("ignore", message="numpy.dtype size changed")  # noqa
-warnings.filterwarnings("ignore", message="numpy.ufunc size changed")  # noqa
-
-import pkg_resources
-
-# image processing methods and objects
-from . import image
-# spot detection and manipulation
-from . import spots
+from . import (
+    # configuration management.
+    config,
+    # image processing methods and objects.
+    image,
+    # spot detection and manipulation.
+    spots,
+)
+from .core import (
+    is_release_tag as __is_release_tag__,
+    version as __version__
+)
 # display images and spots
-from ._display import display
-# generated version number and commit hash
-from ._version import get_versions
+from .core._display import display
 # top-level objects
-from .codebook.codebook import Codebook
-from .experiment.experiment import Experiment, FieldOfView
-from .imagestack.imagestack import ImageStack
-from .intensity_table.intensity_table import IntensityTable
-from .recipe import cli
-from .starfish import starfish
+from .core.codebook.codebook import Codebook
+from .core.experiment.experiment import Experiment, FieldOfView
+from .core.expression_matrix.expression_matrix import ExpressionMatrix
+from .core.imagestack.imagestack import ImageStack
+from .core.intensity_table.intensity_table import IntensityTable
+from .core.recipe import cli
+from .core.starfish import starfish
 
 
-# NOTE: if we move to python 3.7, we can produce this value at call time via __getattr__
-__version__ = get_versions()['version']
-__is_release_tag__ = None
-if "+" not in str(__version__):
-    __is_release_tag__ = f"Release: {__version__}"
-del get_versions
-
 if __name__ == "__main__":
     starfish()
-
-del warnings, pkg_resources

starfish/config.py

@@ -0,0 +1 @@
+from .core.config import environ, StarfishConfig  # noqa: F401

starfish/core/__init__.py

@@ -0,0 +1,16 @@
+# deal with numpy import warnings due to cython
+# See: https://stackoverflow.com/questions/40845304/
+#      runtimewarning-numpy-dtype-size-changed-may-indicate-binary-incompatibility)
+import warnings
+warnings.filterwarnings("ignore", message="numpy.dtype size changed")  # noqa
+warnings.filterwarnings("ignore", message="numpy.ufunc size changed")  # noqa
+
+# generated version number and commit hash
+from ._version import get_versions
+
+
+# NOTE: if we move to python 3.7, we can produce this value at call time via __getattr__
+version = get_versions()['version']
+is_release_tag = None
+if "+" not in str(version):
+    is_release_tag = f"Release: {version}"

starfish/_display.py → starfish/core/_display.py

@@ -5,9 +5,9 @@
 
 import numpy as np
 
-from starfish.imagestack.imagestack import ImageStack
-from starfish.intensity_table.intensity_table import IntensityTable
-from starfish.types import Axes, Features
+from starfish.core.imagestack.imagestack import ImageStack
+from starfish.core.intensity_table.intensity_table import IntensityTable
+from starfish.core.types import Axes, Features
 
 try:
     with warnings.catch_warnings():