Package: rancoord
RanCoordRanCoord is a Python package for random sampling of geographic coordinates!About The ProjectThis project arises within the scope of research and development activities in the area of freight transport with respect to vehicle routing problems. Geographic coordinates are one of the most accurate means of identifying a location with extreme sensitivity.Thus, with this project it is intended:Reduce the time and effort required to acquire geographic coordinates within a specific locationEliminate the need to use geographic data that do not fit a particular problem to be addressedProvide geographic coordinates in an extremely easy, fast and customized way to the user's needsAs time goes on, according to my availability and the feedback offered by users it is expected that new features will be included in this package that can make life easier for users addressing vehicle routing problems associated with geographic coordinates.
A list of commonly used resources that I find helpful are listed in the acknowledgements.Built WithThe major frameworks used to build this project were:PythonFoliumProject OSRMGetting StartedThis section presents how the package can be reached and installed.Where to get itThe source code is currently hosted on GitHub at:https://github.com/hugodscarvalho/rancoordBinary installer for the latest released version are available at the Python Package Index (PyPI).pipinstallrancoordUsage1. Import the packageThe first step in using the package is, after it has been installed, to import it.importrancoordasrc2. Geographical polygonIn order to be able to generate a number of random geographic coordinates within a specific location it is necessary to create the polygon that encompasses it. The package provides three different ways to approach this prerequisite.2.1. Use the default polygonIf you choose this option, there's no need to define it, the geographic randomizer module will already have it defined. Geographic data comprised in it:poly=Polygon([(38.78562804689748,-9.47276949903965),(38.713870245772654,-9.139059782242775),(38.89740476139506,-9.055975675797463),(38.96871087768789,-8.969115019059181),(39.05061092686942,-8.92894625685215),(39.08579612091302,-9.407538175797463),(38.984457987516386,-9.397238493180275),])Map visualization:2.2. Create your own polygonIf you choose this option, you will have to define the polygon using some geographic tool as the app fromHeadwall Photonics, copy the coordinates, structure them and define de polygon.2.3. Get a polygon using an address usingIf you choose this option, you can get a polygon based on thebounding boxof an address or location usingNoninatim.# Get the bounding boxbounding_box=nominatim_geocoder('Braga, Portugal')# Create a polygon based on the previously created bounding boxpoly=polygon_from_boundingbox(bounding_box)3. Randomize the geographic coordinatesOnce the geographic polygon has been defined, the next step is to generate the geographic coordinates. You can also choose to modify the number of locations to generate within the polygon (default is10). In addition, although by default these options are disabled, you can choose to save the geographic coordinates and to save a map containing them (options explained below).lat,lon=coordinates_randomizer(polygon=poly,num_locations=50,plot=True,save=True)This method will return two lists, one with the latitudes and one with the longitudes with the following characteristics:Locations within the previously defined polygon50 locationsA plot will be saved in the/mapsfolder with the .html format and named by defaultmap_DDMMYYYY_HHMMSSwith the temporal information of locations generation.A file containing the locations will be saved in the/coordinatesfolder with the default.jsonformat and named by defaultcoordinates_DDMMYYYY_HHMMSSwith the temporal information of locations generation.4. [EXTRA] Auxiliar methodsThe following methods were used in the development of this random geocraphic coordinates generation.create_dirnominatim_geocoderpolygon_from_boundingboxlist_averageplot_coordinatesmultiple_formats_saverhaversine_distancevincenty_distanceosrm_distancedistance_matrixcreate_dir( dir_name )Auxiliar function to createa new directoryif it doesn't already exists. User can choose to name the specific location.Argumentsdir_name[String] : Address the new name.Defaultsto'data'.Exampledir_name='example'create_dir(dir_name)nominatim_geocoder(address)Function to geocode an address using the Nominatim geocoder and return the bounding box of the address.Argumentsaddress[String] :  Address to geocode.RaisesValueError(address): The introduced adress was not found. Please introduce a valid address.Returns[List] : List of coordinates of the bounding box of the address.Examplebounding_box=nominatim_geocoder(address='Barcelona, Spain')polygon_from_boundingbox(boundingbox)Function to create a polygon from a bounding box.Argumentsboundingbox[List] : List of coordinates of the bounding box.Returns[Polygon] : Polygon created from the bounding box.Examplepoly=polygon_from_boundingbox(boundingbox=bounding_box)list_average(list_of_numbers)Function to calculate the average of a list of numbers in order to center geographical map.Argumentslist_of_numbers[List] : List of numbers.Returns[float] : Average of the list of numbers.Exampleavg=list_average(list_of_numbers=[1,2,2,3,6,7])plot_coordinates(list_of_numbers)Function to calculate the average of a list of numbers in order to center geographical map.Argumentslat[List] : List of numbers.lon[List] : List of numbers.zoom[Integer] :  Zoom level of the map. Defaults to 11.save[Boolean] : If True, the map will be saved. Defaults to True.Returns[Folium Map] : Folium map with the coordinates.Examplemap=plot_coordinates(lat=lat,lon=lon,zoom=11,save=True)multiple_formats_saver(lat, lon, columns, file_format, file_name, dir_name)This function saves the coordinates lat and lon as the names introduced
in a given columns list ('Latitude' and 'Longitude' by default). The
coordinates are saved in a given format introduced by the user among the
possibilities csv, json, txt and xlsx (json by default) and the output
file name is also given by the user as file_name. User can choose the
directory name where the output file will be saved.Argumentslat[List] : List of latitude values.lon[List] : List of longitude values.columns[Integer] :  Column names. Defaults to ['Latitude', 'Longitude'].file_format[String] : File format. Defaults to 'json'.file_name[String] : File name. Defaults to 'coordinates'.dir_name[String] : Directory name. Defaults to 'coordinates'.RaisesAssertionError(lat): No values found on the latitude list.AssertionError(lon): No values found on the longitude list.AssertionError(lat & lon): The lists must have the same length.AssertionError(columns): No column names found.AssertionError(columns): The column names list must have two elements.AssertionError(file_name): No file name found.AssertionError(dir_name): No directory name found.Returns[None] : None.Examplemultiple_formats_saver(lat=lat,lon=lon,columns=['Latitude','Longitude'],file_format='json',file_name='coordinates',dir_name='coordinates')haversine_distance(pickup_lat, pickup_long, dropoff_lat, dropoff_long, miles)The haversine formula is used to calculate the great-circle distance between two points on a sphere given their longitudes and latitudes.Argumentspickup_lat[float] : The latitude of the pickup location.pickup_long[float] : The longitude of the pickup location.dropoff_lat[float] :  The latitude of the dropoff location.dropoff_long[float] :  The longitude of the dropoff location.miles[Boolean] : If True, the output will be in miles. If False, the output will be in kilometers. Defaults to False.Returns[float] : The distance between two points on a sphere.Examplehaversine=haversine_distance(pickup_lat=41.4781,pickup_long=-8.1992,dropoff_lat=40.8761,dropoff_long=-9.1222,miles=False)vincenty_distance(pickup_lat, pickup_long, dropoff_lat, dropoff_long, miles)The function takes the latitude and longitude of two points on the Earth's surface and returns the distance between them in kilometers using the Vincenty's formula.Argumentspickup_lat[float] : The latitude of the pickup location.pickup_long[float] : The longitude of the pickup location.dropoff_lat[float] :  The latitude of the dropoff location.dropoff_long[float] :  The longitude of the dropoff location.miles[Boolean] : If True, the output will be in miles. If False, the output will be in kilometers. Defaults to False.Returns[float] : The distance between two points on the earth using the vincenty's formula.Examplevincenty=vincenty_distance(pickup_lat=41.4781,pickup_long=-8.1992,dropoff_lat=40.8761,dropoff_long=-9.1222,miles=False)osrm_distance(pickup_lat, pickup_long, dropoff_lat, dropoff_long, miles)This function takes in the pickup and dropoff coordinates and returns the distance between them in kilometers by default using the OSRM API.Argumentspickup_lat[float] : The latitude of the pickup location.pickup_long[float] : The longitude of the pickup location.dropoff_lat[float] :  The latitude of the dropoff location.dropoff_long[float] :  The longitude of the dropoff location.miles[Boolean] : If True, the output will be in miles. If False, the output will be in kilometers. Defaults to False.Returns[float] : The distance between two coordinates.Exampleosrm=osrm_distance(pickup_lat=41.4781,pickup_long=-8.1992,dropoff_lat=40.8761,dropoff_long=-9.1222,miles=False)distance_matrix(lat, lon, method)For each pair of geographic coordinates, calculate the distance between them using the specified method and return a matrix of distances.Argumentslat[List] :  List of latitudes.lon[List] : List of longitudes.method[String] :  The method to use to calculate the distances. 'haversine', 'vincenty' or 'osrm'. Vincenty's distance by default.Returns[numpy.ndarray] : A matrix of distances between each pair of coordinates.Examplehaversine=haversine_distance(lat=lat,lon=lon,method='osrm')5. [EXTENDED] Full code usageThe following examples show an extended full code usage of the package.# Get the bouding box of a specified addressbb=nominatim_geocoder(address='Berlin, Germany')# Create the polygon from the bounding boxpoly=polygon_from_boundingbox(boundingbox=bb)# Randomize de coordinates (False to all extra options to use them below)latitudes,longitudes,matrix=coordinates_randomizer(polygon=poly,num_locations=5,plot=False,save=False,matrix=False)# Plot the coordinates in a Folium map and save it to .html formatfolium_map=plot_coordinates(lat=latitudes,lon=longitudes,zoom=11,save=True)# Save the coordinates in an output file (.csv, .xlsx, .txt or .json)multiple_formats_saver(lat=latitudes,lon=longitudes,columns=["Latitude","Longitude"],file_format='json',file_name='coordinates',dir_name='coordinates')# Get the distance matrixmatrix=distance_matrix(lat=latitudes,lon=longitudes,method='osrm')RoadmapSee theopen issuesfor a list of proposed features (and known issues).ContributingContributions are what make the open source community such an amazing place to be learn, inspire, and create. Any contributions you make aregreatly appreciated.Fork the ProjectCreate your Feature Branch (git checkout -b feature/AmazingFeature)Commit your Changes (git commit -m 'Add some AmazingFeature')Push to the Branch (git push origin feature/AmazingFeature)Open a Pull RequestLicenseDistributed under the MIT License. SeeLICENSEfor more information.ContactProject Link:GithubLinkedin:hugodscarvalhoAcknowledgementsFoliumProject OSRMGeopy