Documentation - Cellyzer

1. Quick Start

1.1 Installation

Binary installers for the latest released version are available at the Python package index : https://pypi.org/project/cellyzer/. Use the pip package manager to install cellyzer.

pip install cellyzer

After installing Cellyzer it can be used in your project by simply importing it

xxxxxxxxxx
import cellyzer as cz

1.2 Reading Datasets

Cellyzer accepts 3 kinds of datasets as below in the given format.

• Call Dataset : user, other_user, direction, duration, timestamp, cell_id, cost
• Message Dataset : user, other_user, direction, length, timestamp
• Cell/Antenna Dataset : cell_id, latitude, longitude

xxxxxxxxxx
call_file_path = "demo_datasets/test_data/calls.csv"
callDataSet = cz.read_call(call_file_path)

Adding a call dataset to Cellyzer is as above. read_msg, read_cell can be used to add message and cell datasets respectively. Default file type for the dataset file is csv. Also you can add xlsx and json files.

xxxxxxxxxx
callDataSet = cz.read_call(file_path="datasets/calls.xlsx", file_type="xlsx")

A dataset object consists of a list of Record objects. A Record object represents a row in the dataset. Accessing the attributes of a Record object gives the values of the fields in that row of the dataset.

1.3 Using Functions

Cellyzer is modeled using object-oriented approach. A dataset you add is kept as an object. Hence you can use your own functions and classes with Cellyzer objects. Also you can access the inbuilt functions for the added dataset objects.

xxxxxxxxxx
all_users_of_call_dataset = callDataSet.get_all_users()
"""This function returns all the users available in the call dataset object"""

xxxxxxxxxx
search_user = "3e97992791"
connected_users = callDataSet.get_connected_users(search_user)
"""This fuction returns all the users that are connected to a given user"""

Other than inbuilt functions for dataset objects, Cellyzer gives some helping functions in utils and visualization modules to print, visualize data.

xxxxxxxxxx
cz.utils.print_dataset(callDataSet)
"""This function can be used to print a dataset object in a table"""

2. Reference

2.1 IO

IO module is to read, write, filter and clean datasets.

IO functions can be accessed directly using the name of the import of the Cellyzer library.

Example:

​x
import cellyzer as cz
​
cz.read_call(file_path)

read_call

xxxxxxxxxx
read_call(file_path='', file_type='csv', hash=True)
    """
    Loads call records dataset and returns a call dataset object
    :param file_path: file path of the dataset
    :param file_type: csv,xlsx,json file types are accepted
    :param hash: hash user phone numbers for privacy
    :return: CallDataset object
    """

read_msg

xxxxxxxxxx
read_msg(file_path='', file_type='csv', hash=True)
    """
    Loads message records dataset and returns a message dataset object
    :param file_path: file path of the dataset
    :param file_type: csv,xlsx,json file types are accepted
    :param hash: hash user phone numbers for privacy
    :return: MessageDataset object
    """

read_cell

xxxxxxxxxx
read_cell(file_path='', call_csv_path=None, call_dataset_obj=None, file_type='csv')
    """
    Loads cell dataset and returns a cell dataset. In order to adda a cell-dataset,
     a call dataset object or call dataset filepath is also needed
​
    :param file_path: file path of the dataset
    :param call_csv_path: file path of the call dataset
    :param call_dataset_obj: call dataset object
    :param file_type: csv,xlsx,json file types are accepted
    :return: CellDataset object
    """

to_csv

xxxxxxxxxx
to_csv(dataset_object, filename)
    """
    Write a dataset object to a csv file
    :param dataset_object: dataset object created
    :param filename: name of the dataset file
    :return: None
    """

to_json

xxxxxxxxxx
to_json(dataset_object, filename):
    """
    Write dataset object to a json file
    :param dataset_object: dataset object created
    :param filename: name of the dataset file
    :return: None
    """

2.2 core

Cellyzer core module consists of all the classes and relevant methods.

Common Functions for Call & Message Datasets

● Get all the users

Returns a list with all the users available in the dataset

xxxxxxxxxx
callDataset.get_all_users()

● Get records of a given user or records between given 2 users

If a single user is given, the system outputs all the records where that user is involved. If two users were given, the system returns a list of records where there had been a call/message between those two users.

xxxxxxxxxx
callDataset.get_records(user1, user2)

● Get connected users

Outputs a list of users that are connected to a given user

xxxxxxxxxx
callDataset.get_connected_users(user)

● Get connections for a given list of users

Returns a list of 2 user lists in the format [user1,user2] where user1 has made a call/message to user2.

xxxxxxxxxx
callDataset.get_connections(users_list, allow_duplicates=False)

● Get the connection matrix

Get a matrix(2D list) with which user is connected to who and the number of calls/messages between them. The matrix is visualized in an HTML page.

xxxxxxxxxx
callDataset.print_connection_matrix()

● Visualize connection network

Generates a graph with the connections within a given list of users. If the graph is directed the arrow head implies the direction of the call/message. The value near the arrow gives the number of connections made to that direction.

xxxxxxxxxx
callDataset.visualize_connection_network(users_list, directed=True, font_size=5)

● Get most active time of a given user

Returns a dictionary with the hours in the day as keys and values as number of calls/messages made. Can get the idea of how the user is active with the time.

xxxxxxxxxx
callDataset.get_most_active_time(user)

● Get close contacts

Get the top contacts who have the most number of messages with a given specific user.

xxxxxxxxxx
callDataset.get_close_contacts(user, top_contact=5)

Functions that are specific for Call datasets

● Get call records by Antenna-ID

Returns all the records related to a given specific cell

xxxxxxxxxx
callDataset.get_call_records_by_antenna_id(cell_id)

● Get ignored call details

Get records of ignored call details of a given user

xxxxxxxxxx
callDataset.get_ignored_call_details(user)

Functions for antenna(cell) datasets

● Get cell records

Returns all the records in the cell dataset

xxxxxxxxxx
cellDataset.get_cell_records()

● Get population

Get population around all the cells or around a given cell ID

xxxxxxxxxx
cellDataset.get_population(self, cell_id=3)

● Get users around a given cell

Returns all the unique users around a given cell_id

xxxxxxxxxx
cellDataset.get_unique_users_around_cell(call_records)

● Get trip details of a given user

Get/print/tabulate trip details of a specific user

xxxxxxxxxx
cellDataset.get_trip_details(user, console_print=False, tabulate=False)

Functions that are specific for a User

● Get home location

Get the home location of a given user

xxxxxxxxxx
userobj.get_home_location()

● Get work location

Get the work location of a given user

xxxxxxxxxx
userobj.get_work_location()

2.3 utils

Printing a list of Record objects

As discussed in the Quick-Start, Cellyzer keeps a dataset as a Dataset object where it contains a list of Record objects. A Record object represents a row in the dataset. In order to print a list of record objects in a readable manner Cellyzer provides a function.

xxxxxxxxxx
cz.utils.print_record_lists(records_list)

Printing a Dataset object

You can have a readable console print of the dataset using the inbuilt function print_dataset. It will print the datasets in a tabulate way. If the dataset is is larger than 50 rows it summarize it with 5 head and 5 tail rows. You can also set the optional parameters head, tail to summarize and tabulate the dataset.

xxxxxxxxxx
cz.utils.print_dataset(messageDataSetObject, name="Message Dataset", head=10, tail=10)

2.4 visualization

Connection Network Graph

Visualize the connections of the given list of user couples in a graph. Nodes are users and Edges are the connections. The arrow head from A to B represent a call/message from user A to B. The edge value near the arrow head represents the number of calls/messages made from A to B.

xxxxxxxxxx
network_graph(edge_list, directed, fig_id, font_size=6, users="All")
    """
    :param edge_list: list of 2 user couples with 1st user made a call to the 2nd
    :param directed: Bool value to switch between directed and undirected graphs
    :param fig_id: unique ID to the figure
    :param users: list of users
    :return: None, visualizes the graph in a web page
    """

Active time - Bar chart

Generates a bar chart of the active time of a given user. X-axis represents the time(hour of the day). Y-axis number of records

xxxxxxxxxx
active_time_bar_chart(time_dict, gui=False, user='xxx')
    """
    :param time_dict: Dictionary of hour and activities as key,value pairs
    :param user: Given User
    :return: None, visualizes the chart in a web page
    """

Population visualization around cells

Visualize a map with population around cells

xxxxxxxxxx
cell_population_visualization(cell_list, map_name="population_map", notebook=False):
    """
    :param cell_list: cells and its respective number of calls
    :param map_name: name of the map to be displayed
    :param notebook: set to True of runs in a notebook
    :return: shows a map with population around cells
    """

Visualize home and work locations

Visualize a map of home and work locations

xxxxxxxxxx
view_home_work_locations(home_location=None, work_location=None, map_name="home_work_location", notebook=False):
    """
    :param home_location: home locations
    :param work_location: work locations
    :param map_name: name of the map to be displayed
    :param notebook: set True if run in notebook
    :return: shows a map with home/work locations around cells
    """

Visualize trips of a user

Visualize the trips/routes of a given user in a map. Very useful to get the behavior of the user. Decisions like w here he spent most of the time, where he wend more frequently can be get easily with this map.

xxxxxxxxxx
trip_visualization(locations, map_name="trip_map", notebook=False):
    """
    :param locations: Locations visited by the user (sorted in timestamp)
    :param map_name: name of the map to be displayed
    :param notebook: set true if runs in notebook
    :return: shows a map of routes of the user
    """