vortexa-claude-skills 1.0.0

package/lib/movements.py

@@ -0,0 +1,242 @@
+"""Cargo movement queries and OOW helpers."""
+
+import time as time_module
+from collections import defaultdict
+
+import pandas as pd
+
+
+def _to_utc(ts):
+    """Convert timestamp-like to UTC-aware pandas Timestamp."""
+    if ts is None or pd.isna(ts):
+        return None
+    try:
+        return pd.to_datetime(ts, utc=True)
+    except Exception:
+        try:
+            return pd.to_datetime(ts).tz_localize("UTC")
+        except Exception:
+            return None
+
+
+def _extract_location(event, layer):
+    """Pull location label from event location_details for a given layer."""
+    if getattr(event, "location_details", None):
+        for ent in event.location_details:
+            if getattr(ent, "layer", None) == layer:
+                return ent.label
+    return None
+
+
+def _get_location_timeline(events, layer):
+    """Build chronological timeline of location changes from voyage events."""
+    loc_changes = []
+    for ev in events or []:
+        ts = _to_utc(getattr(ev, "start_timestamp", None))
+        if ts is None:
+            continue
+        loc = _extract_location(ev, layer)
+        if loc:
+            loc_changes.append((ts, loc))
+    loc_changes.sort(key=lambda x: x[0])
+
+    collapsed = []
+    prev_label = None
+    for ts, label in loc_changes:
+        if label != prev_label:
+            collapsed.append((ts, label))
+            prev_label = label
+    return collapsed
+
+
+def _get_location_at_time(location_timeline, target_time):
+    """Find the location in effect at a given time from a timeline."""
+    current_location = None
+    for ts, location in location_timeline:
+        if ts <= target_time:
+            current_location = location
+        else:
+            break
+    return current_location
+
+
+def _build_cargo_location_lookup(voyages, layer):
+    """Build cargo_movement_id (16-char) -> voyage location info lookup."""
+    cargo_voyages = defaultdict(list)
+    for voy in voyages:
+        voyage_id = getattr(voy, "id", None)
+        vessel_name = getattr(voy.vessel, "name", None) if hasattr(voy, "vessel") else None
+        voyage_start = _to_utc(getattr(voy, "start_timestamp", None))
+        voyage_end = _to_utc(getattr(voy, "end_timestamp", None))
+        location_timeline = _get_location_timeline(voy.events, layer)
+        for ev in voy.events or []:
+            if getattr(ev, "event_type", None) == "cargo":
+                cargo_id = getattr(ev, "cargo_movement_id", None)
+                if cargo_id:
+                    cargo_id_short = cargo_id[:16] if len(cargo_id) > 16 else cargo_id
+                    cargo_voyages[cargo_id_short].append({
+                        "voyage_id": voyage_id,
+                        "vessel_name": vessel_name,
+                        "location_timeline": location_timeline,
+                        "voyage_start": voyage_start,
+                        "voyage_end": voyage_end,
+                    })
+    return dict(cargo_voyages)
+
+
+def _get_cargo_location_for_day(cargo_id_short, day, lookup):
+    """Find the location for a cargo on a specific day using voyage location data."""
+    voyage_refs = lookup.get(cargo_id_short, [])
+    if not voyage_refs:
+        return "Unknown"
+
+    day_end = day + pd.Timedelta(days=1)
+
+    for ref in voyage_refs:
+        voyage_start = ref.get("voyage_start")
+        voyage_end = ref.get("voyage_end")
+        if voyage_start and voyage_start < day_end and (voyage_end is None or voyage_end > day):
+            location = _get_location_at_time(ref["location_timeline"], day_end)
+            if location:
+                return location
+
+    for ref in voyage_refs:
+        location = _get_location_at_time(ref["location_timeline"], day_end)
+        if location:
+            return location
+
+    return "Unknown"
+
+
+def cargo_on_water_ts(
+    time_min, time_max, product, unit,
+    location_layer="shipping_region_v2",
+    exclude_intra_country=False, verbose=True,
+):
+    """Build daily cargo-on-water by location using CM-Authoritative approach.
+
+    Uses CargoMovements for authoritative OOW periods/quantities and
+    VoyagesSearchEnriched for location data, joined on cargo_movement_id.
+
+    Returns wide DataFrame: date index, location columns, Total column.
+    """
+    from vortexasdk import CargoMovements, VoyagesSearchEnriched
+
+    total_steps = 5
+    start_time = time_module.time()
+    product_ids = [product] if isinstance(product, str) else list(product)
+
+    if verbose:
+        print(f"Building cargo-on-water (unit: {unit}, layer: {location_layer})")
+
+    # Step 1: CargoMovements
+    if verbose:
+        print(f"Step 1/{total_steps}: Querying CargoMovements...", end=" ", flush=True)
+    step_start = time_module.time()
+    cm_columns = [
+        "cargo_movement_id", "quantity",
+        "events.cargo_oil_on_water_event.0.start_timestamp",
+        "events.cargo_oil_on_water_event.0.end_timestamp",
+    ]
+    cm_params = {
+        "filter_activity": "cargo_on_water_state",
+        "filter_time_min": time_min,
+        "filter_time_max": time_max,
+        "filter_products": product_ids,
+        "cm_unit": unit,
+    }
+    if exclude_intra_country:
+        cm_params["intra_movements"] = "exclude_intra_country"
+
+    raw_cm = CargoMovements().search(**cm_params).to_df(columns=cm_columns)
+    if verbose:
+        print(f"done ({time_module.time() - step_start:.1f}s) - {len(raw_cm):,} cargoes")
+
+    if raw_cm.empty:
+        if verbose:
+            print("No cargo movements found.")
+        return pd.DataFrame()
+
+    cm_df = raw_cm.copy()
+    cm_df["quantity"] = pd.to_numeric(cm_df["quantity"], errors="coerce").fillna(0)
+    cm_df["oow_start"] = pd.to_datetime(
+        cm_df["events.cargo_oil_on_water_event.0.start_timestamp"], utc=True
+    )
+    cm_df["oow_end"] = pd.to_datetime(
+        cm_df["events.cargo_oil_on_water_event.0.end_timestamp"], utc=True
+    )
+    cm_df["cargo_id_short"] = cm_df["cargo_movement_id"].str[:16]
+
+    # Step 2: VoyagesSearchEnriched
+    if verbose:
+        print(f"Step 2/{total_steps}: Querying VoyagesSearchEnriched...", end=" ", flush=True)
+    step_start = time_module.time()
+    voyages = VoyagesSearchEnriched().search(
+        time_min=time_min, time_max=time_max,
+        latest_products=product_ids,
+        voyage_status="laden",
+        voyage_date_range_activity="active",
+    ).to_list()
+    if verbose:
+        print(f"done ({time_module.time() - step_start:.1f}s) - {len(voyages):,} voyages")
+
+    # Step 3: Build location lookup
+    if verbose:
+        print(f"Step 3/{total_steps}: Building location lookup...", end=" ", flush=True)
+    step_start = time_module.time()
+    cargo_location_lookup = _build_cargo_location_lookup(voyages, location_layer)
+    if verbose:
+        print(f"done ({time_module.time() - step_start:.1f}s) - {len(cargo_location_lookup):,} unique cargoes")
+
+    # Step 4: Aggregate by day
+    if verbose:
+        print(f"Step 4/{total_steps}: Aggregating by day...", end=" ", flush=True)
+    step_start = time_module.time()
+    tmin = _to_utc(time_min)
+    tmax = _to_utc(time_max)
+    dates = pd.date_range(start=tmin.normalize(), end=tmax.normalize(), freq="D", tz="UTC")
+    daily_by_location = {d: defaultdict(float) for d in dates}
+
+    for _, cargo in cm_df.iterrows():
+        oow_start = cargo["oow_start"]
+        oow_end = cargo["oow_end"]
+        quantity = cargo["quantity"]
+        cargo_id_short = cargo["cargo_id_short"]
+        if pd.isna(oow_start):
+            continue
+        for day in dates:
+            day_start = day
+            day_end = day + pd.Timedelta(days=1)
+            if oow_start < day_end and (pd.isna(oow_end) or oow_end > day_start):
+                location = _get_cargo_location_for_day(cargo_id_short, day_start, cargo_location_lookup)
+                daily_by_location[day][location] += quantity
+    if verbose:
+        print(f"done ({time_module.time() - step_start:.1f}s) - {len(dates):,} days")
+
+    # Step 5: Build DataFrame
+    if verbose:
+        print(f"Step 5/{total_steps}: Building DataFrame...", end=" ", flush=True)
+    step_start = time_module.time()
+    rows = []
+    for day, locations in daily_by_location.items():
+        for location, qty in locations.items():
+            rows.append({"date": day, "location": location, "value": qty})
+
+    if not rows:
+        if verbose:
+            print("done (no data)")
+        return pd.DataFrame()
+
+    df = pd.DataFrame(rows)
+    wide = df.pivot(index="date", columns="location", values="value").fillna(0)
+    wide["Total"] = wide.sum(axis=1)
+    wide.index = pd.to_datetime(wide.index, utc=True)
+    wide.index.name = "date"
+    wide.columns.name = None
+
+    total_elapsed = time_module.time() - start_time
+    if verbose:
+        print(f"done ({time_module.time() - step_start:.1f}s)")
+        print(f"Complete! Total time: {int(total_elapsed // 60)}m {int(total_elapsed % 60)}s")
+
+    return wide.sort_index()

package/lib/requirements.txt

@@ -0,0 +1,6 @@
+vortexasdk>=0.30.0
+pandas>=2.0
+plotly>=5.18
+python-dotenv>=1.0
+numpy>=1.24
+python-dateutil>=2.8

package/lib/seasonal.py

@@ -0,0 +1,200 @@
+"""Seasonal analysis -- multi-year flows with min/max/avg bands."""
+
+import pandas as pd
+import dateutil.relativedelta
+from datetime import datetime
+
+
+def get_search_blocks(start_y, start_m, start_d, today):
+    """Split date range into 4-year API-compatible blocks (Vortexa max window)."""
+    blocks = []
+    start = datetime(start_y, start_m, start_d)
+    end = start + dateutil.relativedelta.relativedelta(years=4) - dateutil.relativedelta.relativedelta(seconds=1)
+
+    if end > today:
+        blocks.append((start, today))
+    else:
+        blocks.append((start, end))
+
+    while end < today:
+        start += dateutil.relativedelta.relativedelta(years=4)
+        end += dateutil.relativedelta.relativedelta(years=4)
+        if end > today:
+            blocks.append((start, today))
+        else:
+            blocks.append((start, end))
+
+    return blocks
+
+
+def moving_average(data, period, col=None):
+    """Calculate rolling moving average on a DataFrame."""
+    if col is None:
+        moving_avg = pd.DataFrame(data.iloc[:, 1:].rolling(window=period, min_periods=1).mean())
+        moving_avg_df = pd.concat([data.iloc[0:, 0:1], moving_avg], axis=1)
+        moving_avg_df.columns = list(data.columns)
+    else:
+        moving_avg = pd.DataFrame(data[col].rolling(window=period, min_periods=1).mean())
+        moving_avg.columns = [f"{period}-day moving_avg"]
+        data_cols = list(data.columns)
+        date_cols = [x for x in data_cols if x != col]
+        moving_avg_df = pd.concat([data[date_cols], moving_avg], axis=1)
+        moving_avg_df.rename(columns={f"{period}-day moving_avg": "value"}, inplace=True)
+
+    return moving_avg_df
+
+
+def seasonal_charts(data, freq, start_y):
+    """Convert flows data to seasonal min/max/avg/current/last-year format."""
+    df = data[data["dd_mmm"] != "29-Feb"]
+    df.reset_index(drop=True, inplace=True)
+
+    current_date = datetime.today()
+    this_year = current_date.year
+    last_year = this_year - 1
+    stats_end_y = last_year
+    stats_start_y = start_y
+
+    stats_df = df[(df["year"] >= stats_start_y) & (df["year"] <= stats_end_y)]
+    this_year_df = df[df["year"] == this_year]
+
+    if freq == "day":
+        start_date = datetime(2023, 1, 1)
+        end_date = datetime(2023, 12, 31)
+        date_range = pd.DataFrame(pd.date_range(start=start_date, end=end_date, freq="1D"), columns=["Date"])
+        date_range["Date"] = date_range["Date"].dt.strftime("%d-%b")
+
+        mins, maxs, avgs, this_year_vals = [], [], [], []
+
+        for i in range(len(date_range)):
+            temp = stats_df[stats_df["dd_mmm"] == date_range["Date"][i]]
+            mins.append(min(temp["value"]))
+            maxs.append(max(temp["value"]))
+            avgs.append(temp["value"].mean())
+
+        last_year_df = pd.DataFrame(stats_df[stats_df["year"] == last_year]["value"])
+        last_year_df.columns = ["Last year"]
+        last_year_df.reset_index(drop=True, inplace=True)
+
+        for i in range(len(date_range)):
+            temp = this_year_df[this_year_df["dd_mmm"] == date_range["Date"][i]]
+            if len(temp) != 0:
+                this_year_vals.append(temp["value"].iloc[0])
+            else:
+                this_year_vals.append("")
+
+        mins_df = pd.DataFrame(mins, columns=["Min."])
+        maxs_df = pd.DataFrame(maxs, columns=["Max."])
+        avgs_df = pd.DataFrame(avgs, columns=[f"Average {stats_start_y}-{stats_end_y}"])
+        this_year_vals_df = pd.DataFrame(this_year_vals, columns=["Current year"])
+
+        seasonal_df = pd.concat([date_range, mins_df, maxs_df, avgs_df, last_year_df, this_year_vals_df], axis=1)
+        seasonal_df[f"Range {stats_start_y}-{stats_end_y}"] = seasonal_df["Max."] - seasonal_df["Min."]
+        seasonal_df = seasonal_df[
+            ["Date", "Min.", f"Range {stats_start_y}-{stats_end_y}",
+             f"Average {stats_start_y}-{stats_end_y}", "Last year", "Current year"]
+        ]
+
+    elif freq == "month":
+        start_date = datetime(2023, 1, 1)
+        end_date = datetime(2023, 12, 31)
+        date_range = pd.DataFrame(pd.date_range(start=start_date, end=end_date, freq="ME"), columns=["Date"])
+        date_range["Date"] = date_range["Date"].dt.strftime("%b")
+
+        mins, maxs, avgs, this_year_vals = [], [], [], []
+
+        for i in range(len(date_range)):
+            temp = stats_df[stats_df["month"] == date_range["Date"][i]]
+            mins.append(min(temp["value"]))
+            maxs.append(max(temp["value"]))
+            avgs.append(temp["value"].mean())
+
+        last_year_df = pd.DataFrame(stats_df[stats_df["year"] == last_year]["value"])
+        last_year_df.columns = ["Last year"]
+        last_year_df.reset_index(drop=True, inplace=True)
+
+        for i in range(len(date_range)):
+            temp = this_year_df[this_year_df["month"] == date_range["Date"][i]]
+            if len(temp) != 0:
+                this_year_vals.append(temp["value"].iloc[0])
+            else:
+                this_year_vals.append("")
+
+        mins_df = pd.DataFrame(mins, columns=["Min."])
+        maxs_df = pd.DataFrame(maxs, columns=["Max."])
+        avgs_df = pd.DataFrame(avgs, columns=[f"Average {stats_start_y}-{stats_end_y}"])
+        this_year_vals_df = pd.DataFrame(this_year_vals, columns=["Current year"])
+
+        seasonal_df = pd.concat([date_range, mins_df, maxs_df, avgs_df, last_year_df, this_year_vals_df], axis=1)
+        seasonal_df[f"Range {stats_start_y}-{stats_end_y}"] = seasonal_df["Max."] - seasonal_df["Min."]
+        seasonal_df = seasonal_df[
+            ["Date", "Min.", f"Range {stats_start_y}-{stats_end_y}",
+             f"Average {stats_start_y}-{stats_end_y}", "Last year", "Current year"]
+        ]
+
+    return seasonal_df
+
+
+def complete_seasonal_flows(
+    start_y, start_m, start_d,
+    product_ids, product_ids_excl,
+    freq, unit, activity,
+    origin_ids, origin_ids_excl,
+    destination_ids, destination_ids_excl,
+    storage_location_ids=None,
+    ma_period=None, exclude_intra=True,
+):
+    """End-to-end: query flows -> optional MA -> seasonal format. Returns seasonal DataFrame."""
+    from vortexasdk import CargoTimeSeries
+
+    today = datetime.today()
+    search_blocks = get_search_blocks(start_y, start_m, start_d, today)
+
+    intra_movements = "exclude_intra_country" if exclude_intra else "all"
+
+    result_dfs = pd.DataFrame()
+    for block in search_blocks:
+        time_min = block[0]
+        time_max = block[1]
+
+        result = CargoTimeSeries().search(
+            filter_time_min=time_min,
+            filter_time_max=time_max,
+            filter_origins=origin_ids,
+            exclude_origins=origin_ids_excl,
+            filter_destinations=destination_ids,
+            exclude_destinations=destination_ids_excl,
+            filter_storage_locations=storage_location_ids,
+            filter_products=product_ids,
+            exclude_products=product_ids_excl,
+            intra_movements=intra_movements,
+            filter_activity=activity,
+            timeseries_frequency=freq,
+            timeseries_unit=unit,
+        ).to_df(columns="all")
+
+        result2 = result[["key", "value"]]
+        result2.columns = ["date", "value"]
+        result_dfs = pd.concat([result_dfs, result2])
+
+    result_dfs = result_dfs.copy()
+    result_dfs["date"] = pd.to_datetime(result_dfs["date"])
+    result_dfs["string_date"] = result_dfs["date"].dt.strftime("%d-%m-%Y")
+    result_dfs["dd_mmm"] = result_dfs["date"].dt.strftime("%d-%b")
+    result_dfs["month"] = result_dfs["date"].dt.strftime("%b")
+    result_dfs["week_end_timestamp"] = result_dfs["date"] + pd.offsets.Week(weekday=6)
+    result_dfs["week_number"] = result_dfs["date"].dt.isocalendar().week
+    result_dfs["year"] = round(pd.to_numeric(result_dfs["date"].dt.strftime("%Y")), 0)
+    result_dfs = result_dfs.fillna(0)
+    result_dfs = result_dfs[
+        ["date", "week_end_timestamp", "string_date", "dd_mmm", "week_number", "month", "year", "value"]
+    ]
+    result_dfs.reset_index(drop=True, inplace=True)
+
+    if ma_period is not None:
+        data = moving_average(data=result_dfs, period=ma_period, col="value")
+    else:
+        data = result_dfs
+
+    seasonal_data = seasonal_charts(data=data, freq=freq, start_y=start_y)
+    return seasonal_data