### Run Example Scripts

Source: https://github.com/mie-lab/trackintel/blob/master/examples/README.md

Execute the provided Python scripts to run various trackintel examples. Output plots are generated in the 'examples/out' directory. Adapt 'config.json' for database connection examples.

```bash
python preprocess_trajectories.py
```

```bash
python import_export_postgis.py
```

```bash
python setup_example_database.py
```

--------------------------------

### Install trackintel

Source: https://github.com/mie-lab/trackintel/blob/master/docs/tutorial.md

Install the trackintel library using pip. This is the first step before using any of its functionalities.

```python
pip install trackintel
```

--------------------------------

### Install Sphinx for Documentation

Source: https://github.com/mie-lab/trackintel/blob/master/CONTRIBUTING.md

Install Sphinx, the documentation generator used by the project. Use pip or conda.

```bash
pip install -U sphinx
```

```bash
conda install sphinx
```

--------------------------------

### Install trackintel Locally

Source: https://github.com/mie-lab/trackintel/blob/master/CONTRIBUTING.md

Install trackintel locally for development purposes. This command downloads the repository and installs the package.

```bash
pip install .
```

--------------------------------

### Install Trackintel with Conda

Source: https://github.com/mie-lab/trackintel/blob/master/README.md

Installs the trackintel library using the conda-forge channel. This is the recommended installation method.

```bash
conda install -c conda-forge trackintel
```

--------------------------------

### Test trackintel Installation

Source: https://github.com/mie-lab/trackintel/blob/master/docs/tutorial.md

Verify the installation by importing trackintel and printing its version. Ensures the library is accessible.

```python
import trackintel as ti
ti.print_version()
```

--------------------------------

### Generate and Preview ASV Benchmark Results

Source: https://github.com/mie-lab/trackintel/blob/master/benchmarks/ASV-BENCHMARKING.md

Commands to generate static HTML files for benchmark results and start a local server to preview them.

```bash
asv publish
```

```bash
asv preview
```

--------------------------------

### Install PyQt Dependencies for Ubuntu

Source: https://github.com/mie-lab/trackintel/blob/master/benchmarks/ASV-BENCHMARKING.md

Use these commands to resolve dependency conflicts with PyQt on Ubuntu. Ensure you are using the correct versions.

```bash
pip install --upgrade --user pyqtwebengine==5.12
pip install --upgrade --user pyqt5==5.12
```

--------------------------------

### Example of Test Data Definition

Source: https://github.com/mie-lab/trackintel/blob/master/CONTRIBUTING.md

Illustrates how test data should be defined directly within the code for clarity and independence. This example is from the PostGIS integration tests.

```python
import pandas as pd

from trackintel.geogr import calculate_distance

def test_calculate_distance():
    # Test data
    data = {
        "id": [1, 2, 3],
        "geom": [
            "POINT (1 1)",
            "POINT (2 2)",
            "POINT (3 3)",
        ],
        "type": ["a", "b", "c"]
    }
    df = pd.DataFrame(data)
    df["geom"] = gpd.GeoSeries.from_wkt(df["geom"])
    df = df.set_index("id")

    # Expected output
    expected_output = pd.DataFrame({
        "id": [1, 2, 3],
        "geom": [
            "POINT (1 1)",
            "POINT (2 2)",
            "POINT (3 3)",
        ],
        "type": ["a", "b", "c"]
    })
    expected_output["geom"] = gpd.GeoSeries.from_wkt(expected_output["geom"])
    expected_output = expected_output.set_index("id")

    # Calculate distance
    result = calculate_distance(df)

    # Assertions
    pd.testing.assert_frame_equal(result, expected_output)
```

--------------------------------

### Full Pipeline Example Imports

Source: https://context7.com/mie-lab/trackintel/llms.txt

Imports necessary modules from trackintel for a complete end-to-end workflow, from raw GPS data to semantic mobility analysis.

```python
import os
import trackintel as ti
from trackintel.io import read_geolife, geolife_add_modes_to_triplegs
from trackintel.analysis import (
    temporal_tracking_quality,
    calculate_modal_split,
    location_identifier,
    radius_gyration,
)
```

--------------------------------

### Print trackintel Version

Source: https://github.com/mie-lab/trackintel/blob/master/CONTRIBUTING.md

Quickly check the installed version of trackintel for testing or verification.

```python
trackintel.print_version()
```

--------------------------------

### Run Tests with pytest

Source: https://github.com/mie-lab/trackintel/blob/master/CONTRIBUTING.md

Execute all project tests using pytest. Ensure pytest is installed first.

```bash
pytest
```

--------------------------------

### Import and Print Trackintel Version

Source: https://github.com/mie-lab/trackintel/blob/master/README.md

Imports the trackintel library and prints its current version. This is a basic check after installation.

```python
import trackintel as ti

ti.print_version()
```

--------------------------------

### Import trackintel and Libraries

Source: https://github.com/mie-lab/trackintel/blob/master/examples/trackintel_basic_tutorial.ipynb

Imports the trackintel library and other necessary Python libraries for data manipulation and visualization. This is the initial setup for using trackintel.

```python
# This is not needed if the trackintel library is installed. ==================
import sys
sys.path.append("..\n")
sys.path.append("../trackintel")
# =============================================================================

import trackintel as ti
import geopandas as gpd
import pandas as pd

from matplotlib import pyplot as plt
%matplotlib inline
```

--------------------------------

### Import Libraries for Trackintel Case Study

Source: https://github.com/mie-lab/trackintel/blob/master/examples/Trackintel case study.ipynb

Imports necessary libraries for data analysis, visualization, and trackintel functionalities. Includes setup for plotting and database connections.

```python
import os, sys
from collections import defaultdict
import pickle
import datetime
import warnings
warnings.filterwarnings("ignore")

import numpy as np
import pandas as pd
import geopandas as gpd
import matplotlib.pyplot as plt
import pytz
import json
import seaborn as sns
from shapely.geometry import Point, Polygon
from sqlalchemy import create_engine

from IPython.display import Image

import trackintel as ti
from trackintel.analysis import temporal_tracking_quality
from trackintel.analysis import calculate_modal_split
from trackintel.visualization import plot_modal_split
from trackintel.analysis import predict_transport_mode
plt.rcParams.update({"font.size": 15})
```

--------------------------------

### Load and Plot Geolife Dataset

Source: https://github.com/mie-lab/trackintel/blob/master/examples/trackintel_basic_tutorial.ipynb

Loads the example Geolife dataset and plots the raw position fixes. Requires the 'geolife_long' data to be available in the specified path.

```python
# Load example geolife dataset
pfs, _ = ti.io.read_geolife('../tests/data/geolife_long')
# plot the raw positionfixes
ti.plot(positionfixes=pfs, plot_osm=True)
```

--------------------------------

### Run Tests with pipenv and pytest

Source: https://github.com/mie-lab/trackintel/blob/master/CONTRIBUTING.md

If using pipenv, install pytest and then run tests using the pipenv-managed Python interpreter.

```bash
pip install pytest
python -m pytest
```

--------------------------------

### Create tours Table

Source: https://github.com/mie-lab/trackintel/wiki/Data-Model-(SQL)

Defines the structure for storing tours, representing sequences of trips that start and end at the same place. Links to users.

```sql
CREATE TABLE tours
(
  id bigint NOT NULL,
  user_id integer NOT NULL,

  started_at timestamp without time zone NOT NULL,
  finished_at timestamp without time zone NOT NULL,
  origin geometry,
  journey bool,

  CONSTRAINT tours_pkey PRIMARY KEY (id)
);
```

--------------------------------

### Create Date Ranges with Minute Resolution

Source: https://github.com/mie-lab/trackintel/blob/master/examples/Trackintel case study.ipynb

Expands staypoints to include all minutes within their start and end times. Requires 'started_at' and 'finished_at' columns.

```python
sp_study["date"] = sp_study.apply(
    lambda x: pd.date_range(
        x["started_at"], x["finished_at"], freq="min")
    , axis=1
)
sp_study_expl = sp_study.explode("date", ignore_index=True).drop(
    columns=["started_at", "finished_at"]
)
```

--------------------------------

### Display First 3 Tours

Source: https://github.com/mie-lab/trackintel/blob/master/examples/Trackintel case study.ipynb

Shows the first 3 rows of the 'tours' DataFrame, including user ID, start and end times, associated staypoint and trip IDs, and study information.

```python
tours.head(3)
```

--------------------------------

### Format Code with Black

Source: https://github.com/mie-lab/trackintel/blob/master/CONTRIBUTING.md

Automatically format your Python code to conform to the black style guide with a line length of 120 characters. Run this in the trackintel folder.

```bash
python -m black . -l 120
```

--------------------------------

### Generate tours from trips

Source: https://context7.com/mie-lab/trackintel/llms.txt

Generates tours, which are sequences of trips starting and ending at the same location within a time window. Requires trips with geometry or staypoints with location IDs.

```python
import trackintel as ti

# Requires trips with geometry (add_geometry=True) or staypoints with location_id
trips_with_tours, tours = trips.generate_tours(
    staypoints=sp,           # use location_id for matching (preferred)
    max_time="1D",           # maximum tour duration
    max_nr_gaps=0,           # 0 = no spatial gaps allowed
    n_jobs=-1,
    print_progress=True
)

print(f"Generated {len(tours)} tours")
print(tours[["user_id", "started_at", "finished_at", "trips"]].head())
```

--------------------------------

### Display First 3 Trips

Source: https://github.com/mie-lab/trackintel/blob/master/examples/Trackintel case study.ipynb

Shows the first 3 rows of the 'trips' DataFrame to inspect the generated trip data, including user ID, start and end times, geometry, and associated staypoint IDs.

```python
trips.head(3)
```

--------------------------------

### Generate Documentation

Source: https://github.com/mie-lab/trackintel/blob/master/CONTRIBUTING.md

Build the project documentation in HTML format using Sphinx. The output is placed in the 'docs.gen' directory.

```bash
sphinx-build -b html docs docs.gen
```

--------------------------------

### Define Paths and PostGIS Connections

Source: https://github.com/mie-lab/trackintel/blob/master/examples/Trackintel case study.ipynb

Sets up the output directory and defines paths for the Geolife dataset. Establishes database connections to PostGIS for different data sources (GC, yumuv, casestudy).

```python
# output directory to save all outputs
out_path = "temp"
os.makedirs(out_path, exist_ok=True)

# Geolife data
path_to_geolife = "Geolife Trajectories 1.3/Data"

# for postgis
DBLOGIN_FILE_GC = "../../dblogin_commit.json"
DBLOGIN_FILE_yumuv = "../../dblogin_mielab.json"

with open(DBLOGIN_FILE_GC) as json_file:
    LOGIN_DATA_GC = json.load(json_file)

with open(DBLOGIN_FILE_yumuv) as json_file:
    LOGIN_DATA_YUMUV = json.load(json_file)

engine_gc = create_engine(
    "postgresql://{user}:{password}@{host}:{port}/{database}".format(
        **LOGIN_DATA_GC
    )
)
yengine_yumuv = create_engine(
    "postgresql://{user}:{password}@{host}:{port}/{database}".format(
        **LOGIN_DATA_YUMUV
    )
)
engine_casestudy = create_engine(
    "postgresql://{user}:{password}@{host}:{port}/case_study_cache".format(
        **LOGIN_DATA_YUMUV
    )
)

CRS_WGS84 = "epsg:4326"
```

--------------------------------

### trips.generate_tours

Source: https://context7.com/mie-lab/trackintel/llms.txt

Generates tours from trips, where a tour is a sequence of trips starting and ending at the same location within a time window.

```APIDOC
## trips.generate_tours — Generate tours from trips

### Description
A tour is a sequence of trips that starts and ends at the same location within a time window.

### Parameters
- **staypoints** (StayPointDataFrame) - The staypoints DataFrame, used to match locations if trips do not have geometry. Preferred for matching.
- **max_time** (str) - The maximum duration of a tour (e.g., '1D' for one day). Defaults to '1D'.
- **max_nr_gaps** (int) - The maximum number of spatial gaps allowed within a tour. Defaults to 0.
- **n_jobs** (int) - Number of parallel jobs to run. Defaults to -1 (use all available cores).
- **print_progress** (bool) - If True, prints progress updates. Defaults to False.

### Request Example
```python
# Assuming 'trips' is a TripDataFrame with geometry or 'sp' is a StayPointDataFrame
trips_with_tours, tours = trips.generate_tours(
    staypoints=sp,
    max_time="1D",
    max_nr_gaps=0,
    n_jobs=-1,
    print_progress=True
)
```

### Response
- **tours** (TourDataFrame) - A DataFrame containing the generated tours.
```

--------------------------------

### Run ASV Benchmarks for Specific Commits

Source: https://github.com/mie-lab/trackintel/blob/master/benchmarks/ASV-BENCHMARKING.md

Execute ASV benchmarks using the commit hashes from the specified file. The '-q' flag runs each benchmark once for initial testing.

```bash
asv run HASHFILE:commits.txt
```

```bash
asv run -q HASHFILE:commits.txt
```

--------------------------------

### Compute Users at Home Fraction

Source: https://github.com/mie-lab/trackintel/blob/master/examples/Trackintel case study.ipynb

Calculates the fraction of users at home for each minute of the day by dividing the number of home staypoints by the total active users.

```python
# compute the number of users at home per day
count_by_minute["users_at_home"] = count_by_minute[
    "nr_home_sp"] / count_by_minute["active_users"]
```

--------------------------------

### Import Positionfixes from Geolife Dataset

Source: https://github.com/mie-lab/trackintel/blob/master/README.md

Reads positionfixes from the Geolife dataset. This function also returns a GeoDataFrame for staypoints, which is ignored in this example.

```python
# or with predefined dataset readers (here geolife) 
pfs, _ = ti.io.read_geolife(".\tests\data\geolife_long")
```

--------------------------------

### Prepare Basic Dataset Statistics Table

Source: https://github.com/mie-lab/trackintel/blob/master/examples/Trackintel case study.ipynb

Selects and formats basic dataset statistics, filling missing values with 0 and converting relevant columns to integer type. Requires 'overview_df' to be pre-populated.

```python
# basic info
overview_df.fillna(0, inplace=True)
df_basic = overview_df[
    [
        "nr_user",
        "mean_tracking_period",
        "std_tracking_period",
        "nr_loc",
        "nr_sp",
        "nr_tpls",
        "nr_trips",
        "nr_tours",
    ]
].astype(int)
```

--------------------------------

### Tours Table Schema

Source: https://github.com/mie-lab/trackintel/blob/master/docs/modules/model.md

Defines the structure for storing tours, which are sequences of trips starting and ending at the same location, linked to users and potentially a specific location.

```sql
CREATE TABLE tours (
    -- Common to all tables.
    id bigint NOT NULL,
    user_id integer NOT NULL,

    -- References to foreign tables.
    location_id bigint,

    -- Temporal attributes.
    started_at timestamp with time zone NOT NULL,
    finished_at timestamp with time zone NOT NULL,

    -- Specific attributes.
    journey bool,

    -- Constraints.
    CONSTRAINT tours_pkey PRIMARY KEY (id)
);
```

--------------------------------

### Prepare Detailed Trip Statistics Table

Source: https://github.com/mie-lab/trackintel/blob/master/examples/Trackintel case study.ipynb

Selects and rounds detailed trip statistics from the 'overview_df'. Requires 'overview_df' to be pre-populated with relevant columns.

```python
# Analysis table
df_detailed = overview_df[
    [
        "nr_trips_per_user_per_day",
        "mean_trip_dur",
        "std_trip_dur",
        "avg_hops_tours",
        "nr_legs_per_trip",
        "avg_trip_length",
        "std_trip_length",
        "mean_tracking_quality",
        "std_tracking_quality",
    ]
]

df_detailed = df_detailed.round(2)
```

--------------------------------

### Calculate Trip Duration in Hours

Source: https://github.com/mie-lab/trackintel/blob/master/examples/Trackintel case study.ipynb

Calculates the duration of each trip in hours by subtracting the start time from the finish time. Requires 'trips' DataFrame with 'started_at' and 'finished_at' columns.

```python
trips["duration_s"] = (
    trips["finished_at"] - trips["started_at"]
    ).dt.total_seconds() / 3600
```

--------------------------------

### Read GPX Files

Source: https://github.com/mie-lab/trackintel/blob/master/docs/modules/io.md

Reads GPX data from a directory and returns it as Positionfixes for a single user. Non-GPX files in the specified path are ignored.

```python
from trackintel.io import read_gpx
positionfixes = read_gpx(path='path/to/gpx/files')
```

--------------------------------

### Display Staypoints Data

Source: https://github.com/mie-lab/trackintel/blob/master/examples/trackintel_basic_tutorial.ipynb

Displays the first 5 rows of the generated staypoints data. This provides an overview of the detected staypoints, including their start and end times and locations.

```python
sp.head()
```

--------------------------------

### Read trips from CSV with column mapping

Source: https://github.com/mie-lab/trackintel/blob/master/docs/modules/io.md

Reads trips from a CSV file, allowing custom mapping of column names for start time and user ID. Geometry is optional.

```python
>>> trackintel.read_trips_csv('data.csv')
>>> trackintel.read_trips_csv('data.csv', columns={'start_time':'started_at', 'User':'user_id'})
```

```text
    user_id                started_at               finished_at  origin_staypoint_id  destination_staypoint_id    id
0         1 2015-11-27 08:00:00+00:00 2015-11-27 08:15:00+00:00                    2                         5
1         1 2015-11-27 08:20:22+00:00 2015-11-27 08:35:22+00:00                    5                         3
                            geom
id
0   MULTIPOINT (116.31842 39.98470, 116.29873 39.999729)
1   MULTIPOINT (116.29873 39.98402, 116.32480 40.009269)
```

--------------------------------

### Aggregate Average Users at Home

Source: https://github.com/mie-lab/trackintel/blob/master/examples/Trackintel case study.ipynb

Calculates the mean fraction of users at home for each study, aggregated by 'minute_of_day'.

```python
# Aggregate over the days to get the average fraction of users at hoe
count_by_minute = count_by_minute.groupby(
    ["study", "minute_of_day"]
).agg({"users_at_home": "mean"}).reset_index()
```

--------------------------------

### Read triplegs from GeoDataFrame

Source: https://github.com/mie-lab/trackintel/blob/master/docs/modules/io.md

Imports triplegs from a GeoDataFrame, supporting custom mapping for start time, end time, user ID, and geometry columns, along with timezone and CRS settings.

```python
>>> trackintel.read_triplegs_gpd(gdf, user_id='User', geom_col='geom', tz='utc')
```

--------------------------------

### Read Staypoints from GeoDataFrame

Source: https://github.com/mie-lab/trackintel/blob/master/docs/modules/io.md

Use this function to import staypoints from a GeoDataFrame. Specify column names for start time, end time, and user ID if they differ from the defaults. Timezone can also be set.

```python
>>> trackintel.read_staypoints_gpd(gdf, started_at='start_time', finished_at='end_time', tz='utc')
```

--------------------------------

### Calculate and Visualize Modal Split

Source: https://github.com/mie-lab/trackintel/blob/master/examples/trackintel_basic_tutorial.ipynb

Calculates the modal split from triplegs with modes and visualizes the results.

```python
# the modal split can then be calculated
modal_split = ti.analysis.calculate_modal_split(tpls_with_modes, metric="count", freq="D", per_user=False, norm=True)

# and visualized
ti.plot_modal_split(modal_split, date_fmt_x_axis='%m-%d', y_label='Percentage of daily count', x_label='days')
plt.show()
```

--------------------------------

### Run ASV Benchmarks Skipping Existing

Source: https://github.com/mie-lab/trackintel/blob/master/benchmarks/ASV-BENCHMARKING.md

This command runs ASV benchmarks but skips any that have already been executed on the same machine, saving time.

```bash
asv run --skip-existing HASHFILE:commits.txt
```

--------------------------------

### Compute temporal tracking coverage

Source: https://context7.com/mie-lab/trackintel/llms.txt

Calculates per-user tracking quality as the ratio of tracked time to total observation time. Supports various granularities like 'all', 'day', 'week', 'weekday', and 'hour'.

```python
import trackintel as ti

pfs, _ = ti.io.read_geolife("Geolife Trajectories 1.3")
pfs, sp = pfs.generate_staypoints()
pfs, tpls = pfs.generate_triplegs(sp)

# Overall quality per user
quality_all = ti.analysis.temporal_tracking_quality(tpls, granularity="all")
print(quality_all.head())
# user_id  quality
# 0        0.9821
# 1        0.8734

# Daily breakdown
quality_day = ti.analysis.temporal_tracking_quality(tpls, granularity="day")

# Supported granularities: 'all', 'day', 'week', 'weekday', 'hour'
quality_hour = ti.analysis.temporal_tracking_quality(sp, granularity="hour")
```

--------------------------------

### Read Trips from GeoDataFrame/DataFrame

Source: https://github.com/mie-lab/trackintel/blob/master/docs/modules/io.md

Reads trip data from a GeoDataFrame or DataFrame. This function allows customization of column names for start and end times, user ID, and staypoint IDs. It can also handle geometry columns and timezones.

```python
>>> trackintel.read_trips_gpd(df, tz='utc')
```

--------------------------------

### Get Trips Grouped by Tour

Source: https://github.com/mie-lab/trackintel/blob/master/docs/modules/preprocessing.md

A helper function to retrieve trips grouped by their tour ID. This is necessary because generate_tours assigns the tour ID of the smallest tour a trip belongs to. This function returns all trips for each tour, including those in nested tours.

```python
>>> get_trips_grouped(trips, tours)
```

--------------------------------

### Select Home or Work Staypoints for Analysis

Source: https://github.com/mie-lab/trackintel/blob/master/examples/Trackintel case study.ipynb

Prepares the staypoints DataFrame for analysis by filtering for either 'home' or 'work' purposes based on the 'home_work_variable'. Creates a copy to avoid SettingWithCopyWarning.

```python
# Chose to analyze "home" or "work" activity staypoints
home_work_variable = "home"

# Use either the home staypoints or the work staypoints
if home_work_variable == "home":
    sp_study = staypoints[staypoints["purpose"] == "home"].copy()
elif home_work_variable == "work":
    sp_study = staypoints[staypoints["purpose"] == "work"].copy()
```

--------------------------------

### Generate Tours from Trips and Staypoints

Source: https://github.com/mie-lab/trackintel/blob/master/examples/Trackintel case study.ipynb

Generates tours by grouping trips and staypoints. The 'print_progress' parameter shows the progress of the tour generation. Converts 'started_at' and 'finished_at' columns to datetime objects.

```python
trips, tours = ti.preprocessing.generate_tours(
    trips, staypoints=staypoints, print_progress=True
)
tours["started_at"] = pd.to_datetime(tours["started_at"])
tours["finished_at"] = pd.to_datetime(tours["finished_at"])
```

--------------------------------

### Print Analysis Results

Source: https://context7.com/mie-lab/trackintel/llms.txt

Prints sample data for tracking quality and radius of gyration to the console.

```python
print("Tracking quality (sample):")
print(quality.head())
print("\nRadius of gyration (sample):")
print(rg.head())
```

--------------------------------

### Create trips Table

Source: https://github.com/mie-lab/trackintel/wiki/Data-Model-(SQL)

Defines the structure for storing trips, which are collections of trip legs. Links to users and can be associated with tours.

```sql
CREATE TABLE trips
(
  id bigint NOT NULL,
  user_id integer NOT NULL,

  started_at timestamp without time zone NOT NULL,
  finished_at timestamp without time zone NOT NULL,
  origin bigint,
  destination bigint,
  tour_id BIGINT[],

  CONSTRAINT trips_pkey PRIMARY KEY (id)
);
```

--------------------------------

### Push ASV Benchmark Results to gh-pages

Source: https://github.com/mie-lab/trackintel/blob/master/benchmarks/ASV-BENCHMARKING.md

Manually push generated benchmark results to the gh-pages branch. This involves rewriting the branch and requires a force push.

```bash
asv gh-pages --no-push --rewrite
```

```bash
git stash
```

```bash
git checkout gh-pages
```

```bash
git log
```

```bash
git push -f origin gh-pages
```

--------------------------------

### Calculate Temporal Tracking Quality

Source: https://github.com/mie-lab/trackintel/blob/master/docs/modules/analysis.md

Calculates per-user temporal tracking quality (coverage) for a given source dataframe. Requires columns ['user_id', 'started_at', 'finished_at']. Supports 'all', 'day', 'week', 'weekday', and 'hour' granularities.

```python
>>> # calculate overall tracking quality of staypoints
>>> temporal_tracking_quality(sp, granularity="all")
>>> # calculate per-day tracking quality of sp and tpls sequence
>>> temporal_tracking_quality(sp_tpls, granularity="day")
```

--------------------------------

### Calculate Number of Tours per User

Source: https://github.com/mie-lab/trackintel/blob/master/examples/Trackintel case study.ipynb

Calculates the total number of tours and the number of tours per user for each study group. Requires 'tours' and 'nr_user' to be defined.

```python
overview_df["nr_tours"] = tours.groupby(by=["study"]).size()
overview_df["nr_tours_per_user"] = overview_df["nr_tours"] / nr_user
```

```python
overview_df
```

--------------------------------

### Prepare Staypoints for Time Series Analysis

Source: https://github.com/mie-lab/trackintel/blob/master/examples/Trackintel case study.ipynb

Selects only the 'started_at', 'finished_at', and 'study' columns from the staypoints DataFrame, preparing it for time series resampling and aggregation.

```python
# chop up durations to minute-by-minute time series
sp_study = sp_study[["started_at", "finished_at", "study"]]

```

--------------------------------

### Calculate User Tracking Period Duration

Source: https://github.com/mie-lab/trackintel/blob/master/examples/Trackintel case study.ipynb

Calculates the minimum and maximum tracking times per user and study, then computes the duration of the tracking period for each user in days. Finally, it aggregates the mean and standard deviation of these tracking periods per study.

```python
min_max_times_by_user = trips.groupby(["study", "user_id"]).aggregate(
    {"started_at": "min", "finished_at": "max"}
)
duration_by_user = (
    min_max_times_by_user[
        "finished_at"
    ] - min_max_times_by_user["started_at"]
).dt.total_seconds() / (3600 * 24)

overview_df[
    ["mean_tracking_period", "std_tracking_period"]
] = duration_by_user.groupby("study").aggregate(["mean", "std"])
```

```python
overview_df[["mean_tracking_period", "std_tracking_period"]]
```

--------------------------------

### Import Geolife Dataset with trackintel

Source: https://github.com/mie-lab/trackintel/blob/master/examples/Trackintel case study.ipynb

Use the `read_geolife` function to import the Geolife dataset. This function handles the required column format and names. The output includes positionfixes and user data.

```python
import trackintel
from trackintel.io import read_geolife

pfs_geolife, _ = read_geolife(path_to_geolife, print_progress=True)
pfs_geolife[["user_id", "tracked_at", "geom", "elevation"]].head(3)
```

--------------------------------

### Read GPX Files

Source: https://context7.com/mie-lab/trackintel/llms.txt

Reads GPX track files from a directory into positionfixes for a single user. Specify the correct path to your GPX files.

```python
from trackintel.io import read_gpx

pfs = read_gpx("path/to/gpx_folder")
print(pfs.head())
```

--------------------------------

### Identify Staypoints with FREQ Method

Source: https://context7.com/mie-lab/trackintel/llms.txt

Uses the FREQ method to identify staypoints based on location frequency. Requires minimum staypoints and locations per user, as well as minimum staypoints and time at each location.

```python
sp = location_identifier(
    sp,
    method="FREQ",
    pre_filter=True,
    thresh_sp=10,            # minimum staypoints per user
    thresh_loc=10,           # minimum locations per user
    thresh_sp_at_loc=10,     # minimum staypoints at location
    thresh_loc_time="1h",    # minimum total time at location
    thresh_loc_period="5h"   # minimum timespan first-to-last visit
)
```

--------------------------------

### Generate Trips with Triplegs and Staypoints

Source: https://github.com/mie-lab/trackintel/blob/master/examples/trackintel_basic_tutorial.ipynb

Generates trips, triplegs, and staypoints from raw trajectory data, inferring activity labels. Requires staypoints and triplegs as input.

```python
sp, tpls, trips = ti.preprocessing.generate_trips(sp, tpls, gap_threshold=15)
trips.head(5)
```

--------------------------------

### Create cust_movements Table

Source: https://github.com/mie-lab/trackintel/wiki/Data-Model-(SQL)

Defines the structure for storing customer movements, specifically sequences of public transport trip legs. Links to users and trips.

```sql
CREATE TABLE cust_movements
(
  id bigint NOT NULL,
  user_id integer NOT NULL,
  trip_id bigint NOT NULL,

  started_at timestamp without time zone NOT NULL,
  finished_at timestamp without time zone NOT NULL,
  provider varchar,

  CONSTRAINT cust_movements_pkey PRIMARY KEY (id)
);
```

--------------------------------

### Prepare Triplegs for Modal Split Analysis

Source: https://github.com/mie-lab/trackintel/blob/master/examples/Trackintel case study.ipynb

Selects triplegs for a specific user from the 'Green Class' dataset and renames the 'mode_detailed' column to 'mode' for subsequent modal split analysis.

```python
# Use one GC2 user for this visualization
tpls_vis = triplegs[
    triplegs["user_id"] == "c9aa08e2-1a5d-4d41-ae62-6110a9072b23"
].copy()

# rename to mode
tpls_vis["mode"] = tpls_vis["mode_detailed"]
```

--------------------------------

### Generate Trips from Staypoints and Triplegs

Source: https://github.com/mie-lab/trackintel/blob/master/docs/modules/preprocessing.md

Shows how to generate trips using the `generate_trips` function from the preprocessing module. It also illustrates the equivalent class method available on the Triplegs object. The function returns modified staypoints, triplegs, and the newly generated trips.

```python
>>> from trackintel.preprocessing import generate_trips
>>> staypoints, triplegs, trips = generate_trips(staypoints, triplegs)
>>> # trips can also be directly generated using the tripleg class method
>>> staypoints, triplegs, trips = triplegs.generate_trips(staypoints)
```

--------------------------------

### trackintel.analysis.freq_method

Source: https://github.com/mie-lab/trackintel/blob/master/docs/modules/analysis.md

Generates an activity label (e.g., 'home', 'work') for each user based on the frequency of visits to locations.

```APIDOC
## trackintel.analysis.freq_method(staypoints, *labels)

### Description
Generate an activity label per user.
Assigning the most visited location the label “home” and the second most visited location the label “work”.
The remaining locations get no label.
Labels can also be given as arguments.

### Parameters
* **staypoints** ([*Staypoints*](model.md#trackintel.Staypoints)) – Staypoints with the column “location_id”.
* **labels** (*collection* *of* *str* *,* *default* *(* "home" *,*  "work" *)*) – Labels in decreasing time of activity.

### Returns
**sp** – The input staypoints with additional column “purpose”.
* **Return type:**
[Staypoints](model.md#trackintel.Staypoints)

### Examples
```pycon
>>> from ti.analysis import freq_method
>>> staypoints = freq_method(staypoints, "home", "work")
```
```

--------------------------------

### Displaying a Sample Staypoint per Study

Source: https://github.com/mie-lab/trackintel/blob/master/examples/Trackintel case study.ipynb

Selects and displays the first staypoint for each study, excluding user_id and geometry for privacy. This provides a quick overview of the data.

```python
# show a staypoint for each study (without user_id and geometry due to privacy)
staypoints[[ 
    "started_at", "finished_at", "study", "is_activity", "purpose" 
]].groupby("study").head(1)
```

--------------------------------

### Plot user tracking quality distribution

Source: https://github.com/mie-lab/trackintel/blob/master/examples/Trackintel case study.ipynb

Generates a Kernel Density Estimate (KDE) plot to visualize the distribution of tracking quality across users for different studies. Saves the plot to a PDF file.

```python
fig, ax = plt.subplots(figsize=(9, 5))
g = sns.kdeplot(
    data=tracking_quality_df,
    fill=True,
    alpha=0.3,
    legend=True,
    common_grid=True,
    common_norm=False,
    ax=ax,
)

plt.ylabel("Density (users)", fontsize=20)
plt.xlabel("Tracking quality", fontsize=20)
sns.move_legend(g, "upper left")
plt.xlim(0, 1)
plt.savefig(os.path.join(out_path, "tracking_quality_kde.pdf"))
plt.show()
```

--------------------------------

### trackintel.analysis.osna_method

Source: https://github.com/mie-lab/trackintel/blob/master/docs/modules/analysis.md

Identifies 'home' and 'work' locations based on timeframes ('rest', 'work', 'leisure') and duration spent at locations.

```APIDOC
## trackintel.analysis.osna_method(staypoints)

### Description
Find “home” location for timeframes “rest” and “leisure” and “work” location for “work” timeframe.
Use weekdays data divided in three time frames [“rest”, “work”, “leisure”] to generate location labels.
“rest” + “leisure” locations are weighted together. The location with the longest duration is assigned “home” label.
The longest “work” location is assigned “work” label.

### Parameters
**staypoints** ([*Staypoints*](model.md#trackintel.Staypoints)) – Staypoints with the column “location_id”.

### Returns
The input staypoints with additional column “purpose”.
* **Return type:**
[Staypoints](model.md#trackintel.Staypoints)

#### NOTE
The method is adapted from [1].
When “home” and “work” label overlap, the method selects the “work” location by the 2nd highest score.
The original algorithm count the distinct hours at a location as the home location is derived from
geo-tagged tweets. We directly sum the time spent at a location.

### References
[1] Efstathiades, Hariton, Demetris Antoniades, George Pallis, and Marios Dikaiakos. 2015.
‘Identification of Key Locations Based on Online Social Network Activity’.
In [https://doi.org/10.1145/2808797.2808877](https://doi.org/10.1145/2808797.2808877).

### Examples
```pycon
>>> from ti.analysis import osna_method
>>> staypoints = osna_method(staypoints)
```
```

--------------------------------

### Load and Preprocess Yumuv Staypoints

Source: https://github.com/mie-lab/trackintel/blob/master/examples/Trackintel case study.ipynb

Reads staypoint data from a PostGIS database, adjusts column names and timestamps, creates an activity flag, offsets user IDs, and filters data to the study duration. Geometry is dropped for privacy.

```python
sp_yumuv = ti.io.read_staypoints_postgis(
    "select id, user_fk, started_at, finished_at,\n    geometry from yumuv.staypoint",
    con=engine_yumuv,
    geom_col="geometry",
    crs=CRS_WGS84,
    index_col="id",
    tz="UTC",
    mapper={\"user_fk\": \"user_id\"},
)
sp_yumuv = sp_yumuv.rename({\"geometry\": \"geom\"}, axis=1).set_geometry(\"geom\")

sp_yumuv["study"] = "Yumuv"

# yumuv specific definition of activities
sp_yumuv = sp_yumuv.as_staypoints.create_activity_flag(time_threshold=25)

# offset user id to avoid conflicts with other studies
sp_yumuv["user_id"] = sp_yumuv["user_id"] + 10000

# filter study duration
sp_date_flag = (sp_yumuv["started_at"] >= min_date) &
    (sp_yumuv["finished_at"] <= max_date)
sp_yumuv = sp_yumuv[sp_date_flag]

# display output
print("Staypoints loaded successfully for Yumuv.\    Geometry not shown due to data protection.")
sp_yumuv.drop("geom", axis=1).head(3)
```

--------------------------------

### Creating User-Study Matching Table

Source: https://github.com/mie-lab/trackintel/blob/master/examples/Trackintel case study.ipynb

Generates a DataFrame that maps unique user IDs to their corresponding studies. This is useful for analyzing data on a per-user basis.

```python
user_study_matching = staypoints[["user_id", "study"]].drop_duplicates()
user_study_matching = user_study_matching.set_index("user_id")
```

--------------------------------

### Revert to Master Branch and Pop Stash

Source: https://github.com/mie-lab/trackintel/blob/master/benchmarks/ASV-BENCHMARKING.md

After pushing benchmark results, revert to the master branch and reapply any stashed changes.

```bash
git checkout master
```

```bash
git stash pop
```

--------------------------------

### Visualize Mobility Data and Analysis

Source: https://context7.com/mie-lab/trackintel/llms.txt

Visualizes processed mobility data including staypoints, triplegs, and locations, and generates plots for modal split analysis. Outputs are saved as PNG files.

```python
ti.plot(staypoints=sp, triplegs=tpls, locations=locs,
        filename="overview.png", plot_osm=True)
ti.plot_modal_split(modal_split, out_path="modal_split.png",
                    y_label="Distance share", x_label="Week")
```

--------------------------------

### Create Activity Flag

Source: https://github.com/mie-lab/trackintel/blob/master/examples/trackintel_basic_tutorial.ipynb

Creates an activity flag for staypoints based on a time threshold. Staypoints exceeding the specified time threshold are flagged as activities.

```python
# infer activity label based on duration, here any staypoint larger than 15 min is considered as an activity
sp = sp.create_activity_flag(time_threshold=15)
```

--------------------------------

### Create places Table

Source: https://github.com/mie-lab/trackintel/wiki/Data-Model-(SQL)

Defines the structure for storing meaningful locations, such as those derived from clustering stay points. Can be linked to users and stay points.

```sql
CREATE TABLE places
(
  id bigint NOT NULL,
  geom geometry,
  user_id BIGINT,
  purpose VARCHAR,
  staypoint_id BIGINT[]
);
```

--------------------------------

### Generate Commit List for Benchmarking

Source: https://github.com/mie-lab/trackintel/blob/master/benchmarks/ASV-BENCHMARKING.md

This command extracts the last 3 merge commit hashes (short form) from the git log and saves them to commits.txt. Adjust 'head -n 3' to include more or fewer commits.

```bash
git log | grep -B 1 'Merge' | grep 'commit' | sed 's/commit //g' | cut -c1-7 | head -n 3 > commits.txt
```