Convert ecoscope.base classes to dataframe accessors

[atmorling]

Opening this as a draft to get eyes on:

• Relocations and Trajectory are now dataframe accessors
• Removed EcoDataFrame / SpeedDataFrame
• _straighttrack_properties is now StraighttrackMixin and available to both Relocations and Trajectory
• Removed custom cachedproperty in favour of built-in cached_property
• Move analysis.proximity into Trajectory
• Removes upper bound version pin on geopandas and numpy

• closes Support Geopandas >= 0.14.3 #118
• closes Replace custom cachedproperty with built-in cached_property? #153
• closes Use pyogrio for gpd.read_file() #155
• closes Can calculate_proximity be a function on Trajectory ? #157
• closes Support numpy>2 #251
• closes Deprecate Speed Dataframe #188
• closes Align .github/workflows to ecoscope-workflows #247

Tasks remaining:

• Update docstrings
• Update notebooks
• Re-add add_speedmap logic in a more generalised way
• Fix Github CI - this is failing due to resolving geopandas<0.14.2, unsure why as yet

[atmorling]

The use of relocations/trajectories used to look like:

trajectory = ecoscope.base.Trajectory.from_relocations(movebank_relocations)

With accessors this is now:

trajectory = movebank_relocations.trajectories.from_relocations()

The main change I want to advertise/socialise is that this PR makes a choice to have all accessor methods that used to return a Relocations/Trajectory instance now return a gpd.GeoDataFrame
The reason for this is IMO, this makes the using the accessors in conjunction with regular pandas/geopandas methods feel more consistent.

For example, by returning a GDF, getting turn angle looks like :

#all steps return a gdf
trajectory = movebank_relocations.trajectories.from_relocations()
trajectory = trajectory.loc[trajectory.groupby_col == "Habiba"]
trajectory["heading"] = [0, 90, 120, 60, 300]
turn_angle = trajectory.trajectories.get_turn_angle()

vs returning self (an instance of either Relocations or Trajectory):

trajectory = movebank_relocations.trajectories.from_relocations() 
# no longer a gdf
trajectory = trajectory.gdf.loc[trajectory.gdf.groupby_col == "Habiba"] 
trajectory.gdf["heading"] = [0, 90, 120, 60, 300]
turn_angle = trajectory.get_turn_angle()

[cisaacstern]

Just getting a few comments out to start. More to follow!

[cisaacstern]

Love that this is now possible.

Do we want to be more opinionated about typing here, perhaps via pandera schemas?

Certainly the majority of gpd.GeoDataFrames will not work if passed here.

Not necessarily a question to be solved by this PR, but something to consider as a follow-on perhaps.

[cisaacstern]

Another way of putting this, if this can only operate on Trajectories, than it should be a method (i.e. accessor) on a Trajectory. (Which is the accessors paradigm, is a GeoDataFrame that adheres to a validated schema.)

[cisaacstern]

traj = ...  # but, how do we get this? 🤷 

traj.ecoscope.calculate_etd()

[cisaacstern]

plain_gdf = ...

traj = plain_gdf.ecoscope.EcoTrajectory()
turn_angle = traj.ecotrajectory.get_turn_angle()
etd = traj.ecotrajectory.calculate_etd()

🤔

[cisaacstern]

(Typing for alex...)

plain_gdf.EcoscopeBase.init()
inited_gdf.relocations.thing

[cisaacstern]

from typing import TypeVar

import pandera as pa
import pandas as pd

S = TypeVar("S")


class RelocationsSchema(pa.Schema): ...

class TrajectorySchema(pa.Schema): ...

class GDFWithSchema(Generic[S]):  ...


@pd.api.extensions.register_dataframe_accessor("ecoscope")
class ecoscope():

    def __init__(self, pandas_obj):
        assert isinstance(obj, gpd.GeoDataFrame)
        self._gdf = pandas_obj

    def Relocations(..., parser=...) -> GDFWithSchema[RelocationsSchema]: 
        # possibly coerce to schema here

        assert pa.validate(self._gdf, RelocationsSchema)
        return self._gdf

    def is_trajectory():
        return pa.validate(self._gdf, TrajectorySchema)

    def Trajectory(..., parser=...) -> GDFWithSchema[TrajectorySchema]:
        relocs = self.Relocations(parser=parser)
        ...
        
@pd.api.extensions.register_dataframe_accessor("trajectory")
class trajectory():

    def __init__(self, pandas_obj):
        pa.validate(self._gdf, TrajectorySchema)
        self._gdf = pandas_obj

    def get_turn_angle(...) ...:

    def calculate_etd(...) ...:

@pd.api.extensions.register_dataframe_accessor("is_trajectory")
class is_trajectory():
    def __call__(self) -> bool:
        return pa.validate(self._gdf, TrajectorySchema)

[cisaacstern]

plain_gdf = ...

reloc = plain_gdf.ecoscope.Relocations()
traj = reloc.ecoscope.Trajectory()

# ~ OR ~

traj = plain_gdf.ecoscope.Trajectory(parser=...)


traj.trajectory.get_turn_angle()
traj.trajectory.calculate_etd()

...

if not plain_gdf.is_trajectory(): ... # can accessors implement __call__()?

# ~ OR ~

if not plain_gdf.ecoscope.is_trajectory(): ...

plain_gdf.trajectory.get_turn_angle()  # -> validation error

[cisaacstern]

Nice that's a much more intelligible separation between base environment and package under test.

[atmorling]

Just to summarise the conversation with @cisaacstern, let's hold off on merging this for now and have a deeper discussion about how the core API is structured.

The main things to hash out are

• With accessors, how do we validate that when we call random_gdf.trajectory.get_turn_angle(), that random_gdf conforms to our notion of a "Trajectory"
• Can roll analysis module methods that require Relocation/Trajectory "objects" into accessors as well?

[atmorling]

I'm going to close this issue in favour of the discussed rework that includes much broader API changes than described here. See https://github.com/wildlife-dynamics/compose/issues/27 for more info.

I've split some of the smaller changes in this PR that don't strictly relate to the core change out into their own PRs, rather than deferring them until the broader API change is complete.

• remove custom cached prop and replace with builtin #293
• remove SpeedDataframe and Speedmap #294
• Explicit pip install step in CI #295