diff --git a/docs/api.rst b/docs/api.rst index ce01c902..6eff39dd 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -1,3 +1,5 @@ +.. currentmodule:: geometric_features + ############# API reference ############# @@ -9,8 +11,6 @@ the documentation. Command-line scripts ==================== -.. currentmodule:: geometric_features.__main__ - .. autosummary:: :toctree: generated/ @@ -28,22 +28,46 @@ Command-line scripts Python package ============== -.. currentmodule:: geometric_features.geometric_features +Reading Geometric Features +-------------------------- .. autosummary:: :toctree: generated/ GeometricFeatures GeometricFeatures.read + +Splitting new data into Geometric Features +------------------------------------------ + +.. autosummary:: + :toctree: generated/ + GeometricFeatures.split + write_feature_names_and_tags -.. currentmodule:: geometric_features.feature_collection +Reading a Feature Collection +---------------------------- .. autosummary:: :toctree: generated/ read_feature_collection + +Creating a Feature Collection +----------------------------- + +.. autosummary:: + :toctree: generated/ + FeatureCollection + +Manipulating a Feature Collection +--------------------------------- + +.. autosummary:: + :toctree: generated/ + FeatureCollection.add_feature FeatureCollection.merge FeatureCollection.tag diff --git a/docs/feature_collection.rst b/docs/feature_collection.rst index f028b48a..020d25c0 100644 --- a/docs/feature_collection.rst +++ b/docs/feature_collection.rst @@ -11,7 +11,7 @@ Reading in Features ------------------- A ``FeatureCollection`` can be read from a file with the function -:func:`geometric_features.feature_collection.read_feature_collection`: +:func:`geometric_features.read_feature_collection`: .. code-block:: python @@ -23,7 +23,7 @@ Add a Feature ------------- To add a single feature to a ``FeatureColleciton``, use -:meth:`geometric_features.feature_collection.FeatureCollection.add_feature`: +:meth:`geometric_features.FeatureCollection.add_feature`: .. code-block:: python @@ -35,7 +35,7 @@ Merging Features ---------------- A ``FeatureCollection`` ``fc2`` can be merged into another colleciton ``fc1`` - with :meth:`geometric_features.feature_collection.FeatureCollection.merge`: + with :meth:`geometric_features.FeatureCollection.merge`: .. code-block:: python @@ -48,7 +48,7 @@ Plotting Features ----------------- A ``FeatureCollection`` can be plotted on a given map projeciton with -:meth:`geometric_features.feature_collection.FeatureCollection.plot`: +:meth:`geometric_features.FeatureCollection.plot`: .. code-block:: python @@ -63,7 +63,7 @@ Tag Features ------------ All the features in a ``FeatureCollection`` can be tagged with one or more tags -using :meth:`geometric_features.feature_collection.FeatureCollection.tag`: +using :meth:`geometric_features.FeatureCollection.tag`: .. code-block:: python @@ -78,7 +78,7 @@ Writing out Features -------------------- To write out a ``FeatureCollection`` to a ``geojson`` file, call -:meth:`geometric_features.feature_collection.FeatureCollection.to_geojson` +:meth:`geometric_features.FeatureCollection.to_geojson` .. code-block:: python @@ -88,7 +88,7 @@ Set a Group Name ---------------- To set the ``groupName`` property of a ``FeatureCollection``, call -:meth:`geometric_features.feature_collection.FeatureCollection.set_group_name`. +:meth:`geometric_features.FeatureCollection.set_group_name`. .. code-block:: python @@ -105,7 +105,7 @@ Combine Features Features in a ``FeatureCollection`` can be combined (fused together into a single feature) using -:meth:`geometric_features.feature_collection.FeatureCollection.combine`: +:meth:`geometric_features.FeatureCollection.combine`: .. code-block:: python @@ -117,7 +117,7 @@ Difference Features Features in a ``FeatureCollection`` can be masked with one or more masking features from another ``FeatureCollection`` using -:meth:`geometric_features.feature_collection.FeatureCollection.difference`: +:meth:`geometric_features.FeatureCollection.difference`: .. code-block:: python @@ -132,7 +132,7 @@ Simplify Features Sometimes, features are made up of segments or polygons with tiny edges that add little relevant detail to the features but make the files describing them needlessly large. In such cases, the features can be simplified by calling -:meth:`geometric_features.feature_collection.FeatureCollection.simplify` with +:meth:`geometric_features.FeatureCollection.simplify` with and appropriate length scale (in degrees latitude/longitude) over which the feature may be modified to make it simpler. If a length scale of zero is used, the feature will be simplified without any modification tot he shape @@ -153,7 +153,7 @@ provides a bit of a hack for removing a tiny sliver of the feature around the antimeridian so that the resulting shape remians between -180 and 180 degrees longitude. -:meth:`geometric_features.feature_collection.FeatureCollection.fix_antimeridian` +:meth:`geometric_features.FeatureCollection.fix_antimeridian` .. code-block:: python diff --git a/docs/geometric_data.rst b/docs/geometric_data.rst index 43e498ef..f09edeae 100644 --- a/docs/geometric_data.rst +++ b/docs/geometric_data.rst @@ -5,19 +5,22 @@ Geometric Data The the overarching purpose of ``geometric_features`` is to facilitate access to and manipulation of the geometric data in the repository. This data is -currently divided across 5 components, ``bedmap2``, ``iceshelves``, -``landice``, ``natural_earth``, and ``ocean``. +currently divided across 6 components, ``bedmachine``, ``bedmap2``, +``iceshelves``, ``landice``, ``natural_earth``, and ``ocean``. Components ---------- -bedmap2 -^^^^^^^ +bedmachine and bedmap2 +^^^^^^^^^^^^^^^^^^^^^^ -This component defines two "coastlines" between the Antarctic continent and -the ocean. One exclues the cavity under ice shelves while the other includes -them. The dataset used to define these coastlines is Bedmap2 -(`Fretwell et al. 2016`_). +These components each define two "coastlines" between the Antarctic continent +and the ocean. One excludes the cavity under ice shelves while the other +includes them. The ``bedmachine`` component uses the BedMachine Antarctica +dataset +(`Morlighem et al. 2020 `_) +to define the coastlines, while the ``bedmap2`` dataset is based on Bedmap2 +(`Fretwell et al. 2016 `_). iceshelves ^^^^^^^^^^ @@ -176,7 +179,7 @@ Here are two simple examples of features from the repository: ] } -.. _`Fretwell et al. 2016`: http://www.the-cryosphere.net/7/375/2013/ + .. _`IMBIE1 Basins`: http://imbie.org/imbie-2016/drainage-basins/ .. _`Natural Earth`: http://www.naturalearthdata.com/ .. _`International Hydrographic Organisation`: http://www.marineregions.org/downloads.php#iho diff --git a/geometric_features/__init__.py b/geometric_features/__init__.py index 2a6a2be3..de18f004 100644 --- a/geometric_features/__init__.py +++ b/geometric_features/__init__.py @@ -6,5 +6,12 @@ from geometric_features.feature_collection import FeatureCollection, \ read_feature_collection +from geometric_features.__main__ import combine_features, difference_features, \ + fix_features_at_antimeridian, merge_features, plot_features, \ + set_group_name, split_features, simplify_features, tag_features + +from geometric_features.utils import write_feature_names_and_tags + + __version_info__ = (0, 1, 11) __version__ = '.'.join(str(vi) for vi in __version_info__) diff --git a/geometric_features/feature_collection.py b/geometric_features/feature_collection.py index 627a2b90..de9d2508 100644 --- a/geometric_features/feature_collection.py +++ b/geometric_features/feature_collection.py @@ -35,7 +35,7 @@ def read_feature_collection(fileName): Returns ------- - fc : ``FeatureCollection`` + fc : geometric_features.FeatureCollection The feature collection read in ''' # Authors @@ -121,7 +121,7 @@ def merge(self, other): Parameters ---------- - other : ``FeatureCollection`` + other : geometric_features.FeatureCollection The other feature collection ''' # Authors @@ -184,7 +184,7 @@ def combine(self, featureName): Returns ------- - fc : ``FeatureCollection`` + fc : geometric_features.FeatureCollection A new feature collection with a single feature with the combined geometry @@ -242,7 +242,7 @@ def difference(self, maskingFC, show_progress=False): Parameters ---------- - maskingFC : ``FeatureCollection``` + maskingFC : geometric_features.FeatureCollection Another collection of one or more features to use as masks show_progress : bool @@ -250,7 +250,7 @@ def difference(self, maskingFC, show_progress=False): Returns ------- - fc : ``FeatureCollection`` + fc : geometric_features.FeatureCollection A new feature collection with a single feature with the geometry masked ''' @@ -321,7 +321,7 @@ def fix_antimeridian(self): Returns ------- - fc : ``FeatureCollection`` + fc : geometric_features.FeatureCollection A new feature collection with the antimeridian handled correctly ''' # Authors @@ -355,7 +355,7 @@ def simplify(self, tolerance=0.0): Returns ------- - fc : ``FeatureCollection`` + fc : geometric_features.FeatureCollection A new feature collection with simplified geometries ''' # Authors diff --git a/geometric_features/geometric_features.py b/geometric_features/geometric_features.py index 60fe7258..f052433e 100644 --- a/geometric_features/geometric_features.py +++ b/geometric_features/geometric_features.py @@ -100,7 +100,7 @@ def read(self, componentName, objectType, featureNames=None, tags=None, Returns ------- - fc : ``FeatureCollection`` + fc : geometric_features.FeatureCollection The feature collection read in ''' # Authors @@ -125,7 +125,7 @@ def split(self, fc, destinationDir=None): Parameters ---------- - fc : ``FeatureCollection`` + fc : geometric_features.FeatureCollection The feature collection to split destinationDir : str, optional @@ -134,7 +134,7 @@ def split(self, fc, destinationDir=None): Returns ------- - fc : ``FeatureCollection`` + fc : geometric_features.FeatureCollection The feature collection read in ''' # Authors diff --git a/geometric_features/test/test_set_group_name.py b/geometric_features/test/test_set_group_name.py index a7220ce1..ccc333bb 100644 --- a/geometric_features/test/test_set_group_name.py +++ b/geometric_features/test/test_set_group_name.py @@ -22,7 +22,7 @@ def test_assign_groupname(self, componentName='ocean', objectType='region', Parameters ---------- - componentName : {'bedmap2', 'iceshelves', 'landice', 'natural_earth', 'ocean'}, optional + componentName : {'bedmachine', 'bedmap2', 'iceshelves', 'landice', 'natural_earth', 'ocean'}, optional The component from which to retieve the feature objectType : {'point', 'transect', 'region'}, optional