<commit_before>GeosPy: Geolocation Inference Made Easy
=======================================

.. image:: https://travis-ci.org/tylfin/GeosPy.svg?branch=master
    :target: https://travis-ci.org/tylfin/GeosPy

GeosPy is a MIT Licensed Geolocation Inference Library, written in Python.

Of the few existing Python modules for conducting geolocation inference,
most are verbose and cumbersome.

.. code-block:: python

    >>> from GeosPy import Geos
    >>> geosPy = Geos()
    >>> print(geosPy.models)
    frozenset({'jakartr', 'backstrom'})
    >>> geosPy = geosPy.set_model('backstrom')
    >>> user_location_dict = {'Tyler': (44, -71.5), 'Fake': None}
    >>> user_friend_dict = {'Fake':['Tyler']}
    >>> print(geosPy.locate(user_location_dict, user_friend_dict))
    {'Tyler': (44, -71.5), 'Fake': (44, -71.5)}
    ...

GeosPy is based off of `Jurgens et al. (2015)`_, implementing state-of-the-art
methods for geolocation inference. It allows the user to locate nodes with unknown locations
based solely on network-based relationships.


Features
--------

- Python3.3, 3.4 and 3.5 Support
- Highly optimized cython code
- State-of-the-art methods
- Code coverage


Installation
------------

TODO


Documentation
-------------

TODO


Contribute
----------

#. Check for open issues or open a fresh issue to start a discussion around a feature idea or a bug.
#. Fork `the repository`_ on GitHub to start making your changes to the **master** branch (or branch off of it).
#. Write a test which shows that the bug was fixed or that the feature works as expected.
#. Send a pull request and bug the maintainer until it gets merged and published. Make sure to add yourself to `AUTHORS`_.

.. _the repository: http://github.com/tylfin/GeosPy
.. _AUTHORS: https://github.com/tylfin/GeosPy/blob/master/AUTHORS
.. _Jurgens et al. (2015): http://www-cs.stanford.edu/~jurgens/docs/jurgens-et-al_icwsm-2015.pdf<commit_msg>Update README with install instructions and doc<commit_after>GeosPy: Geolocation Inference Made Easy
=======================================

.. image:: https://travis-ci.org/tylfin/GeosPy.svg?branch=master
    :target: https://travis-ci.org/tylfin/GeosPy

GeosPy is a MIT Licensed Geolocation Inference Library, written in Python.

Of the few existing Python modules for conducting geolocation inference,
most are verbose and cumbersome.

.. code-block:: python

    >>> from GeosPy import Geos
    >>> geosPy = Geos()
    >>> print(geosPy.models)
    frozenset({'jakartr', 'backstrom'})
    >>> geosPy = geosPy.set_model('backstrom')
    >>> user_location_dict = {'Tyler': (44, -71.5), 'Fake': None}
    >>> user_friend_dict = {'Fake':['Tyler']}
    >>> print(geosPy.locate(user_location_dict, user_friend_dict))
    {'Tyler': (44, -71.5), 'Fake': (44, -71.5)}
    ...

GeosPy is based off of `Jurgens et al. (2015)`_, implementing state-of-the-art
methods for geolocation inference. It allows the user to locate nodes with unknown locations
based solely on network-based relationships.


Features
--------

- State-of-the-art geolocation inference method(s)
- Supports python 3.3, 3.4 and 3.5
- Written in cython
- Test coverage


Installation
------------

To install GeosPy from source run the following commands

.. code-block:: bash

    > git clone https://github.com/tylfin/GeosPy/
    > cd GeosPy
    > pip install -r requirements.txt
    ...
    Successfully installed ...
    > make build_inplace
    ...
    > make test
    ...
    OK
    > make install
    ...
    
PIP support coming soon!
    
Documentation
-------------

The GeosPy library makes one wrapper class Geos available with three public methods:

 - set_model: sets the model to be used by GeosPy
    - takes as input the name of an available model, and outputs the instatiated class with model set
    - raises NameError if model not available
 - train: trains the model (optional in most cases) using the given data
    - takes as input a key to location (latitude, longitude) or None dictionary, a key to keys dictionary.
 - locate: runs the model, returning users approximate location
    - takes as input a key to location (latitude, longitude) or None dictionary, a key to keys dictionary, and outputs a dictionary run against the model.
    
That's it! 


Contribute
----------

#. Check for open issues or open a fresh issue to start a discussion around a feature idea or a bug.
#. Fork `the repository`_ on GitHub to start making your changes to the **master** branch (or branch off of it).
#. Write a test which shows that the bug was fixed or that the feature works as expected.
#. Send a pull request and bug the maintainer until it gets merged and published. Make sure to add yourself to `AUTHORS`_.

.. _the repository: http://github.com/tylfin/GeosPy
.. _AUTHORS: https://github.com/tylfin/GeosPy/blob/master/AUTHORS
.. _Jurgens et al. (2015): http://www-cs.stanford.edu/~jurgens/docs/jurgens-et-al_icwsm-2015.pdf
.. _clone the repository: https://help.github.com/articles/cloning-a-repository/
{'fraction_non_alphanumeric': 0.13561014579588576, 'fraction_numerical': 0.013181545835829839, 'mean_word_length': 3.3434518647007807, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 51, 'https://': 8, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3971395', 'n_tokens_mistral': 1582, 'n_tokens_neox': 1500, 'n_words': 551}