:py:mod:`ecoscope.base.base` ============================ .. py:module:: ecoscope.base.base Module Contents --------------- .. py:class:: EcoDataFrame(data=None, *args, **kwargs) Bases: :py:obj:`geopandas.GeoDataFrame` `EcoDataFrame` extends `geopandas.GeoDataFrame` to provide customizations and allow for simpler extension. .. py:property:: _constructor Used when a manipulation result has the same dimensions as the original. .. py:method:: __getitem__(key) If the result is a column containing only 'geometry', return a GeoSeries. If it's a DataFrame with any columns of GeometryDtype, return a GeoDataFrame. .. py:method:: from_file(filename, **kwargs) :classmethod: Alternate constructor to create a ``GeoDataFrame`` from a file. It is recommended to use :func:`geopandas.read_file` instead. Can load a ``GeoDataFrame`` from a file in any format recognized by `fiona`. See http://fiona.readthedocs.io/en/latest/manual.html for details. :param filename: File path or file handle to read from. Depending on which kwargs are included, the content of filename may vary. See http://fiona.readthedocs.io/en/latest/README.html#usage for usage details. :type filename: str :param kwargs: These arguments are passed to fiona.open, and can be used to access multi-layer data, data stored within archives (zip files), etc. :type kwargs: key-word arguments .. rubric:: Examples >>> import geodatasets >>> path = geodatasets.get_path('nybb') >>> gdf = geopandas.GeoDataFrame.from_file(path) >>> gdf # doctest: +SKIP BoroCode BoroName Shape_Leng Shape_Area geometry 0 5 Staten Island 330470.010332 1.623820e+09 MULTIPOLYGON (((970217.022 145643.332, 970227.... 1 4 Queens 896344.047763 3.045213e+09 MULTIPOLYGON (((1029606.077 156073.814, 102957... 2 3 Brooklyn 741080.523166 1.937479e+09 MULTIPOLYGON (((1021176.479 151374.797, 102100... 3 1 Manhattan 359299.096471 6.364715e+08 MULTIPOLYGON (((981219.056 188655.316, 980940.... 4 2 Bronx 464392.991824 1.186925e+09 MULTIPOLYGON (((1012821.806 229228.265, 101278... The recommended method of reading files is :func:`geopandas.read_file`: >>> gdf = geopandas.read_file(path) .. seealso:: :obj:`read_file` read file to GeoDataFame :obj:`GeoDataFrame.to_file` write GeoDataFrame to file .. py:method:: from_features(features, **kwargs) :classmethod: Alternate constructor to create GeoDataFrame from an iterable of features or a feature collection. :param features: - Iterable of features, where each element must be a feature dictionary or implement the __geo_interface__. - Feature collection, where the 'features' key contains an iterable of features. - Object holding a feature collection that implements the ``__geo_interface__``. :param crs: Coordinate reference system to set on the resulting frame. :type crs: str or dict (optional) :param columns: Optionally specify the column names to include in the output frame. This does not overwrite the property names of the input, but can ensure a consistent output format. :type columns: list of column names, optional :rtype: GeoDataFrame .. rubric:: Notes For more information about the ``__geo_interface__``, see https://gist.github.com/sgillies/2217756 .. rubric:: Examples >>> feature_coll = { ... "type": "FeatureCollection", ... "features": [ ... { ... "id": "0", ... "type": "Feature", ... "properties": {"col1": "name1"}, ... "geometry": {"type": "Point", "coordinates": (1.0, 2.0)}, ... "bbox": (1.0, 2.0, 1.0, 2.0), ... }, ... { ... "id": "1", ... "type": "Feature", ... "properties": {"col1": "name2"}, ... "geometry": {"type": "Point", "coordinates": (2.0, 1.0)}, ... "bbox": (2.0, 1.0, 2.0, 1.0), ... }, ... ], ... "bbox": (1.0, 1.0, 2.0, 2.0), ... } >>> df = geopandas.GeoDataFrame.from_features(feature_coll) >>> df geometry col1 0 POINT (1.00000 2.00000) name1 1 POINT (2.00000 1.00000) name2 .. py:method:: __finalize__(*args, **kwargs) propagate metadata from other to self .. py:method:: astype(*args, **kwargs) Cast a pandas object to a specified dtype ``dtype``. Returns a GeoDataFrame when the geometry column is kept as geometries, otherwise returns a pandas DataFrame. See the pandas.DataFrame.astype docstring for more details. :rtype: GeoDataFrame or DataFrame .. py:method:: merge(*args, **kwargs) Merge two ``GeoDataFrame`` objects with a database-style join. Returns a ``GeoDataFrame`` if a geometry column is present; otherwise, returns a pandas ``DataFrame``. Returns ------- GeoDataFrame or DataFrame Notes ----- The extra arguments ``*args`` and keyword arguments ``**kwargs`` are passed to DataFrame.merge. See https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas\ .DataFrame.merge.html for more details. .. py:method:: dissolve(*args, **kwargs) Dissolve geometries within `groupby` into single observation. This is accomplished by applying the `unary_union` method to all geometries within a groupself. Observations associated with each `groupby` group will be aggregated using the `aggfunc`. :param by: Column(s) whose values define the groups to be dissolved. If None, the entire GeoDataFrame is considered as a single group. If a list-like object is provided, the values in the list are treated as categorical labels, and polygons will be combined based on the equality of these categorical labels. :type by: str or list-like, default None :param aggfunc: Aggregation function for manipulation of data associated with each group. Passed to pandas `groupby.agg` method. Accepted combinations are: - function - string function name - list of functions and/or function names, e.g. [np.sum, 'mean'] - dict of axis labels -> functions, function names or list of such. :type aggfunc: function or string, default "first" :param as_index: If true, groupby columns become index of result. :type as_index: boolean, default True :param level: If the axis is a MultiIndex (hierarchical), group by a particular level or levels. .. versionadded:: 0.9.0 :type level: int or str or sequence of int or sequence of str, default None :param sort: Sort group keys. Get better performance by turning this off. Note this does not influence the order of observations within each group. Groupby preserves the order of rows within each group. .. versionadded:: 0.9.0 :type sort: bool, default True :param observed: This only applies if any of the groupers are Categoricals. If True: only show observed values for categorical groupers. If False: show all values for categorical groupers. .. versionadded:: 0.9.0 :type observed: bool, default False :param dropna: If True, and if group keys contain NA values, NA values together with row/column will be dropped. If False, NA values will also be treated as the key in groups. .. versionadded:: 0.9.0 :type dropna: bool, default True :param \*\*kwargs: Keyword arguments to be passed to the pandas `DataFrameGroupby.agg` method which is used by `dissolve`. In particular, `numeric_only` may be supplied, which will be required in pandas 2.0 for certain aggfuncs. .. versionadded:: 0.13.0 :rtype: GeoDataFrame .. rubric:: Examples >>> from shapely.geometry import Point >>> d = { ... "col1": ["name1", "name2", "name1"], ... "geometry": [Point(1, 2), Point(2, 1), Point(0, 1)], ... } >>> gdf = geopandas.GeoDataFrame(d, crs=4326) >>> gdf col1 geometry 0 name1 POINT (1.00000 2.00000) 1 name2 POINT (2.00000 1.00000) 2 name1 POINT (0.00000 1.00000) >>> dissolved = gdf.dissolve('col1') >>> dissolved # doctest: +SKIP geometry col1 name1 MULTIPOINT (0.00000 1.00000, 1.00000 2.00000) name2 POINT (2.00000 1.00000) .. seealso:: :obj:`GeoDataFrame.explode` explode multi-part geometries into single geometries .. py:method:: explode(*args, **kwargs) Explode multi-part geometries into multiple single geometries. Each row containing a multi-part geometry will be split into multiple rows with single geometries, thereby increasing the vertical size of the GeoDataFrame. :param column: Column to explode. In the case of a geometry column, multi-part geometries are converted to single-part. If None, the active geometry column is used. :type column: string, default None :param ignore_index: If True, the resulting index will be labelled 0, 1, …, n - 1, ignoring `index_parts`. :type ignore_index: bool, default False :param index_parts: If True, the resulting index will be a multi-index (original index with an additional level indicating the multiple geometries: a new zero-based index for each single part geometry per multi-part geometry). :type index_parts: boolean, default True :returns: Exploded geodataframe with each single geometry as a separate entry in the geodataframe. :rtype: GeoDataFrame .. rubric:: Examples >>> from shapely.geometry import MultiPoint >>> d = { ... "col1": ["name1", "name2"], ... "geometry": [ ... MultiPoint([(1, 2), (3, 4)]), ... MultiPoint([(2, 1), (0, 0)]), ... ], ... } >>> gdf = geopandas.GeoDataFrame(d, crs=4326) >>> gdf col1 geometry 0 name1 MULTIPOINT (1.00000 2.00000, 3.00000 4.00000) 1 name2 MULTIPOINT (2.00000 1.00000, 0.00000 0.00000) >>> exploded = gdf.explode(index_parts=True) >>> exploded col1 geometry 0 0 name1 POINT (1.00000 2.00000) 1 name1 POINT (3.00000 4.00000) 1 0 name2 POINT (2.00000 1.00000) 1 name2 POINT (0.00000 0.00000) >>> exploded = gdf.explode(index_parts=False) >>> exploded col1 geometry 0 name1 POINT (1.00000 2.00000) 0 name1 POINT (3.00000 4.00000) 1 name2 POINT (2.00000 1.00000) 1 name2 POINT (0.00000 0.00000) >>> exploded = gdf.explode(ignore_index=True) >>> exploded col1 geometry 0 name1 POINT (1.00000 2.00000) 1 name1 POINT (3.00000 4.00000) 2 name2 POINT (2.00000 1.00000) 3 name2 POINT (0.00000 0.00000) .. seealso:: :obj:`GeoDataFrame.dissolve` dissolve geometries into a single observation. .. py:method:: plot(*args, **kwargs) .. py:method:: reset_filter(inplace=False) .. py:method:: remove_filtered(inplace=False) .. py:class:: Relocations(data=None, *args, **kwargs) Bases: :py:obj:`EcoDataFrame` Relocation is a model for a set of fixes from a given subject. Because fixes are temporal, they can be ordered asc or desc. The additional_data dict can contain info specific to the subject and relocations: name, type, region, sex etc. These values are applicable to all fixes in the relocations array. If they vary, then they should be put into each fix's additional_data dict. .. py:method:: from_gdf(gdf, groupby_col=None, time_col='fixtime', uuid_col=None, **kwargs) :classmethod: :param gdf: Observations data :type gdf: GeoDataFrame :param groupby_col: Name of `gdf` column of identities to treat as separate individuals. Usually `subject_id`. Default is treating the gdf as being of a single individual. :type groupby_col: str, optional :param time_col: Name of `gdf` column containing relocation times. Default is 'fixtime'. :type time_col: str, optional :param uuid_col: Name of `gdf` column of row identities. Used as index. Default is existing index. :type uuid_col: str, optional .. py:method:: _apply_speedfilter(df, fix_filter) :staticmethod: .. py:method:: _apply_distfilter(df, fix_filter) :staticmethod: .. py:method:: apply_reloc_filter(fix_filter=None, inplace=False) Apply a given filter by marking the fix junk_status based on the conditions of a filter .. py:method:: distance_from_centroid() .. py:method:: cluster_radius() The cluster radius is the largest distance between a point in the relocationss and the centroid of the relocationss .. py:method:: cluster_std_dev() The cluster standard deviation is the standard deviation of the radii from the centroid to each point making up the cluster .. py:method:: threshold_point_count(threshold_dist) Counts the number of points in the cluster that are within a threshold distance of the geographic centre .. py:method:: apply_threshold_filter(threshold_dist_meters=float('Inf')) .. py:class:: Trajectory(data=None, *args, **kwargs) Bases: :py:obj:`EcoDataFrame` A trajectory represents a time-ordered collection of segments. Currently only straight track segments exist. It is based on an underlying relocs object that is the point representation .. py:method:: from_relocations(gdf, *args, **kwargs) :classmethod: Create Trajectory class from Relocation dataframe. :param gdf: Relocation geodataframe with relevant columns :type gdf: Geodataframe :param args: :param kwargs: :rtype: Trajectory .. py:method:: get_displacement() Get displacement in meters between first and final fixes. .. py:method:: get_tortuosity() Get tortuosity for dataframe defined as distance traveled divided by displacement between first and final points. .. py:method:: get_daynight_ratio(n_grid_points=150) :param n_grid_points: The number of grid points on which to search for the horizon crossings of the target over a 24-hour period, default is 150 which yields rise time precisions better than one minute. https://github.com/astropy/astroplan/pull/424 :type n_grid_points: int (optional) :returns: Daynight ratio for each unique individual subject in the grouby_col column. :rtype: pd.Series .. py:method:: _create_multitraj(df) :staticmethod: .. py:method:: _create_trajsegments(gdf) :staticmethod: .. py:method:: apply_traj_filter(traj_seg_filter, inplace=False) .. py:method:: get_turn_angle() .. py:method:: upsample(freq) Interpolate to create upsampled Relocations :param freq: Sampling frequency for new Relocations object :type freq: str, pd.Timedelta or pd.DateOffset :returns: **relocs** :rtype: ecoscope.base.Relocations .. py:method:: to_relocations() Converts a Trajectory object to a Relocations object. :rtype: ecoscope.base.Relocations .. py:method:: downsample(freq, tolerance='0S', interpolation=False) Function to downsample relocations. :param freq: Downsampling frequency for new Relocations object :type freq: str, pd.Timedelta or pd.DateOffset :param tolerance: Tolerance on the downsampling frequency :type tolerance: str, pd.Timedelta or pd.DateOffset :param interpolation: If true, interpolates locations on the whole trajectory :type interpolation: bool, optional :rtype: ecoscope.base.Relocations .. py:method:: _straighttrack_properties(df) :staticmethod: Private function used by Trajectory class.