xyt

Name	xyt JSON
Version	0.1.2 JSON
	download
home_page
Summary	xyt is a python package for processing raw gps data into mobility data. xyt offers privacy-based capabilities and aims to provide a plug-and-play pipeline to leverage gps data.
upload_time	2023-12-04 15:30:18
maintainer	Marc-Edouard Schultheiss
docs_url	None
author	Marc-Edouard Schultheiss
requires_python	>=3.6,<4.0
license	MIT
keywords	xyt gps mobility
VCS
bugtrack_url
requirements	No requirements were recorded.
Travis-CI	No Travis.
coveralls test coverage	No coveralls.

            # xyt

## Usage

Install the xyt library

```bash
pip install xyt
```

## Documentation

[Full documentation here](https://meschultheiss.github.io/xyt/py-modindex.html)

## Scientific methods

[More documentation here](https://situee.ch/articles/xyt/scientific-report)

## Input gps format

Here are some specific things to know regarding geodata processing

- CRS is important – this is the geographic projection system which is set to `EPSG:4327` (internatioinal standard, aka WGS 84) or `EPSG:2056`  (Swiss standard, aka CH1903+ / LV95) – please stick to WGS 84
- WGS 84 is in degrees, CH1903+ in in meter – this matters when computing distances, dbscna, etc.
- `datetimes`  are set to a specific time zone (UTC+1 for Switzerland)
- Typically there are three types of geometries:
    - `type==waypoints` is a shapely point() unlabeled i.e., raw gps data
    - `type==staypoint` is a shapely point() detected as an activity
    - `type==leg` is a shapely linestring() detected as a trip
- Waypoints typically have the following columns. Note that some other columns such as `<'detected_mode'>` or `<'detected_purpose'>` may be inferred from the gps data provider

```python
['user_id', 'type', 'tracked_at', 'latitude', 'longitude', 'accuracy']
```

- Leg and / or Staypoint df typically have the following columns :

```python
['user_id', 'type', 'started_at', 'finished_at', 'timezone',
		    'length_meters', 'detected_mode', 'purpose', 'geometry',
				'home_location', 'work_location']
```

## Keep in mind

- You work in degrees
- Write docstrings for documentation generation later on
- Document the structure of the input df so we know what column and column name we should find in the input df for each method
- Test the instances – without spending too much time on corner cases, we aim at a Minimum Viable Product here which will be further enhanced and maintained later on

## List of instances and ‘public’ methods

List of instances in the python library xyt:

```python
from xyt import FakeDataGenerator, GPSDataProcessor, GPSDataPrivacy, GPSAnalytics, GPStoGraph, GPStoActionspace, plot_gps_on_map
```

- `FakeDataGenerator()`

A fake gps data generator to play with the library without infringing on users’ privacy

```python
fakegps = FakeDataGenerator(location_name="Suisse", num_users=5, home_radius_km = 20)
waypoints = fakegps.generate_waypoints(num_rows=12, num_extra_od_points=10, max_displacement_meters = 10)
legs = fakegps.generate_legs(num_rows=12)
stays = fakegps.generate_staypoints(num_rows=12)
```

- `GPSDataProcessor()`

A geotagging instance to transform raw gps data into mobility data

```python
data_processor = GPSDataProcessor(radius=0.03)

poi_waypoints = data_processor.guess_home_work(waypoints_df, cell_size=0.3)
smoothed_df = data_processor.smooth(poi_waypoints, sigma=10)
segmented_df = data_processor.segment(smoothed_df)
mode_df = data_processor.mode_detection(segmented_df)
legs_ = data_processor.get_legs(df = mode_df)
```

- `plot_gps_on_map()`

A function to plot easily xyt’s instances outputs

```python
plot_gps_on_map(poi_waypoints, home_col='home_loc', work_col='work_loc')
```

- `GPSDataPrivacy()`

An instance to artificially degrade the data for privacy purposes

```python
data_privacy = GPSDataPrivacy()

df_obfuscated = data_privacy.obfuscate()
utility = data_privacy.get_obfuscation_utility()
df_aggergated = data_privacy.aggregate()
```

- `GPSAnalytics()`

An instance to perform space-based and time-based analytics on the mobility data

```python
metrics = GPSAnalytics()

metrics.check_inputs()
staypoint1 = metrics.split_overnight(staypoint)
staypoint2 = metrics.spatial_clustering(staypoint1)
extended_staypoint = metrics.get_metrics(staypoint2)
day_staypoint = metrics.get_daily_metrics(extended_staypoint)
```

- `GPStoGraph()`

An instance to abstract mobility diaries as a graph

```python
graphs = GPStoGraph()

multiday_graph = graphs.get_graphs(extended_staypoint)
graphs.plot_motif(multiday_graph)
graphs.plot_graph(multiday_graph)
motif_seq = graphs.motif_sequence(multiday_graph)
```

- `GPStoActionspace()`

An instance to generate key metrics characterizing the activity space for a more in-depth exploration of spatial familiarity.

```python
action_space = GPStoActionspace()

aggregation_method = 'user_id'  # Change this to 'user_id' or 'user_id_day'
act_spc, act_modified = action_space.compute_action_space(act, aggregation_method=aggregation_method)
mymap = action_space.plot_ellipses(act_spc, aggregation_method=aggregation_method)
action_space.covariance_matrix(action_space=act_spc)
action_space.plot_action_space(act, act_spc, user="CH16871", how="vignette", save=False)
action_space.plot_action_space(act, act_spc, user="CH16871", how="folium", save=False)
```

            

Raw data

            {
    "_id": null,
    "home_page": "",
    "name": "xyt",
    "maintainer": "Marc-Edouard Schultheiss",
    "docs_url": null,
    "requires_python": ">=3.6,<4.0",
    "maintainer_email": "meschultheiss@gmail.com",
    "keywords": "xyt,gps,mobility",
    "author": "Marc-Edouard Schultheiss",
    "author_email": "meschultheiss@gmail.com",
    "download_url": "https://files.pythonhosted.org/packages/33/bc/68c36bed148380f30f0c6aab5021e632dbf6dac1ebfca2eb8469a163c866/xyt-0.1.2.tar.gz",
    "platform": null,
    "description": "# xyt\n\n## Usage\n\nInstall the xyt library\n\n```bash\npip install xyt\n```\n\n## Documentation\n\n[Full documentation here](https://meschultheiss.github.io/xyt/py-modindex.html)\n\n## Scientific methods\n\n[More documentation here](https://situee.ch/articles/xyt/scientific-report)\n\n## Input gps format\n\nHere are some specific things to know regarding geodata processing\n\n- CRS is important \u2013 this is the geographic projection system which is set to `EPSG:4327` (internatioinal standard, aka WGS 84) or `EPSG:2056`  (Swiss standard, aka CH1903+ / LV95) \u2013 please stick to WGS 84\n- WGS 84 is in degrees, CH1903+ in in meter \u2013 this matters when computing distances, dbscna, etc.\n- `datetimes`  are set to a specific time zone (UTC+1 for Switzerland)\n- Typically there are three types of geometries:\n    - `type==waypoints` is a shapely point() unlabeled i.e., raw gps data\n    - `type==staypoint` is a shapely point() detected as an activity\n    - `type==leg` is a shapely linestring() detected as a trip\n- Waypoints typically have the following columns. Note that some other columns such as `<'detected_mode'>` or `<'detected_purpose'>` may be inferred from the gps data provider\n\n```python\n['user_id', 'type', 'tracked_at', 'latitude', 'longitude', 'accuracy']\n```\n\n- Leg and / or Staypoint df typically have the following columns :\n\n```python\n['user_id', 'type', 'started_at', 'finished_at', 'timezone',\n\t\t    'length_meters', 'detected_mode', 'purpose', 'geometry',\n\t\t\t\t'home_location', 'work_location']\n```\n\n## Keep in mind\n\n- You work in degrees\n- Write docstrings for documentation generation later on\n- Document the structure of the input df so we know what column and column name we should find in the input df for each method\n- Test the instances \u2013 without spending too much time on corner cases, we aim at a Minimum Viable Product here which will be further enhanced and maintained later on\n\n## List of instances and \u2018public\u2019 methods\n\nList of instances in the python library xyt:\n\n```python\nfrom xyt import FakeDataGenerator, GPSDataProcessor, GPSDataPrivacy, GPSAnalytics, GPStoGraph, GPStoActionspace, plot_gps_on_map\n```\n\n- `FakeDataGenerator()`\n\nA fake gps data generator to play with the library without infringing on users\u2019 privacy\n\n```python\nfakegps = FakeDataGenerator(location_name=\"Suisse\", num_users=5, home_radius_km = 20)\nwaypoints = fakegps.generate_waypoints(num_rows=12, num_extra_od_points=10, max_displacement_meters = 10)\nlegs = fakegps.generate_legs(num_rows=12)\nstays = fakegps.generate_staypoints(num_rows=12)\n```\n\n- `GPSDataProcessor()`\n\nA geotagging instance to transform raw gps data into mobility data\n\n```python\ndata_processor = GPSDataProcessor(radius=0.03)\n\npoi_waypoints = data_processor.guess_home_work(waypoints_df, cell_size=0.3)\nsmoothed_df = data_processor.smooth(poi_waypoints, sigma=10)\nsegmented_df = data_processor.segment(smoothed_df)\nmode_df = data_processor.mode_detection(segmented_df)\nlegs_ = data_processor.get_legs(df = mode_df)\n```\n\n- `plot_gps_on_map()`\n\nA function to plot easily xyt\u2019s instances outputs\n\n```python\nplot_gps_on_map(poi_waypoints, home_col='home_loc', work_col='work_loc')\n```\n\n- `GPSDataPrivacy()`\n\nAn instance to artificially degrade the data for privacy purposes\n\n```python\ndata_privacy = GPSDataPrivacy()\n\ndf_obfuscated = data_privacy.obfuscate()\nutility = data_privacy.get_obfuscation_utility()\ndf_aggergated = data_privacy.aggregate()\n```\n\n- `GPSAnalytics()`\n\nAn instance to perform space-based and time-based analytics on the mobility data\n\n```python\nmetrics = GPSAnalytics()\n\nmetrics.check_inputs()\nstaypoint1 = metrics.split_overnight(staypoint)\nstaypoint2 = metrics.spatial_clustering(staypoint1)\nextended_staypoint = metrics.get_metrics(staypoint2)\nday_staypoint = metrics.get_daily_metrics(extended_staypoint)\n```\n\n- `GPStoGraph()`\n\nAn instance to abstract mobility diaries as a graph\n\n```python\ngraphs = GPStoGraph()\n\nmultiday_graph = graphs.get_graphs(extended_staypoint)\ngraphs.plot_motif(multiday_graph)\ngraphs.plot_graph(multiday_graph)\nmotif_seq = graphs.motif_sequence(multiday_graph)\n```\n\n- `GPStoActionspace()`\n\nAn instance to generate key metrics characterizing the activity space for a more in-depth exploration of spatial familiarity.\n\n```python\naction_space = GPStoActionspace()\n\naggregation_method = 'user_id'  # Change this to 'user_id' or 'user_id_day'\nact_spc, act_modified = action_space.compute_action_space(act, aggregation_method=aggregation_method)\nmymap = action_space.plot_ellipses(act_spc, aggregation_method=aggregation_method)\naction_space.covariance_matrix(action_space=act_spc)\naction_space.plot_action_space(act, act_spc, user=\"CH16871\", how=\"vignette\", save=False)\naction_space.plot_action_space(act, act_spc, user=\"CH16871\", how=\"folium\", save=False)\n```\n",
    "bugtrack_url": null,
    "license": "MIT",
    "summary": "xyt is a python package for processing raw gps data into mobility data. xyt offers privacy-based capabilities and aims to provide a plug-and-play pipeline to leverage gps data.",
    "version": "0.1.2",
    "project_urls": null,
    "split_keywords": [
        "xyt",
        "gps",
        "mobility"
    ],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "36e63c998e66bcbcf0fe2dbe499b27b8f92af210dd775ae0d34ac927046a28a7",
                "md5": "266e2a3c20f36baaeb5e8f4126cbdf60",
                "sha256": "56054bc4d8ee49e001c4620359199f2f922192fac748c34bf77ead65b5a2218a"
            },
            "downloads": -1,
            "filename": "xyt-0.1.2-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "266e2a3c20f36baaeb5e8f4126cbdf60",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.6,<4.0",
            "size": 38957,
            "upload_time": "2023-12-04T15:30:16",
            "upload_time_iso_8601": "2023-12-04T15:30:16.776498Z",
            "url": "https://files.pythonhosted.org/packages/36/e6/3c998e66bcbcf0fe2dbe499b27b8f92af210dd775ae0d34ac927046a28a7/xyt-0.1.2-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "33bc68c36bed148380f30f0c6aab5021e632dbf6dac1ebfca2eb8469a163c866",
                "md5": "56f669325f1cd6805ddf609494202a1f",
                "sha256": "950190ffa876de8dd0f42b23f8354aa7059f335b64278f630527b49d8dacb925"
            },
            "downloads": -1,
            "filename": "xyt-0.1.2.tar.gz",
            "has_sig": false,
            "md5_digest": "56f669325f1cd6805ddf609494202a1f",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.6,<4.0",
            "size": 37042,
            "upload_time": "2023-12-04T15:30:18",
            "upload_time_iso_8601": "2023-12-04T15:30:18.446088Z",
            "url": "https://files.pythonhosted.org/packages/33/bc/68c36bed148380f30f0c6aab5021e632dbf6dac1ebfca2eb8469a163c866/xyt-0.1.2.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2023-12-04 15:30:18",
    "github": false,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "lcname": "xyt"
}