I Dataset scientifici possono contenere osservazioni lungo una coordinata temporale: concentrazioni, tensioni, intensità spettrali, temperature o segnali acquisiti da uno strumento. Molte analisi, però, non hanno bisogno dell’intera serie: vogliamo confrontare fasi di una reazione, esaminare soltanto un transitorio oppure ripetere la stessa elaborazione su finestre successive e parzialmente sovrapposte.

In GX-TXT questo problema è affrontato dalla Temporal Set API v1. Essa permette di definire, conservare e condividere porzioni temporali di un Dataset canonico. La stessa risorsa può essere creata da uno script GNU Octave, letta da uno script Python e successivamente utilizzata da un modulo di analisi, sempre attraverso le API pubbliche e lo Script Bridge.

Un principio importante

Un Temporal Set non è un nuovo Dataset: non copia le misure, non concatena intervalli, non crea file scientifici per ogni finestra e non altera il campionamento originale. È una definizione persistente che il CORE risolve in intervalli di righe e coordinate.

1. Quando conviene utilizzare un Temporal Set?

Un semplice script può già leggere tutto un Dataset tramite CANONICAL_DATASET_API_v2/read_range. Se dobbiamo calcolare una sola derivata sull’intera curva, senza suddividerla né riutilizzare alcuna selezione, un Temporal Set aggiungerebbe complessità senza un vantaggio concreto.

La situazione cambia quando gli intervalli hanno un significato scientifico oppure devono essere riutilizzati. Alcuni esempi:

  • una cinetica divisa in fase iniziale, transitoria e finale, anche con intervalli non adiacenti;
  • una misura strumentale in cui vogliamo escludere i periodi di stabilizzazione;
  • un segnale da analizzare con finestre di durata o numerosità costante, anche sovrapposte;
  • un’analisi FFT a finestre, Welch o cross-spettrale che debba condividere le stesse porzioni di ingresso;
  • script Octave e Python distinti che devono concordare sui medesimi intervalli senza ridefinirli ciascuno.

La risorsa può essere definita una volta e riutilizzata da altri script nella stessa Session GX-TXT. In questo modo la suddivisione fa parte del contesto riproducibile dell’analisi.

2. Due risorse diverse: Segment Set e Window Set

La API distingue due modelli complementari.

TipoCome si definisceImpiego caratteristico
segment_setElenco ordinato di intervalli arbitrari, con etichette e ID stabiliFasi sperimentali, eventi, periodi selezionati manualmente
window_setGeneratore compatto di finestre, con dimensione, passo e politica per la finestra finaleFFT a finestre, Welch, analisi ripetute e sovrapposte

Un Segment Set conserva i propri segmenti, per esempio «avvio», «stabilizzazione» e «regime», anche se sono discontinui. Un Window Set conserva invece la regola di generazione. I suoi membri vengono risolti quando servono, non archiviati singolarmente.

2.1 Gli estremi sono semiaperti

La convenzione è [start, end): il limite inferiore è incluso, quello superiore escluso. Il segmento da 10 a 30 secondi comprende quindi i campioni il cui tempo soddisfa 10 <= t < 30.

Questa scelta permette di affiancare segmenti consecutivi senza contare due volte un campione di confine. Attenzione: se si integra numericamente una serie di campioni selezionati, l’ultimo valore campionato può precedere il limite superiore del segmento. Torneremo su questo punto con un esempio.

Coordinate, righe e indici

Un membro risolto restituisce row_start e row_count. row_start è un offset da zero, coerente con la lettura canonica dei Dataset. Il parametro index di resolve_member, invece, identifica un membro a partire da uno. Confondere queste due convenzioni porta facilmente a selezioni errate.

3. Il Dataset deve avere un vero asse temporale

GX-TXT non deduce automaticamente la semantica temporale da una variabile chiamata time o dall’unità s. È opportuno dichiararla nel Variable Schema quando si pubblica il Dataset.

Nel nostro esperimento useremo 60 campioni sintetici, uno al secondo, con tempi da 0 a 59 s. La concentrazione di una sostanza ipotetica decresce secondo

\[C(t)=4\,e^{-0.055t}\quad\mathrm{mmol/L}.\]

Il codice Octave prepara i vettori:

time_s = (0:59)';
concentration_mmol_L = 4.0 * exp(-0.055 * time_s);

La dichiarazione della coordinata temporale è intenzionalmente esplicita:

x_variable = struct('variable_id', 'time_s', 'name', 'time_s', ...
  'display_label', 'Elapsed time', 'unit', 's', 'dtype', 'float64', ...
  'value_kind', 'number', 'semantic_role', 'elapsed_time', ...
  'time_reference', 'elapsed', 'semantic_source', 'generator');

value_kind=number è adatto perché i tempi sono già numeri in secondi; il ruolo elapsed_time e time_reference=elapsed descrivono la loro interpretazione fisica. Per dati codificati come HH:MM:SS esiste inoltre il contratto specifico di conversione del tempo trascorso. La rappresentazione non va confusa con una data assoluta o con un semplice numero privo di semantica.

Lo script completo Temporal_00_Prepare.m, incluso in fondo all’articolo, pubblica il Dataset temporal_demo_decay tramite DATASET_PUBLICATION_API_v2/publish_series_batch e lo rilegge con CANONICAL_DATASET_API_v2/read_range.

4. Le operazioni pubbliche richiamabili dallo Script Bridge

L’ID del servizio è TEMPORAL_SET_API_v1. Le stesse otto operazioni sono disponibili per gli script gestiti da GNU Octave e Python.

OperazioneArgomenti posizionaliFunzione e risultato
createdefinizioneCrea un Set persistente e restituisce il suo ID
listDataset ID facoltativoElenca i Set, eventualmente filtrati per sorgente
readSet IDRecupera la definizione persistente
resolve_infoSet IDDescrive la risoluzione corrente, inclusi il numero di membri e la sorgente
resolve_memberSet ID, indice da 1Restituisce un membro con ID, limiti e righe da leggere
resolveSet IDRisolve l’intero insieme di membri
updateSet ID, modificheAggiorna una definizione conservando l’identità della risorsa
deleteSet IDElimina esplicitamente il Set, non il Dataset sorgente

temporalSetIterate è una procedura del contesto host che usa callback Tcl: non è una chiamata ammessa allo Script Bridge. Per uno script si usano resolve_info e resolve_member, evitando quando possibile di materializzare in memoria elenchi enormi con resolve.

4.1 Stessa API, sintassi diversa in Octave e Python

In GNU Octave il terzo argomento di gxtxt_api_call è una cell array:

api = 'TEMPORAL_SET_API_v1';
gxtxt_api_require({api});
assert(gxtxt_api_has_operation(api, 'resolve_member'));
member = gxtxt_api_call(api, 'resolve_member', {set_id, 1});

In Python lo stesso elenco di argomenti è una lista:

from gxtxt import gxtxt_api_require, gxtxt_api_call

API = 'TEMPORAL_SET_API_v1'
gxtxt_api_require([API])
member = gxtxt_api_call(API, 'resolve_member', [set_id, 1])

I valori restituiti diventano strutture e celle Octave oppure dizionari e liste Python. Lo Script Bridge controlla le operazioni pubblicamente registrate per la Session corrente: non occorre importare moduli CORE privati né leggere direttamente i file del registro temporale.

5. Esempio GNU Octave: creare tre fasi di una cinetica

Dopo aver pubblicato il Dataset iniziale, definiamo tre intervalli che coprono l’intera sequenza:

segments = {
  struct('label', 'Early decay', 'start', 0, 'end', 10), ...
  struct('label', 'Middle decay', 'start', 10, 'end', 30), ...
  struct('label', 'Late decay', 'start', 30, 'end', 60)
};

definition = struct('type', 'segment_set', ...
  'source_dataset_id', 'temporal_demo_decay', ...
  'temporal_variable_id', 'time_s', ...
  'label', 'Three kinetic phases', 'segments', {segments});

set_id = gxtxt_api_call('TEMPORAL_SET_API_v1', 'create', {definition});

source_dataset_id identifica il Dataset, mentre temporal_variable_id è il suo Variable ID temporale, non un titolo mostrato nella GUI. Il CORE restituisce un ID come tset_001, che può essere riutilizzato da altri script e moduli.

Editor GNU Octave di GX-TXT con codice per creare tre segmenti temporali persistenti
Un Segment Set definisce tre fasi di una cinetica mediante lo Script Bridge Octave.

5.1 Risolvere i segmenti invece di leggere file interni

Dopo la creazione possiamo leggere la definizione con read e chiedere al CORE a quali righe corrisponde il secondo segmento:

member = gxtxt_api_call('TEMPORAL_SET_API_v1', ...
  'resolve_member', {set_id, 2});

block = gxtxt_api_call('CANONICAL_DATASET_API_v2', 'read_range', ...
  {'temporal_demo_decay', {'time_s', 'concentration_mmol_L'}, ...
   member.row_start, member.row_count});

Nell’esempio, la risoluzione restituisce questi intervalli:

SegmentoIntervallo definitorow_startrow_countTempi effettivamente letti
seg_001[0,10) s0100…9 s
seg_002[10,30) s102010…29 s
seg_003[30,60) s303030…59 s

Le tre fasi costituiscono un unico segment_set persistente. Non abbiamo pubblicato tre nuovi Dataset e non abbiamo modificato la sorgente.

6. Esempio Python: leggere i segmenti di Octave e creare finestre sovrapposte

Lo script Python opera nella stessa Session. Prima chiama list per cercare il segment_set, poi risolve il suo secondo membro e legge i 20 campioni con l’API canonica. Questo dimostra che la risorsa non appartiene al linguaggio che l’ha creata.

Definiamo ora un window_set con 10 campioni per finestra e avanzamento di 5 campioni:

from gxtxt import gxtxt_api_call, gxtxt_api_require

API = 'TEMPORAL_SET_API_v1'
gxtxt_api_require([API])

window_definition = {
    'type': 'window_set',
    'source_dataset_id': 'temporal_demo_decay',
    'temporal_variable_id': 'time_s',
    'generator_basis': 'samples',
    'window_size': 10,
    'step': 5,
    'partial_policy': 'drop',
    'label': 'Overlapping 10-sample windows'
}
window_id = gxtxt_api_call(API, 'create', [window_definition])
info = gxtxt_api_call(API, 'resolve_info', [window_id])
print(info['member_count'])  # 11

La sovrapposizione in campioni è

\[\mathrm{overlap}=\frac{10-5}{10}=50\%.\]

Con 60 campioni otteniamo 11 finestre complete. La prima parte dalla riga 0 e contiene 10 valori; l’ultima parte dalla riga 50 e contiene gli ultimi 10. Il CORE genera identificativi deterministici come win_000001 e win_000011.

Editor Python integrato in GX-TXT con Script Bridge e definizione di un Window Set
Python legge i segmenti creati con Octave e prepara finestre temporali sovrapposte.
Output Python di GX-TXT con undici finestre temporali e intervalli di righe risolti
Il CORE produce 11 finestre da 10 campioni con passo di 5 campioni.

6.1 Finestre basate su campioni e finestre basate su durata

Con generator_basis=samples, window_size e step sono numeri di campioni. Il 50% qui indica sovrapposizione di righe, non necessariamente il 50% della durata fisica su una griglia temporale irregolare.

GX-TXT supporta anche generator_basis=duration, con duration_unit quando necessario. Questa modalità richiede una griglia temporale canonica uniforme e una conversione esatta delle durate in numeri interi di campioni: il CORE non arrotonda silenziosamente intervalli incompatibili. Se il dato non è uniformemente campionato, non bisogna equiparare finestre di 10 campioni a finestre di 10 secondi.

La politica partial_policy=drop esclude l’eventuale ultima finestra incompleta. Con include viene inclusa esplicitamente una finestra finale troncata. La scelta va documentata perché influenza il numero e la copertura dei membri.

7. Aggiornare e cancellare un Temporal Set

Una risorsa persistente può essere aggiornata senza cambiare il proprio ID:

updated = gxtxt_api_call(API, 'update', [
    window_id, {'label': 'Overlap 50% (10 samples / 5 step)'}
])

Cambiare un’etichetta non cambia i campioni. È invece necessario rivalidare gli intervalli quando si modificano la dimensione, il passo, la sorgente o la definizione scientifica. Per un segment_set, se si vogliono conservare gli ID dei segmenti esistenti durante una modifica, bisogna includerli nella definizione aggiornata.

delete elimina soltanto la risorsa Temporal Set, non il Dataset di origine. Nell’esempio completo Python ne creiamo una temporanea, la cancelliamo e lasciamo intatte le due risorse didattiche principali. Per Dataset e Temporal Set condivisi da più analisi, una cancellazione non va effettuata senza verificare i consumer dipendenti.

8. Tornare in Octave: il risultato è riutilizzabile

Un ulteriore script GNU Octave recupera il window_set che Python ha creato. list e read permettono di riconoscerlo, resolve_info indica 11 membri e resolve_member restituisce la prima e la seconda finestra.

info = gxtxt_api_call('TEMPORAL_SET_API_v1', ...
  'resolve_info', {window_id});
first = gxtxt_api_call('TEMPORAL_SET_API_v1', ...
  'resolve_member', {window_id, 1});
second = gxtxt_api_call('TEMPORAL_SET_API_v1', ...
  'resolve_member', {window_id, 2});

assert(first.row_start == 0 && first.row_count == 10);
assert(second.row_start == 5 && second.row_count == 10);

I valori risolti possono essere passati direttamente a CANONICAL_DATASET_API_v2/read_range. Per mostrare la composizione con un servizio matematico, lo script usa poi NUMERIC_API_v1/integrate sui valori della prima finestra. Il risultato è 28,40200061 mmol·s/L, relativo ai campioni da 0 a 9 secondi.

Attenzione al confine di integrazione

La finestra definita sui campioni copre la prima decina di righe; il loro tempo va da 0 a 9 s. L’integrale numerico calcolato su quelle dieci coordinate copre quindi [0,9] s, non automaticamente l’intervallo continuo [0,10] s. Per includere un punto al confine sarebbe necessaria un’ulteriore scelta scientifica, non una correzione silenziosa degli indici.

Editor Octave integrato in GX-TXT con lettura di un Temporal Set creato da Python
Gli ID temporali sono riutilizzabili tra Octave e Python nella stessa Session.
Output Octave con undici finestre e integrale della prima finestra temporale
Octave integra i campioni 0–9 s della prima finestra definita da Python.

9. Eseguire i quattro script nel framework

Apriamo una nuova Session GX-TXT, poi utilizziamo i Viewer Octave Scripts e Python Scripts. Importiamo e registriamo ogni file con uno Script ID distinto, salvandolo prima di aprire il relativo Script Runner. L’ordine dell’esempio è:

  1. Temporal_00_Prepare.m — crea il Dataset con 60 campioni e semantica elapsed_time;
  2. Temporal_01_Octave_Segments.m — crea e risolve il segment_set;
  3. Temporal_02_Python_Windows.py — legge il Set Octave e crea/aggiorna il window_set;
  4. Temporal_03_Octave_Consume_Python.m — legge il Set Python e usa i campioni nel servizio numerico.

La Session è condivisa dai quattro Job, ma ognuno usa uno snapshot della revisione salvata del proprio script. Dopo le esecuzioni, le risorse Temporal Set rimangono disponibili per altri consumer nella stessa Session.

Gestore Script Jobs GX-TXT con quattro esecuzioni completate in GNU Octave e Python
Il flusso completo di creazione e riutilizzo dei Temporal Set è eseguito in GX-TXT.

10. Quando evitare i Temporal Set e quali errori prevenire

SituazioneScelta appropriata
Un solo calcolo sull’intera serieLeggere il Dataset direttamente: un Temporal Set non è indispensabile
Una singola lettura locale, non destinata al riusoPuò bastare read_range con offset e numero di righe già noti
Fasi sperimentali, intervalli separati o non contiguisegment_set
Molte finestre regolari, sovrapposizione e analisi ripetutawindow_set
Finestre con dimensione temporale costantewindow_set in base duration, ma solo se il contratto temporale e l’asse sono compatibili
Analisi condivise fra Octave, Python e moduli GX-TXTTemporal Set persistente con ID stabile
Necessità di nuovi risultati scientificiPubblicare i risultati come Dataset tramite DATASET_PUBLICATION_API_v2; il Temporal Set, da solo, non li crea

I problemi più frequenti riguardano l’asse temporale: ruolo semantico mancante, unità incompatibili con il tempo, Dataset/Variable ID inesistenti, coordinate non coerenti con gli intervalli o risorse che fanno riferimento a sorgenti non più disponibili. Il CORE invalida esplicitamente i riferimenti obsoleti anziché simulare un risultato corretto.

Un Temporal Set può avere un parent_selection_id: una Selection x_range sullo stesso Dataset e sulla stessa variabile temporale limita l’intervallo effettivo prima della generazione dei membri. Anche qui il Set continua a essere una vista, non una copia dei campioni.

Un criterio pratico

Usiamo i Temporal Set quando vogliamo conservare e condividere la definizione scientifica della selezione temporale. Non li usiamo soltanto perché una colonna contiene il tempo. Le API dei Dataset restano responsabili della lettura delle osservazioni; le API numeriche dell’elaborazione; la Temporal Set API della scelta persistente degli intervalli.

11. Sorgenti, versione e materiale dell’esempio

L’esempio è riferito a GX-TXT 0.9.8.10-dev-112 Release 2, patch cumulativa P008, disponibile nella release ufficiale GitHub. Il tag della release punta al commit 17ff2a7f93de0612015a873e626f87dbeb56b6a2; il bundle della patch identifica il commit sorgente f691b0f6e1016cb9af3db30ba3d1c8b5ea91429c. Le versioni delle API sono indipendenti dal numero della release del framework.

Documentazione delle API pubbliche:

Gli script completi sono riportati in fondo all’articolo, in riquadri espandibili. I commenti e le intestazioni dei sorgenti sono in inglese, con licenza GPL-3.0-or-later.

12. Script GNU Octave e Python completi

Espandere uno dei seguenti blocchi per consultare e copiare lo script completo. Gli esempi richiedono una Session nuova e vanno eseguiti nell’ordine presentato.

Nota: gli script usano soltanto le API pubbliche GX-TXT. Tutti i commenti all’interno del codice sono in lingua inglese.

Temporal_00_Prepare.m — codice completo
% GX-TXT Temporal Set API tutorial - create a canonical timed Dataset.
% Framework: GX-TXT DEV112-r2 P008; all GX-TXT access uses public APIs.
% SPDX-License-Identifier: GPL-3.0-or-later

source_id = 'temporal_demo_decay';
dataset_api = 'CANONICAL_DATASET_API_v2';
publication_api = 'DATASET_PUBLICATION_API_v2';
gxtxt_api_require({dataset_api, publication_api});
assert(gxtxt_api_has_operation(publication_api, 'publish_series_batch'));
assert(gxtxt_api_has_operation(dataset_api, 'read_range'));

existing_ids = gxtxt_api_call(dataset_api, 'list', {});
if any(strcmp(existing_ids, source_id))
  error('Dataset already exists: use a fresh Session.');
endif

% Sixty samples, one sample per second: t = 0, 1, ..., 59 s.
time_s = (0:59)';
concentration_mmol_L = 4.0 * exp(-0.055 * time_s);
assert(numel(time_s) == 60 && all(diff(time_s) == 1));

% Elapsed-time semantics are explicit, not inferred from the column name.
x_variable = struct('variable_id', 'time_s', 'name', 'time_s', ...
  'display_label', 'Elapsed time', 'unit', 's', 'dtype', 'float64', ...
  'value_kind', 'number', 'semantic_role', 'elapsed_time', ...
  'time_reference', 'elapsed', 'semantic_source', 'generator');
y_variable = struct('variable_id', 'concentration_mmol_L', ...
  'name', 'concentration_mmol_L', 'display_label', 'Concentration', ...
  'unit', 'mmol/L', 'dtype', 'float64', 'value_kind', 'number', ...
  'semantic_source', 'generator');

metadata = struct();
metadata.('simulation.synthetic') = true;
metadata.('simulation.kinetic_rate_per_s') = 0.055;
metadata.('simulation.uniform_time_step_s') = 1;
series = struct('dataset_id', source_id, 'contract', 'table.generic', ...
  'storage', 'auto', 'x_values', time_s, 'y_values', concentration_mmol_L, ...
  'x_variable', x_variable, 'y_variable', y_variable, ...
  'producer_version', '1.0.0', 'source', 'GX-TXT Temporal Set tutorial', ...
  'provenance', 'Deterministic first-order decay (synthetic data)', ...
  'structured_metadata', metadata);
batch = struct('series', {{series}});
receipt = gxtxt_api_call(publication_api, 'publish_series_batch', {batch});
assert(receipt.atomic && receipt.output_count == 1);
readback = gxtxt_api_call(dataset_api, 'read_range', ...
  {source_id, {'time_s', 'concentration_mmol_L'}, 0, 60});
assert(max(abs(readback.time_s.values(:) - time_s)) < 1e-12);
assert(max(abs(readback.concentration_mmol_L.values(:) - concentration_mmol_L)) < 1e-12);
fprintf('PASS: source Dataset %s; 60 elapsed-time samples, 0..59 s.\n', source_id);
Temporal_01_Octave_Segments.m — codice completo
% GX-TXT Temporal Set API tutorial - create and inspect a Segment Set.
% Run after Temporal_00_Prepare.m in the same GX-TXT Session.
% SPDX-License-Identifier: GPL-3.0-or-later

api = 'TEMPORAL_SET_API_v1';
dataset_api = 'CANONICAL_DATASET_API_v2';
gxtxt_api_require({api, dataset_api});
for op = {'create', 'list', 'read', 'resolve_info', 'resolve_member'}
  assert(gxtxt_api_has_operation(api, op{1}));
endfor

source_id = 'temporal_demo_decay';
existing = gxtxt_api_call(api, 'list', {source_id});
if !isempty(existing)
  error('Temporal Sets already exist for this Dataset; use a fresh Session.');
endif

% Three half-open intervals partition the 60 source samples.
segments = {
  struct('label', 'Early decay', 'start', 0, 'end', 10), ...
  struct('label', 'Middle decay', 'start', 10, 'end', 30), ...
  struct('label', 'Late decay', 'start', 30, 'end', 60)
};
definition = struct('type', 'segment_set', ...
  'source_dataset_id', source_id, 'temporal_variable_id', 'time_s', ...
  'label', 'Three kinetic phases', 'segments', {segments});
set_id = gxtxt_api_call(api, 'create', {definition});
assert(ischar(set_id) && !isempty(set_id));

saved = gxtxt_api_call(api, 'read', {set_id});
assert(strcmp(saved.type, 'segment_set'));
info = gxtxt_api_call(api, 'resolve_info', {set_id});
fprintf('Octave created %s (type %s).\n', set_id, saved.type);
for index = 1:3
  member = gxtxt_api_call(api, 'resolve_member', {set_id, index});
  assert(member.row_count > 0);
  block = gxtxt_api_call(dataset_api, 'read_range', ...
    {source_id, {'time_s', 'concentration_mmol_L'}, ...
     member.row_start, member.row_count});
  values = block.time_s.values(:);
  fprintf('Segment %d: %s, row_start=%d, row_count=%d, t=%g..%g s.\n', ...
    index, member.member_id, member.row_start, member.row_count, ...
    values(1), values(end));
endfor
fprintf('PASS: persistent Segment Set created through public Octave Script Bridge.\n');
Temporal_02_Python_Windows.py — codice completo
"""Create a Window Set with the GX-TXT public Python Script Bridge.

Run after Temporal_01_Octave_Segments.m in the same managed Session.
SPDX-License-Identifier: GPL-3.0-or-later
"""
from gxtxt import gxtxt_api_require, gxtxt_api_has_operation, gxtxt_api_call

API = "TEMPORAL_SET_API_v1"
DATASET_API = "CANONICAL_DATASET_API_v2"
SOURCE = "temporal_demo_decay"
gxtxt_api_require([API, DATASET_API])
for operation in ("list", "read", "create", "resolve_info", "resolve_member",
                  "resolve", "update", "delete"):
    assert gxtxt_api_has_operation(API, operation), operation

existing = gxtxt_api_call(API, "list", [SOURCE])
segment_sets = [item for item in existing if item["type"] == "segment_set"]
window_sets = [item for item in existing if item["type"] == "window_set"]
assert len(segment_sets) == 1 and len(window_sets) == 0

# Verify a resource created by GNU Octave is accessible from Python.
segment_id = segment_sets[0]["id"]
segment = gxtxt_api_call(API, "resolve_member", [segment_id, 2])
rows = gxtxt_api_call(DATASET_API, "read_range", [
    SOURCE, ["time_s", "concentration_mmol_L"],
    int(segment["row_start"]), int(segment["row_count"])
])
print("Python inspected Octave set", segment_id, "segment", segment["member_id"],
      "rows", int(segment["row_count"]))
assert len(rows["time_s"]["values"]) == 20

# Ten samples per window, shifted by five: 50% sample overlap.
definition = {
    "type": "window_set", "source_dataset_id": SOURCE,
    "temporal_variable_id": "time_s", "label": "Overlapping 10-sample windows",
    "generator_basis": "samples", "window_size": 10, "step": 5,
    "partial_policy": "drop",
}
window_id = gxtxt_api_call(API, "create", [definition])
assert isinstance(window_id, str) and window_id
saved = gxtxt_api_call(API, "read", [window_id])
assert saved["type"] == "window_set"
info = gxtxt_api_call(API, "resolve_info", [window_id])
print("Python created", window_id, "window count:", info["member_count"])
first = gxtxt_api_call(API, "resolve_member", [window_id, 1])
last = gxtxt_api_call(API, "resolve_member", [window_id, int(info["member_count"])])
print("First window:", first["member_id"], "rows", first["row_start"], first["row_count"])
print("Last window:", last["member_id"], "rows", last["row_start"], last["row_count"])
assert int(first["row_start"]) == 0 and int(first["row_count"]) == 10
assert int(info["member_count"]) == 11
assert int(last["row_start"]) == 50 and int(last["row_count"]) == 10

# Update the presentation label without changing the stable resource identity.
updated = gxtxt_api_call(API, "update", [window_id, {"label": "Overlap 50% (10 samples / 5 step)"}])
assert updated["id"] == window_id
all_members = gxtxt_api_call(API, "resolve", [window_id])
print("Resolved window-set fields:", sorted(all_members.keys()))

# Exercise delete safely on a temporary, disposable resource only.
scratch = dict(definition, label="Disposable demonstration set")
scratch_id = gxtxt_api_call(API, "create", [scratch])
assert scratch_id not in {window_id, segment_id}
assert gxtxt_api_call(API, "delete", [scratch_id]) == scratch_id
print("PASS: Python read the Octave set, created/updated windows and deleted a disposable set.")
Temporal_03_Octave_Consume_Python.m — codice completo
% GX-TXT Temporal Set API tutorial - consume Python-created windows in Octave.
% Run after Temporal_02_Python_Windows.py in the same Session.
% SPDX-License-Identifier: GPL-3.0-or-later

api = 'TEMPORAL_SET_API_v1';
dataset_api = 'CANONICAL_DATASET_API_v2';
numeric_api = 'NUMERIC_API_v1';
gxtxt_api_require({api, dataset_api, numeric_api});

sets = gxtxt_api_call(api, 'list', {'temporal_demo_decay'});
assert(numel(sets) == 2);
window_id = '';
for k = 1:numel(sets)
  if strcmp(sets{k}.type, 'window_set')
    window_id = sets{k}.id;
  endif
endfor
assert(!isempty(window_id));

info = gxtxt_api_call(api, 'resolve_info', {window_id});
assert(info.member_count == 11);
first = gxtxt_api_call(api, 'resolve_member', {window_id, 1});
second = gxtxt_api_call(api, 'resolve_member', {window_id, 2});
assert(first.row_start == 0 && first.row_count == 10);
assert(second.row_start == 5 && second.row_count == 10);

% row_start is zero-based, but resolve_member index is one-based.
block = gxtxt_api_call(dataset_api, 'read_range', ...
  {'temporal_demo_decay', {'time_s', 'concentration_mmol_L'}, ...
   first.row_start, first.row_count});
time_s = block.time_s.values(:);
y = block.concentration_mmol_L.values(:);
assert(numel(time_s) == 10 && time_s(1) == 0 && time_s(end) == 9);

% An integral over selected samples covers [0, 9] s, not the half-open [0, 10) definition.
area = gxtxt_api_call(numeric_api, 'integrate', {time_s, y, struct()});
fprintf('Octave read Python set %s: %d windows, step=5 samples.\n', ...
  window_id, info.member_count);
fprintf('First window samples t=%g..%g s; integrated area=%.8f mmol*s/L.\n', ...
  time_s(1), time_s(end), area.value);
fprintf('PASS: public cross-language Temporal Set resource and data range verified.\n');

#Dataset scientifici #elaborazione numerica #finestre temporali #GNU Octave #GX-TXT #Python #Script Bridge #segmentazione dei dati #serie temporali #Temporal Set API

Dalla stessa categoria

Lascia un commento

Il tuo indirizzo email non sarà pubblicato. I campi obbligatori sono contrassegnati *