Scrittura Actual [Python]

Un tutorial su come scrivere step by step le serie temporali Actual in Artesian con l'SDK Python.

Artesian ti permette non solo di avere un accesso semplice allo storico dei dati ma anche di poterne scrivere di nuovi al suo interno.

Vediamo passo passo come procedere.

Obiettivo

Scrivere i nostri dati in un Actual Time Serie Market Data.

I dati e i link di riferimento sono fittizi, creati appositamente per questo case. In Artesian è possibile scrivere qualsiasi dato che sia riconducibile a una Time Serie.

Vediamo passo per passo come procedere.

Importazione delle librerie e configurazione di Artesian

La prima cosa da fare per poter utilizzare tutte le funzionalità di Artesian è autenticarsi. Per fare ciò dobbiamo importare la libreria di base più una serie di moduli che saranno necessari per istanziare l’autenticazione verso Artesian (linea 5 dello script) e successivamente per scrivere i dati nel sistema.

Per poter scrivere le Time Series ed utilizzare la TimeZone, dobbiamo importare “datetime” dalla libreria datetime e  “tz” dalla libreria dateutil. 

Una volta importate le librerie necessarie, possiamo configurare Artesian, inserendo il link necessario e l’api-key.

Per poter estrarre questi due dati importanti, si può far riferimento al tutorial di riferimento “Come Configure Artesian Python SDK“. 

Terminata la configurazione di Artesian, possiamo configurare il MarketData Service.

				
					from Artesian import ArtesianConfig, Granularity, MerketData
from Artesian.MarketData import AggregationRule
from datetime import datetime
from dateutil import tz

cfg = ArtesianConfig("https://arkive.artesian.cloud/{tenantName}/", "{api-key}")
mkservice = MarketData.MarketDataService(cfg)
				
			


Il MarketData Identifier e i dati necessari per la scrittura dell'Actual TimeSeries

Una volta configurato Artesian e il MarketData Service, possiamo definire il MarketData Identifier, ovvero possiamo dare un nome al nostro MarketData.

Il nome del Provider, in questo caso sarà “PythonSDK”, mentre il nome del Market Data sarà “ActualWrite”. “Provider” e “MarketData name” costituiscono l’identificatore univoco di ogni curva scritta all’interno del sistema,  è quindi necessario sceglierli accuratamente perché non sarà poi più possibile cambiarli. Tale combinazione di informazioni sarà anche utile all’interno della UI di Artesian per poter ritrovare il dato scritto.

Definiti i nomi del market data e del provider, possiamo passare al decidere le caratteristiche di base della nostra Time Serie, come il tipo di Granularità, il tipo della Time Serie, la TimeZone, l’eventuale Aggregation Rule e le Tags.

Artesian può supportare diverse granularità come: 10min, 15min, 30min, Hour, Day, Week, Month, Quarter, Season e Year.

Nel momento in cui decidiamo il tipo di granularità del nostro market data, lo dobbiamo scrivere di conseguenza, indicandone i valori. Nel caso di Granularity.Day, i dati corrisponderanno a un determinato giorno, di un determinato mese, di un determinato anno. Nel caso di Granularity.Hour, i dati corrisponderanno a una determinata ora (minuto e secondo) di uno stesso determinato giorno in  un determinato anno.

Il tipo della Time Serie, in questo caso è Actual, ma potrebbe essere anche Versioned, MarketAssessment, BidAsk oppure Auction. Vedi gli altri tutorial.

Le TimeZone va valorizzata con quella corrispondente al dato che stiamo salvando, questo aiuterà il sistema ad applicare le conversioni necessarie ai dati nel caso di estrazioni in una TimeZone differente dall’originale 

L’Aggregation Rule è quella funzionalità di Artesian che permette di estrarre i dati anche a granularità differenti da quella originale. L’operazione di aggregazione/disaggregazione applicata ai dati è definita tramite la valorizzazione di questa proprietà. Le possibili opzioni sono “Undefined”, “SumAndDivide” oppure “AverageAndReplicate”. Nel caso di “Undefined” non sarà ovviamente possibile estrarre i dati a granularità differenti dall’originale.

In fine le Tags non sono obbligatorie, possono però essere utili nel categorizzare i nostri dati per poi permetterci di ritrovarli più rapidamente, scorrendo il menù del portale. In questo nostro specifico caso, setteremo le tags come “TutorialSDKPython”, con all’interno “PythonValue1” per questo nostro market data.

				
					mkdir = MarketData.MarketDataIdentifier("PythonSDK","ActualWrite1")

mkd = MarketData.MarketDataEntityInput(
    providerName=mkdir.provider,
    marketDataName=mkdir.name,
    originalGranularity=Granularity.Day,
    type=MarketData.MarketDataType.ActualTimeSerie,
    originalTimezone="CET",
    aggregationRule=AggregationRule.AverageAndReplicate,
    tags=
    {
        "TutorialSDKPython": ["PythonValue1"]
    }
)
				
			


Controllo e registrazione del MarketData

E’ buona prassi, per evitare errori involontari nell’esecuzione del nostro script, di verificare se il MarketData definito esista già o meno a sistema. Per farlo si esegue lo script riportato sotto in cui utilizzando il Provider e MarketData name è possibile richiedere i dati di registrazione di una curva, se questa esiste già, non occorre fare altro, nel caso non vi sia alcun riscontro, è possibile registrare la nuova curva, attraverso il comando “registerMarketData”.

 

				
					registered = mkservice.readMarketDataRegistryByName(mkdir.provider, mkdir.name)
if(registered is None):
    registered = mkservice.registerMarketData(mkd)
				
			


Scrittura dei valori del MarketData

L’ultima parte del nostro codice consiste nell’andare a configurare la scrittura verso Artesian.

I parametri necessari per farlo sono:

Il Marketdata identifier che abbiamo definito all’inizio del nostro codice

La TimeZone di riferimento del dato, questa deve essere “UTC” nel caso di dati a granularità oraria o inferiore (ovviamente con l’adeguata conversione dei dati se necessario), deve invece corrispondere all’OriginalTimezone nel caso di dati a granularità giornaliera o superiore.

Le rows della nostra Actual TimeSerie sono un dictionary di dati in cui la copia “chiave” “valore” è articolata come segue:

  • “chiave” che corrisponde al datetime di riferimento del dato
  • “valore” che corrisponde al numero che vogliamo inserire per quell’istante di tempo
 

Nell’esempio di codice riportiamo sia la scrittura di dati giornalieri, con valori per il primo e secondo Gennaio, sia di valori orari per il primo Gennaio, che vanno dallo ore 5AM alle ore 8AM. Scrivere valori a due differenti granularità non è supportato da Artesian, è stato fatto solamente a titolo di esempio. I dati devo sempre essere scritti alla granularità originale del dato, definita in fase di creazione del Marketdata identifier

Un altro campo obbligatorio da scrivere è il  DownloadedAt, un’informazione di tipo metadata che rappresenta quando il dato è stato generato.

Una volta inseriti i valori e definito il momento di generazione dei dati, possiamo caricare l’Actual Time Serie nel sistema, attraverso il comando “upsertData“.

				
					actual = MarketData.UpsertData(mkdir, "CET",
    rows=
    {
        # Granularity.Day
        datetime(2021,1,1):42.0,
        datetime(2021,1,2):43.0,
        ...
        # Granularity.Hour
        datetime(2021,1,1,5,0,0):42.0,
        datetime(2021,1,1,6,0,0):43.0,
        datetime(2021,1,1,7,0,0):45.0,
        datetime(2021,1,1,8,0,0):44,0,
        ...
    }
    downloadedAt = datetime(2021,1,3).replace(tzinfo=tz.UTC)
    )
    mkservice.upsertData(actual)
				
			


Visualizzazione del nuovo MarketData nel portale Artesian

A meno che non ci siano errori da segnalare, nel terminal non apparirà nulla. Possiamo però, tornando sul portale di Artesian, verificare che la nostra TimeSerie appaia sotto la categoria ProviderName con il nome, datole precedentemente, di “PythonSDK”. Scorrendo il menù, possiamo anche notare la voce “TutorialSDKPython”, che non è altro che il nostro tag.

 

Basta eseguire l’operazione una sola volta per poi averla completamente riproducibile e automatizzata nel nostro workflow.

Questo non solo permette di risparmiare tempo, ma permette anche di ridurre al minimo gli errori umani dati dall’eseguire operazioni ripetute su grandi moli di dati o su diversi file Excel. 

Un vantaggio innegabile che ci consente di focalizzarci sull’analisi del dato invece che sulla sua gestione e ottimizzazione.