Package: dp-mobility-report
Free software: MIT licenseDocumentation:https://dp-mobility-report.readthedocs.io.dp_mobility_report: A python package to create a mobility report with differential privacy (DP) guarantees, especially for urban human mobility data.QuickstartInstallpipinstalldp-mobility-reportor from GitHub:pipinstallgit+https://github.com/FreeMoveProject/dp_mobility_reportData preparationdf:A pandasDataFrame.Expected columns: User IDuid, Trip IDtid, timestampdatetime(expected is a datetime-like string, e.g., in the formatyyyy-mm-ddhh:mm:ss. Ifdatetimecontainsintvalues, it is interpreted as sequence positions, i.e., if the dataset only consists of sequences without timestamps), latitude and longitude in CRS EPSG:4326latandlng. (We thereby closely followed the format of thescikit-mobilityTrajDataFrame.)Here you can find anexample dataset.tessellation:A geopandasGeoDataFramewith polygons.Expected columns:tile_id.The tessellation is used for spatial aggregations of the data.Here you can find anexample tessellation.If you don’t have a tessellation, you can use this code tocreate a tessellation.Create a DpMobilityReportimportpandasaspdimportgeopandasasgpdfromdp_mobility_reportimportDpMobilityReportdf=pd.read_csv("https://raw.githubusercontent.com/FreeMoveProject/dp_mobility_report/main/tests/test_files/test_data.csv")tessellation=gpd.read_file("https://raw.githubusercontent.com/FreeMoveProject/dp_mobility_report/main/tests/test_files/test_tessellation.geojson")report=DpMobilityReport(df,tessellation,privacy_budget=10,max_trips_per_user=5)report.to_file("my_mobility_report.html")The parameterprivacy_budget(in terms ofepsilon-DP) determines how much noise is added to the data. The budget is split between all analyses of the report.
If the value is set toNoneno noise (i.e., no privacy guarantee) is applied to the report.The parametermax_trips_per_userspecifies how many trips a user can contribute to the dataset at most. If a user is represented with more trips, a random sample is drawn according tomax_trips_per_user.
If the value is set toNonethe full dataset is used. Note, that deriving the maximum trips per user from the data violates the differential privacy guarantee. Thus,Noneshould only be used in combination withprivacy_budget=None.Please refer to thedocumentationfor information on further parameters. Here you can find information on theanalysesof the report.Example HTMLs can be found in theexamplesfolder.Create a BenchmarkReportA benchmark report evaluate the similarity of two (differentially private) mobility reports from one or two mobility datasets. This can be based on two datasets (df_baseanddf_alternative) or one dataset (df_base)) with different privacy settings.
The argumentsdf,privacy_budget,user_privacy,max_trips_per_userandbudget_splitcan differ for the two datasets set with the according ending_baseand_alternative. The other arguments are the same for both reports.
For the evaluation,similarity measures(namely the (mean) absolute percentage error (PE), Jensen-Shannon divergence (JSD), Kullback-Leibler divergence (KLD), and the earth mover’s distance (EMD)) are computed to quantify the statistical similarity for each analysis.
The evaluation, i.e., benchmark report, will be generated as an HTML file, using the.to_file()method.Benchmark of two different datasetsThis example creates a benchmark report with similarity measures for two mobility datasets, calledbaseandalternativein the following. This is intended to compare different datasets with the same or no privacy budget.importpandasaspdimportgeopandasasgpdfromdp_mobility_reportimportBenchmarkReport# -- insert paths --df_base=pd.read_csv("mobility_dataset_base.csv")df_alternative=pd.read_csv("mobility_dataset_alternative.csv")tessellation=gpd.read_file("tessellation.gpkg")benchmark_report=BenchmarkReport(df_base=df_base,tesselation=tessellation,df_alternative=df_alternative)# Dictionary containing the similarity measures for each analysissimilarity_measures=benchmark_report.similarity_measures# The measure selection indicates which similarity measure# (e.g. KLD, JSD, EMD, PE) has been selected for each analysismeasure_selection=benchmark_report.measure_selection# If you do not want to access the selection of similarity measures# but e.g. the Jensen-Shannon divergence for all analyses:jsd=benchmark_report.jsd# benchmark_report.to_file("my_benchmark_mobility_report.html")The parametermeasure_selectionspecifies which similarity measures should be chosen for thesimilarity_measuresdictionary that is an attribute of theBenchmarkReport.
The default is set to a specific set of similarity measures for each analysis which can be accessed bydp_mobility_report.default_measure_selection().
The default of single analyses can be overwritten as shown in the following:fromdp_mobility_reportimportBenchmarkReport,default_measure_selectionfromdp_mobility_reportimportconstantsasconst# print the default measure selectionprint(default_measure_selection())# change default of EMD for visits_per_tile to JSD.# For the other analyses the default measure is remainedcustom_measure_selection={const.VISITS_PER_TILE:const.JSD}benchmark_report=BenchmarkReport(df_base=df_base,tesselation=tessellation,df_alternative=df_alternative,measure_selection=custom_measure_selection,)Benchmark of the same dataset with different privacy settingsThis example creates a BenchmarkReport with similarity measures for the same mobility dataset with different privacy settings (privacy_budget,user_privacy,max_trips_per_userandbudget_split) to assess the utility loss of the privacy budget for the different analyses.importpandasaspdimportgeopandasasgpdfromdp_mobility_reportimportBenchmarkReport# -- insert paths --df_base=pd.read_csv("mobility_dataset_base.csv")tessellation=gpd.read_file("tessellation.gpkg")benchmark_report=BenchmarkReport(df_base=df_base,tesselation=tessellation,privacy_budget_base=None,privacy_budget_alternative=5,max_trips_per_user_base=None,max_trips_per_user_alternative=4,)similarity_measures=benchmark_report.similarity_measures# benchmark_report.to_file("my_benchmark_mobility_report.html")Please refer to thedocumentationfor information on further parameters.ExamplesBerlin mobility data simulated using theDLR TAPASModel: [Code used for Berlin]Report of Berlin without DPReport of Berlin with DP epsilon=1MadridCRTM surveydata: [Code used for Madrid]Report of Madrid without DPReport of Madrid with DP epsilon=10BeijingGeolifedataset: [Code used for Beijing]Report of Beijing without DPReport of Beijing with DP epsilon=50Benchmark Report: [Code used for Benchmarkreport of Berlin]Benchmarkreport of Berlin without DP and with DP epsilon=1(Here you find thecode of the data preprocessingto obtain the needed format)Citingif you use dp-mobility-report please cite thefollowing paper:@article{doi:10.1080/17489725.2022.2148008,
                author = {Alexandra Kapp and Saskia Nuñez von Voigt and Helena Mihaljević and Florian Tschorsch},
                title = {Towards mobility reports with user-level privacy},
                journal = {Journal of Location Based Services},
                volume = {17},
                number = {2},
                pages = {95-121},
                year  = {2023},
                publisher = {Taylor & Francis},
                doi = {10.1080/17489725.2022.2148008}
}CreditsThis package was highly inspired by thepandas-profiling/pandas-profilingandscikit-mobilitypackages.This package was created withCookiecutterand theaudreyr/cookiecutter-pypackageproject template.This package was developed as part of the freemove project which is funded by:History0.2.10 (2024-01-03)Fix to work with pandas 2.2.0rc0 update0.2.9 (2023-08-17)Fix to work with pandas 2.1.0rc0 update0.2.8 (2023-04-03)Bug fix: smape of trips per day0.2.7 (2023-03-30)Update requirements0.2.6 (2023-03-24)Bug fix: shape mismatch in similarity_measures for edge case (only counts in bin “inf”)0.2.5 (2023-03-24)Bug fix: compatibility with pandas >= 2.0 and pandas < 2.00.2.4 (2023-03-23)Enhance HTML designInclude info texts for all analysesInclude documentation for differential privacy and an info box about DP in the reportEnhance documentationAdd option forsubtitlein DpMobilityReport and BenchmarkReport to name the report.0.2.3 (2023-02-13)Bug fix: handle if no visit is within the tessallationBug fix: handle if no OD trip is within the tessallationBug fix: unify histogram bins rounding issue0.2.2 (2023-02-01)Bug fix: exclude user_time_delta if there is no user with at least two trips.Bug fix: set max_trips_per_user correctly if user_privacy=False.Enhancement: do not exclude jump_length and travel_time if no tessellation is given0.2.1 (2023-01-24)Bug fix: Correct range of scale for visits per time and tile map.0.2.0 (2023-01-23)Create a BenchmarkReport class that evaluates the similarity of two (differentially private) mobility reports from one or two mobility datasets and creates an HTML output similar to the DpMobilityReport.0.1.8 (2023-01-16)Refine handling of OD Analysis input data:warn if there are no trips with more than a single record and exclude OD Analysisuse all trips for travel time and jump length computation instead of only trips inside tessellation.0.1.7 (2023-01-10)Restructuring of HTML headlines.0.1.6 (2023-01-09)Refactoring of template files.0.1.5 (2022-12-12)Remove scikit-mobility dependency and refactor od flow visualization.0.1.4 (2022=12=07)Remove Google Fonts from HTML.0.1.3 (2022-12-05)Handle FutureWarning of pandas.0.1.2 (2022-11-24)Enhanced documentation for all properties ofDpMobilityReportclass0.1.1 (2022-10-27)fix bug: prevent error “keytripsnot found” intrips_over_timeif sum oftrip_countis 00.1.0 (2022-10-21)make tessellation an Optional parameterallow DataFrames without timestamps but sequence numbering instead (i.e.,integerfortimestampcolumn)allow to set seed for reproducible sampling of the dataset (according tomax_trips_per_user)0.0.8 (2022-10-20)Fixes addressing deprecation warnings.0.0.7 (2022-10-17)parameter for a custom split of the privacy budget between different analysesextend ‘analysis_selection’ to include single analyses instead of entire segmentsparameter for ‘analysis_exclusion’ instead of selectionbug fix: include all possible categories for days and hour of daysbug fix: show correct percentage of outliersshow 95% confidence-interval instead of upper and lower boundshow privacy budget and confidence interval for each analysis0.0.6 (2022-09-30)Remove scaling of counts to match a consistent trip_count / record_count (from ds_statistics) in visits_per_tile, visits_per_time_tile and od_flows. Scaling was implemented to keep the report consistent, though it is removed for now as it introduces new issues.Minor bug fixes in the visualization: outliers were not correctly converted into percentage.0.0.5 (2022-08-26)Bug fix: correct scaling of timewindow counts.0.0.4 (2022-08-22)Simplify naming: fromMobilityDataReporttoDpMobilityReportSimplify import: fromfrom dp_mobility_report import md_report.MobilityDataReporttofrom dp_mobility_report import DpMobilityReportEnhance documentation: change style and correctly include API reference.0.0.3 (2022-07-22)Fix broken link.0.0.2 (2022-07-22)First release to PyPi.It includes all basic functionality, though still in alpha version and under development.0.0.1 (2021-12-16)First version used for evaluation in Alexandra Kapp, Saskia Nuñez von Voigt, Helena Mihaljević & Florian Tschorsch (2022) Towards mobility reports with user-level privacy, Journal of Location Based Services, DOI: 10.1080/17489725.2022.2148008.