ecoscope.base.base#

Module Contents#

class ecoscope.base.base.EcoDataFrame(data=None, *args, **kwargs)[source]#

Bases: geopandas.GeoDataFrame

EcoDataFrame extends geopandas.GeoDataFrame to provide customizations and allow for simpler extension.

property _constructor#

Used when a manipulation result has the same dimensions as the original.

__getitem__(key)[source]#

If the result is a column containing only ‘geometry’, return a GeoSeries. If it’s a DataFrame with a ‘geometry’ column, return a GeoDataFrame.

classmethod from_file(filename, **kwargs)[source]#

Alternate constructor to create a GeoDataFrame from a file.

It is recommended to use 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.

Parameters

  • filename (str) – 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.

  • kwargs (key-word arguments) – These arguments are passed to fiona.open, and can be used to access multi-layer data, data stored within archives (zip files), etc.

Examples

>>> path = geopandas.datasets.get_path('nybb')
>>> gdf = geopandas.GeoDataFrame.from_file(path)
>>> gdf  
   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 geopandas.read_file():

>>> gdf = geopandas.read_file(path)

See also

read_file

read file to GeoDataFame

GeoDataFrame.to_file

write GeoDataFrame to file

classmethod from_features(features, **kwargs)[source]#

Alternate constructor to create GeoDataFrame from an iterable of features or a feature collection.

Parameters

  • 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__.

  • crs (str or dict (optional)) – Coordinate reference system to set on the resulting frame.

  • columns (list of column names, optional) – 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.

Return type

GeoDataFrame

Notes

For more information about the __geo_interface__, see https://gist.github.com/sgillies/2217756

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
__finalize__(*args, **kwargs)[source]#

propagate metadata from other to self

astype(*args, **kwargs)[source]#

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.

Return type

GeoDataFrame or DataFrame

merge(*args, **kwargs)[source]#

Merge two GeoDataFrame objects with a database-style join.

Returns a GeoDataFrame if a geometry column is present; otherwise, returns a pandas DataFrame.

Return type

GeoDataFrame or DataFrame

Notes

The extra arguments *args and keyword arguments **kwargs are passed to DataFrame.merge.

Reference#

https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.merge.html

dissolve(*args, **kwargs)[source]#

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.

Parameters

  • by (string, default None) – Column whose values define groups to be dissolved. If None, whole GeoDataFrame is considered a single group.

  • aggfunc (function or string, default "first") – Aggregation function for manipulation of data associated with each group. Passed to pandas groupby.agg method.

  • as_index (boolean, default True) – If true, groupby columns become index of result.

  • level (int or str or sequence of int or sequence of str, default None) –

    If the axis is a MultiIndex (hierarchical), group by a particular level or levels.

    New in version 0.9.0.

  • sort (bool, default True) –

    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.

    New in version 0.9.0.

  • observed (bool, default False) –

    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.

    New in version 0.9.0.

  • dropna (bool, default True) –

    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.

    This parameter is not supported for pandas < 1.1.0. A warning will be emitted for earlier pandas versions if a non-default value is given for this parameter.

    New in version 0.9.0.

Return type

GeoDataFrame

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  
                                            geometry
col1
name1  MULTIPOINT (0.00000 1.00000, 1.00000 2.00000)
name2                        POINT (2.00000 1.00000)

See also

GeoDataFrame.explode

explode muti-part geometries into single geometries

explode(*args, **kwargs)[source]#

Explode muti-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.

Note

ignore_index requires pandas 1.1.0 or newer.

Parameters

  • column (string, default None) – 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.

  • ignore_index (bool, default False) – If True, the resulting index will be labelled 0, 1, …, n - 1, ignoring index_parts.

  • index_parts (boolean, default True) – 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).

Returns

Exploded geodataframe with each single geometry as a separate entry in the geodataframe.

Return type

GeoDataFrame

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)

See also

GeoDataFrame.dissolve

dissolve geometries into a single observation.

plot(*args, **kwargs)[source]#
reset_filter(inplace=False)[source]#
remove_filtered(inplace=False)[source]#
class ecoscope.base.base.Relocations(data=None, *args, **kwargs)[source]#

Bases: 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.

classmethod from_gdf(gdf, groupby_col=None, time_col='fixtime', uuid_col=None, **kwargs)[source]#
Parameters

  • gdf (GeoDataFrame) – Observations data

  • groupby_col (str, optional) – 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.

  • time_col (str, optional) – Name of gdf column containing relocation times. Default is ‘fixtime’.

  • uuid_col (str, optional) – Name of gdf column of row identities. Used as index. Default is existing index.

static _apply_speedfilter(df, fix_filter)[source]#
static _apply_distfilter(df, fix_filter)[source]#
apply_reloc_filter(fix_filter=None, inplace=False)[source]#

Apply a given filter by marking the fix junk_status based on the conditions of a filter

distance_from_centroid()#
cluster_radius()#

The cluster radius is the largest distance between a point in the relocationss and the centroid of the relocationss

cluster_std_dev()#

The cluster standard deviation is the standard deviation of the radii from the centroid to each point making up the cluster

threshold_point_count(threshold_dist)[source]#

Counts the number of points in the cluster that are within a threshold distance of the geographic centre

apply_threshold_filter(threshold_dist_meters=float('Inf'))[source]#
class ecoscope.base.base.Trajectory(data=None, *args, **kwargs)[source]#

Bases: 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

classmethod from_relocations(gdf, *args, **kwargs)[source]#

Create Trajectory class from Relocation dataframe.

Parameters

  • gdf (Geodataframe) – Relocation geodataframe with relevant columns

  • args –

  • kwargs –

Return type

Trajectory

get_displacement()[source]#

Get displacement in meters between first and final fixes.

get_tortuosity()[source]#

Get tortuosity for dataframe defined as distance traveled divided by displacement between first and final points.

get_daynight_ratio(n_grid_points=150)[source]#
Parameters

n_grid_points (int (optional)) –

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.

astropy/astroplan#424

Returns

Daynight ratio for each unique individual subject in the grouby_col column.

Return type

pd.Series

static _create_multitraj(df)[source]#
static _create_trajsegments(gdf)[source]#
apply_traj_filter(traj_seg_filter, inplace=False)[source]#
get_turn_angle()[source]#
upsample(freq)[source]#

Interpolate to create upsampled Relocations

Parameters

freq (str, pd.Timedelta or pd.DateOffset) – Sampling frequency for new Relocations object

Returns

relocs

Return type

ecoscope.base.Relocations

to_relocations()[source]#

Converts a Trajectory object to a Relocations object.

Return type

ecoscope.base.Relocations

downsample(freq, tolerance='0S', interpolation=False)[source]#

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

Return type

ecoscope.base.Relocations

static _straighttrack_properties(df)[source]#

Private function used by Trajectory class.

Parameters

df (geopandas.GeoDataFrame) –