#!/usr/bin/env python
# coding: utf-8

# # Module 6
# 
# ## Video 26: Inspecting Cargo Movements
# **Python for the Energy Industry**
# 
# In this lesson, we take a closer look at the structure of a Cargo Movement. 
# 
# [Cargo movements documentation.](https://vortechsa.github.io/python-sdk/endpoints/cargo_movements/)

# In[1]:


# imports
from datetime import datetime
from dateutil.relativedelta import relativedelta
import pandas as pd
import vortexasdk as v
now = datetime.utcnow()


# Let's start with a basic query to the SDK, for all Cargo Movements that are currently loading. We then look at one of these:

# In[2]:


# basic query
cm_query = v.CargoMovements().search(
    filter_activity="loading_state",
    filter_time_min=now,
    filter_time_max=now)

# remember - cm_query is a *list* of cargo movements

# taking a look at a single Cargo Movement
cm_query[0]


# There's a lot of information here. Note that this is a 'dictionary' structure, so we can put out the top level keys, and their type:

# In[3]:


cm_query[0].keys()


# In[4]:


print([type(cm_query[0][cmk]) for cmk in cm_query[0]])


# Three of these keys correspond to individual vales which we can print out:

# In[5]:


print('cargo_movement_id:', cm_query[0]['cargo_movement_id'])
print('quantity:', cm_query[0]['quantity'])
print('status:', cm_query[0]['status'])


# The remaning keys are lists, which we now now describe in turn.
# 
# `vessels` contains a `VesselEntity` for each vessel involved in the Cargo Movement. In general, there can be multiple vessels, but we shall touch on this later. The Cargo Movement we're looking only contains one `VesselEntity`:

# In[6]:


vessels = cm_query[1]['vessels']
len(vessels)


# In[7]:


vessels[0]


# `products` contains Product Entries, which each describe one layer of the product tree (Group, Group Product, Category, and Grade). Not all products specify a Grade. We can view the Product Entries in a DataFrame:

# In[8]:


products = cm_query[0]['product']
pd.DataFrame(products)


# `events` contains Cargo Events, which each describe a specific event happening to the cargo at a specific time. These can be:
# - cargo_port_load_event
# - cargo_port_unload_event
# - cargo_fso_load_event
# - cargo_fso_unload_event
# - cargo_sts_event
# - cargo_fixture_event
# - cargo_storage_event
# 
# In our example, the two events are:

# In[9]:


events = cm_query[1]['events']
[e['event_type'] for e in events]


# We can see some high level information about these events by putting them into a DataFrame:

# In[10]:


pd.DataFrame(events)


# The 'location' entries are themselves dictionaries, which we can expand into a DataFrame to see the different layers:

# In[11]:


pd.DataFrame(events[0]['location'])


# **A point to keep in mind**
# 
# In this lesson we have dived into the structure of a Cargo Movement. While important for understanding, in practice it is often simpler to just use cm_query.to_df('all') to convert all these records to a familiar tabular form, without paying attention to the structure. This is true of other endpoints as well.

# ### Exercise
# 
# The Vortexa SDK also offers a `VesselMovements` endpoint. Vessel Movements can be searched for in a similar way to Cargo Movements, but they have some differences. Do a query for Vessel Movements, and inspect the structure of a Vessel Movement to identify the differences.
# 
# [Vessel Movements documentation.](https://vortechsa.github.io/python-sdk/endpoints/vessel_movements/)

# In[ ]: