Input/output multi-file format

Within the Nextmv Cloud, the API expects JSON input and output by default. If you want to work with a format for input/output that is not JSON, you can define the content type used by the run. This can either be set within the configuration field of an instance or within the configuration field of a request to create a run.

As an example, we'll walk through how to use CSV files as the input and output of a run by bundling the input into a tarball, pre-loading it, and setting the content type of the run in its configuration.

Input

For working with file-based input in Nextmv cloud, there are a few additional steps that must be followed in order to enable runs.

Firstly, the input folder must be compressed into a tar archive compressed with gzip (.tar.gz). This archive must contain only either UTF8 encoded files or Microsoft Excel (.xlsx) documents.

Secondly, the input must be uploaded to nextmv cloud prior to the run as an uploaded input for the run (or as a managed input in the case of batch experiments and scenario tests). For the purpose of this example, the uploaded input approach will be detailed.

We will assume to be in the example local directory /workdir/

Sample CSV archive input

We will create a directory inputs/ and file inputs/example.csv within /workdir/ containing the following data:

order_id,customer_id,order_due,order_value
1,1,2021-01-01,100
2,2,2021-01-02,200
3,3,2021-01-03,300
4,4,2021-01-04,400

Then, we will compress the inputs directory into an archive using tar

tar -czvf inputs.tar.gz inputs

Upload CSV archive input pre-loading endpoint

The input archive must now be pre-loaded to the Nextmv cloud to prepare it for use on a run. To do this, we request an upload URL for a run from the Nextmv cloud. This is the same process as outlined in steps 1 and 2 of using the cloud API to use large inputs.

Ensuring the run's content type is configured

When creating a run that uses multi-file archive input, the run's configuration must be defined such that the content type is set to multi-file.

This can either be configured on the instance the run is configured with or on the configuration field of the run creation request itself, which shares the same structure. Note that if configuration is defined on both instance and run creation request, any conflicts between these configurations will use the values specified on the run creation request.

Output

Content format for the multi-file content type is expected by the Nextmv cloud to be file based, and to contain, at minimum, the following file structure (relative to the working directory of the binary):

.
├── inputs/
└── outputs/
    ├── assets/
    ├── solutions/
    └── statistics/

These directories will be pre-created by the Nextmv cloud when running the application and using the multi-file content type.

inputs is a directory that contains user input. The contents of the input tar.gz file should be expected to be extracted here by the point Nextmv cloud runs the application binary.

outputs/solutions is a directory expected to contain the output of the run after the application completes processing. This output is expected to be one or more files that are either UTF8 encoded or Microsoft Excel (.xlsx) documents. This folder is then compressed into a gzip compressed tarball (.tar.gz) and stored on Nextmv cloud as the output of the run.

outputs/statistics is a directory expected to either be empty or contain statistics information for the run used for experimentation on the Nextmv cloud platform. If empty, no statistics information is recorded on the run on the Nextmv cloud. To output statistics to the Nextmv cloud from the run, the application should create a statistics.json file within outputs/statistics that contains a JSON object following the Nexmtv statistics convention.

outputs/assets is a directory expected to either be empty or contain additional assets for the run that can contain suplimental or transformative files that are generally not informationally addititve to the output, such as, but not limited to, assets for enabling custom vizualization of run results on Nextmv console. If empty, no assets are recorded on the run on the Nextmv cloud. To output assets to the Nextmv cloud from the run, the application should create a assets.json file within outputs/assets that contains a JSON object following the Nextmv run assets convention.