XINA Struct Trend

The XINA Struct Export command line utility processes archive files for a specified time range to produce data products for XINA's Export Tasks. There are 2 suppported archive file formats: xbin and xpf. If the archive file is in the xpf format, processing is delegated to a mission specific tool. See the Struct Extract Interface that describes the interface the tool must implement. Available data products include:

Full resolution mnemonic data with a configurable format

Mnemonic data statistics

Configurable plots of data

Limit Report

Events

Log file

Arguments

Name	Req	Description	Default
cache		Cache directory path. Used for any persistent caching across tasks for optimization purposes.
cancellation		Path to the cancellation file for detecting cancel requests.
conf	✓	File path to the JSON config containing the export parameters.
env	✓	File path to the JSON environment file which defines environment parameters such as project specific paths.
extract		Overrides the path provided in the environment file to the struct_extract app. Only used if the archive format is `xpf`.
help		Print available options.
host		XINA Tunnel host.	`"localhost"`
port		XINA Tunnel port.	`41746`
import	✓	Import directory path. Files that need to be imported will be placed here. `struct_export` is responsbile for generating the corresponding import action file but `xina-run` will perform the actual importing.
log	✓	File path that log events will be written to.
out	✓	Ouptut directory path. Files placed here will be uploaded and accessible directly from the Task interface (e.g. notifications panel).
pkt_models		Models to use packet time by default. [TBD Remove]
plot	✓	Overrides the path provided in the environment file to the app that generates plot PDFs.
post	✓	Post directory path (for post-import outputs) e.g. uploading log files to the Task record.
python	✓	Overrides the path to the Python executable used by the plot app provided in the environment file.
task	✓	File path to the JSON file containing info about the Task.
temp	✓	Temp directory path for storing temporary files during execution. For example, zipped archives are unzipped to this directory for processing.

conf

The below table describes the available fields in the conf JSON file and is used to control how data should be exported.

Name	Type	Req	Description	Default
model	`utf8text`	✓	Path of model to export data from e.g. `moma.fm`
label	`utf8text`		The text that will be used to name the files and final zip file. The format will be like `2024_06_12_00_00_00_2024_06_12_00_20_00_profile_label`
profile	`utf8text`		The name of the Profile if the export was generated from one
start	`instant(us)`	✓	Start time of data to export. May be provided as a Unix timestamp in microseconds (e.g. `1738781947000000`) or an ISO 8601 formatted string (e.g. `2024-06-12T00:00:00Z`).
end	`instant(us)`	✓	End time of data to export. May be provided as a Unix timestamp in microseconds (e.g. `1738781947000000`) or an ISO 8601 formatted string (e.g. `2024-06-12T00:00:00Z`).
ueid	`UUID`		Event UUID of interval if the export was requested for an interval. The event's start and end time will be used instead of `start` and `end`.
auto_conf	`struct_auto_conf`		The `struct_auto_conf` that triggered the export. Only provided if the export was auto generated.
plot_conf	`struct_plot_conf`		The plot configuration used to generate the plot PDF. See plot format. An empty object i.e. `{}` can be provided to generate the default plot configuration. If not provided, then plots will not be generated.	One mnemonic per plot, one plot per page, sorted by `mn_id` in ascending order.
data_conf	`struct_data_conf`	✓	See struct_data_conf
disable_filter	`boolean`		If `true`, does not apply the filters defined in `data_conf`.	false
copy	`boolean`		If true, the zip file will be uploaded and available from the Task interface.	false
multi	`boolean`		[TBD REMOVE - Not currently supported] Has extract process all archives at once. This was added for performance reasons since loading the mnem def is slow.

Example conf:

Note: The plot_conf was truncated for brevity.

{
  "model": "oci.fm",
  "profile": "OPS_FLT_OCI_SDS",
  "label": "test",
  "start": 1718150400000000,
  "end": "2024-06-12T00:20:00Z",
  "ueid": null,
  "copy": true,
  "auto_confs": [
    {
      "users": [
        "johndoe",
        "alice"
      ],
      "mine": false,
      "daily": true
    }
  ],
  "plot_conf": {
    "trend_series": [
      "avg"
    ],
    "pages": [
      {
        "plots": [
          {
            "title": "OCI Pri Power (15A)",
            "mnemonics": [
              "PSE.OM1.OCI_PRI_CURR"
            ]
          },
          {
            "series": [
              {
                "mnemonic": "oci.dau.ddc.FPGA.CcdOpMode",
                "plot_options": {
                  "color": "k"
                }
              }
            ]
          }
        ]
      }
    ]
  },
  "data_conf": {
    "limit": false,
    "ids": "@#[42316,42318-42322,43255,44243,45140,45187-45210,45233-45236,45238,45240,45241,45245,45247,45248,45259,45260,45265-45268,45270,45272,45273,45277,45279,45280,45291,45292,45442,45444,45446,45448,45450,45452,45454,45460,45462,45472,45538,45540,45542,45544,45546,45548,45550,45556,45558,45568,51908,51910,64097,64109,64111,64113,64115,66333,66341,66349,66357,66365,66373,66381,67536,67537,69019,69024-69026,69031,69032,69729,77534,77570,77696]sci",
    "dis": false,
    "fill": false,
    "columns": {
      "ts_utc_iso": true
    },
    "join": true,
    "pkt": true
  }
}