Example usage

Example usage of FlowClient to run daily location, modal location and flow queries.

import flowclient

Create an access token¶

Generate an API access token using FlowAuth.

Create an API connection¶

Paste the access token from FlowAuth here as TOKEN

conn = flowclient.connect(
    url=os.getenv("FLOWAPI_URL", "http://localhost:9090"),
    token=TOKEN,
    ssl_certificate=os.getenv("SSL_CERTIFICATE_FILE"),
)

Daily location¶

Specify query parameters¶

query_spec = flowclient.aggregates.spatial_aggregate_spec(
    locations=flowclient.daily_location_spec(
        date="2016-01-01",
        aggregation_unit="admin3",
        method="last",
        subscriber_subset=None,
    )
)

query_spec

{'locations': {'aggregation_unit': 'admin3',
               'date': '2016-01-01',
               'event_types': None,
               'geom_table': None,
               'geom_table_join_column': None,
               'hours': None,
               'mapping_table': None,
               'method': 'last',
               'query_kind': 'daily_location',
               'subscriber_subset': None},
 'query_kind': 'spatial_aggregate'}

Set query running¶

query_id = flowclient.run_query(connection=conn, query_spec=query_spec)
query_id

8a7f64108b657b89e808c700386e1dc7

Check status of query¶

flowclient.get_status(connection=conn, query_id=query_id)

executing

Get query result¶

df = flowclient.get_result_by_query_id(connection=conn, query_id=query_id)
df.head()

Parts run:   0%|          | 0/9 [00:00<?, ?q/s]

	pcod	value
0	NPL.2.3.3_1	783
1	NPL.5.1.2_1	160
2	NPL.1.3.3_1	340
3	NPL.4.1.1_1	494
4	NPL.1.1.3_1	5302

Alternative (run query, wait for it to finish, and get result, in one function call):

df = flowclient.get_result(connection=conn, query_spec=query_spec)
df.head()

	pcod	value
0	NPL.2.3.3_1	783
1	NPL.5.1.2_1	160
2	NPL.1.3.3_1	340
3	NPL.4.1.1_1	494
4	NPL.1.1.3_1	5302

Specify query parameters¶

Either explicitly from a set of daily locations:

dl1 = flowclient.daily_location_spec(
    date="2016-01-01",
    aggregation_unit="admin3",
    method="last",
    subscriber_subset=None,
)
dl2 = flowclient.daily_location_spec(
    date="2016-01-02",
    aggregation_unit="admin3",
    method="last",
    subscriber_subset=None,
)
ml = flowclient.modal_location_spec(locations=[dl1, dl2])

ml

{'locations': [{'aggregation_unit': 'admin3',
                'date': '2016-01-01',
                'event_types': None,
                'geom_table': None,
                'geom_table_join_column': None,
                'hours': None,
                'mapping_table': None,
                'method': 'last',
                'query_kind': 'daily_location',
                'subscriber_subset': None},
               {'aggregation_unit': 'admin3',
                'date': '2016-01-02',
                'event_types': None,
                'geom_table': None,
                'geom_table_join_column': None,
                'hours': None,
                'mapping_table': None,
                'method': 'last',
                'query_kind': 'daily_location',
                'subscriber_subset': None}],
 'query_kind': 'modal_location'}

Or from a date range:

ml = flowclient.modal_location_from_dates_spec(
    start_date="2016-01-01",
    end_date="2016-01-03",
    aggregation_unit="admin3",
    method="last",
    subscriber_subset=None,
)

ml

{'locations': [{'aggregation_unit': 'admin3',
                'date': '2016-01-01',
                'event_types': None,
                'geom_table': None,
                'geom_table_join_column': None,
                'hours': None,
                'mapping_table': None,
                'method': 'last',
                'query_kind': 'daily_location',
                'subscriber_subset': None},
               {'aggregation_unit': 'admin3',
                'date': '2016-01-02',
                'event_types': None,
                'geom_table': None,
                'geom_table_join_column': None,
                'hours': None,
                'mapping_table': None,
                'method': 'last',
                'query_kind': 'daily_location',
                'subscriber_subset': None}],
 'query_kind': 'modal_location'}

Set query running¶

query_id = flowclient.run_query(
    connection=conn,
    query_spec=flowclient.aggregates.spatial_aggregate_spec(locations=ml),
)
query_id

929deb4c32680f8731b0ac04491396be

Check status of query¶

flowclient.get_status(connection=conn, query_id=query_id)

executing

Get query result¶

df = flowclient.get_result_by_query_id(connection=conn, query_id=query_id)
df.head()

Parts run:   0%|          | 0/10 [00:00<?, ?q/s]

	pcod	value
0	NPL.2.3.3_1	894
1	NPL.5.1.2_1	170
2	NPL.4.1.1_1	559
3	NPL.1.3.3_1	417
4	NPL.1.1.3_1	6056

Alternative:

df = flowclient.get_result(
    connection=conn,
    query_spec=flowclient.aggregates.spatial_aggregate_spec(locations=ml),
)
df.head()

	pcod	value
0	NPL.2.3.3_1	894
1	NPL.5.1.2_1	170
2	NPL.4.1.1_1	559
3	NPL.1.3.3_1	417
4	NPL.1.1.3_1	6056

Flow¶

Specify query parameters¶

Specify parameters for two location queries:

aggregation_unit = "admin1"
dl_past = flowclient.daily_location_spec(
    date="2016-01-01",
    aggregation_unit=aggregation_unit,
    method="last",
    subscriber_subset=None,
)
dl_present = flowclient.daily_location_spec(
    date="2016-01-07",
    aggregation_unit=aggregation_unit,
    method="last",
    subscriber_subset=None,
)

Specify parameters for flow query:

flow = flowclient.aggregates.flows_spec(
    from_location=dl_past,
    to_location=dl_present,
)
flow

{'from_location': {'aggregation_unit': 'admin1',
                   'date': '2016-01-01',
                   'event_types': None,
                   'geom_table': None,
                   'geom_table_join_column': None,
                   'hours': None,
                   'mapping_table': None,
                   'method': 'last',
                   'query_kind': 'daily_location',
                   'subscriber_subset': None},
 'join_type': 'inner',
 'query_kind': 'flows',
 'to_location': {'aggregation_unit': 'admin1',
                 'date': '2016-01-07',
                 'event_types': None,
                 'geom_table': None,
                 'geom_table_join_column': None,
                 'hours': None,
                 'mapping_table': None,
                 'method': 'last',
                 'query_kind': 'daily_location',
                 'subscriber_subset': None}}

Set query running¶

query_id = flowclient.run_query(connection=conn, query_spec=flow)
query_id

35ee5d8a35b0edb5d6e4d7e4e40eb3a5

Check status of query¶

flowclient.get_status(connection=conn, query_id=query_id)

executing

Get query result¶

df = flowclient.get_result_by_query_id(connection=conn, query_id=query_id)
df.head()

Parts run:   0%|          | 0/17 [00:00<?, ?q/s]

	pcod_from	pcod_to	value
0	NPL.1_1	NPL.5_1	836
1	NPL.1_1	NPL.4_1	433
2	NPL.1_1	NPL.3_1	487
3	NPL.1_1	NPL.2_1	1084
4	NPL.1_1	NPL.1_1	10966

Counts of Events by Location¶

df = flowclient.get_result(
    connection=conn,
    query_spec=flowclient.aggregates.location_event_counts_spec(
        start_date="2016-01-01",
        end_date="2016-01-08",
        aggregation_unit="admin3",
        count_interval="hour",
    ),
)
df.head()

Parts run:   0%|          | 0/7 [00:00<?, ?q/s]

	pcod	date	value
0	NPL.1.1.3_1	2016-01-01	511
1	NPL.1.1.5_1	2016-01-01	131
2	NPL.1.1.6_1	2016-01-01	49
3	NPL.1.2.1_1	2016-01-01	75
4	NPL.1.2.3_1	2016-01-01	142

Example usage

Create an access token¶

Create an API connection¶

Daily location¶

Specify query parameters¶

Set query running¶

Check status of query¶

Get query result¶

Modal location¶

Specify query parameters¶

Set query running¶

Check status of query¶

Get query result¶

Flow¶

Specify query parameters¶

Set query running¶

Check status of query¶

Get query result¶

Counts of Events by Location¶