syntax="proto3";

package minknow_api.data;

option java_package = "com.nanoporetech.minknow_api";
option objc_class_prefix = "MKAPI";

import "minknow_api/rpc_options.proto";
import "minknow_api/device.proto";
import "minknow_api/statistics.proto";
import "google/protobuf/duration.proto";
import "google/protobuf/wrappers.proto";

service DataService {

    // Get the channel states for all channels from the device.
    //
    // This will return all the channel states from the moment of calling until the rpc is
    // closed by the user. If the user stops acquisition, the rpc will return with the
    // ABORTED status. If the user cancels the rpc, the status will be CANCELLED.
    //
    // The first messages returned will retrieve the current channel state for all channels
    // On the MinION, the current state for all channels will be included in the first message.
    // For PromethION, it will be split on multiple messages.
    //
    // To determine which channels have been returned, please check the channel member in the
    // messages returned in the response.
    //
    // The response will be streamed, and we will provide a message as soon as there are channel
    // state changes (though note that some channels could stay in the same state for a long time),
    // so there is no guaranteed frequency of the messages returned. However, because a response
    // message includes multiple channels, it is very likely that we have messages every few seconds.
    // As in, it is likely that at least some of the channels will change every so often, therefore
    // messages will be generated. For example, if 5 out of 512 channels change the state in the
    // same time, there will be a message containing all 5 changes. Later on, if other channels
    // change their state we will receive another message containing those and so on. Note that
    // MinKNOW tries to group as many channel state changes in a single message, up to the message
    // limit size, which is currently set to 32kB.
    rpc get_channel_states (GetChannelStatesRequest) returns (stream GetChannelStatesResponse) {
        option idempotency_level = NO_SIDE_EFFECTS;
    }

    // Get the data types of data items produced by this service.
    //
    // In order to allow clients to efficiently deal with large volumes of data in languages such as
    // Python, this service can provide data as raw bytes. This call can be used to determine how to
    // interpret those bytes. This can be used to construct an appropriate numpy dtype, for example.
    rpc get_data_types (GetDataTypesRequest) returns (GetDataTypesResponse) {
        option idempotency_level = NO_SIDE_EFFECTS;
    }

    // Get signal data from the device.
    //
    // This can be used to sample the signal being produced by the device. The signal can be
    // returned as raw ADC values or as calibrated picoamp (pA) values; see ``set_calibration`` on
    // the device service for the values used in this conversion.
    //
    // In addition to the signal, this can return the associated channel configuration and/or bias
    // voltage information, to help analyse the data.
    //
    // If bias voltage information is requested, one bias voltage sample will be provided for each
    // signal sample (on any given channel). So if you request 20 samples of signal data and also
    // bias voltages, you will get 20 signal samples on each channel and also 20 bias voltage
    // samples. Bias voltages are always given in millivolts, and no corrections need to be applied
    // (for example, the 5x amplifier on a MinION is already accounted for).
    //
    // If channel configuration information is requested, each channel will have the starting
    // channel configuration (with offset 0 to indicate it applies to the first sample on that
    // channel), as well as any configuration changes that affect any of the returned samples.
    //
    // If a device settings change RPC has completed before this method is called, the data returned
    // is guaranteed to have been generated by the device after those settings were applied.
    // However, note that no guarantee is made about how device settings changes that overlap with
    // this request will affect the returned data.
    //
    // The response will be streamed. In order to limit the size of each response message, any given
    // message may include data from only a subset of the requested channels.
    //
    // Note that the data is returned as bytes fields. See the GetSignalBytesResponse documentation
    // for more details about how to interpret the value. In Python code, the minknow.Device class
    // provides a convenience wrapper method to convert the data into numpy arrays.
    rpc get_signal_bytes (GetSignalBytesRequest) returns (stream GetSignalBytesResponse) {
        option idempotency_level = NO_SIDE_EFFECTS;
    }

    // Get summarised signal data from the device.
    //
    // This provides signal data from the device, like get_signal_bytes, but instead of all the
    // data, it divides the data up into windows, and provides the minimum and maximum values for
    // each window.
    //
    // This call is aimed at visualisations of data (ie: a traceviewer interface). As such, it does
    // not provide most of the guarantees and options that get_signal_bytes() does. No bias voltage
    // or channel configuration data is provided, it is not possible to set the number of samples
    // desired up front (just cancel the call when no further data is required) and no guarantees
    // are made about whether particular commands have been applied to the returned data.
    //
    // Also unlike get_signal_bytes(), the returned data is in native types, and does not require
    // any further interpretation based on get_data_types(). This can be done performantly because
    // of the reduced amount of data transmitted.
    //
    // The response will be streamed. In order to limit the size of each response message, any given
    // message may include data from only a subset of the requested channels.
    rpc get_signal_min_max (GetSignalMinMaxRequest) returns (stream GetSignalMinMaxResponse) {
        option idempotency_level = NO_SIDE_EFFECTS;
    }

    // Call this to force re-evaluating the channel states. This will make sure the next
    // channel state evaluated will be 'unclassified_following_reset'. If the analyser is behind,
    // and older data will come for evaluation, it will result in changing the state to 'pending_manual_reset'.
    // So tipically, after a resetting the channel states, the user would see in the bulk file
    // 'unclassified_following_reset', 'pending_manual_reset', 'pending_manual_reset', until the relevant data
    // comes through to the analyser and it will start outputting the normal channel states again.
    // If the analyser is not behind, the user should ideally see just the 'unclassified_following_reset' state.
    //
    // This call is blocking - it will return from the rpc when it would have processed the
    // 'unclassified_following_reset' in the analyser. If the rpc takes more than 1 minute
    // it will exit with the ABORTED status. This can happen if the analyser is more than 1 minute behind
    // for example (in practice it shouldn't be the case). If the RPC exits with the ABORT status, it means
    // the channels are to be reset in the future, but the analyser did not reach that point yet.
    //
    // Only one of these can be executed at a given time. If multiple threads call this simultaneously,
    // it will execute the first request and it will exit with FAILED_PRECONDITION for the rest. If an RPC
    // exited with the ABORT status, another RPC can immediately be started. The failed RPC would have not
    // reset the channel states, and the user could try again. The second RPC will return as soon as the first
    // reset happens, so this will not be necessarily waiting for the second acquisition index to be
    // processed.
    rpc reset_channel_states (ResetChannelStatesRequest) returns (ResetChannelStatesResponse) {}

    // Forces channels to be fixed on a custom channel state. The channels will not be re-evaluated until
    // they are activated using unlock_channel_states.
    // To create a channel state that will never be entered unless manually set using this call,
    // use the "never_evaluated" criteria:
    // "9": { "group": {...},
    //        "logic": {
    //            "rank": 0,
    //            "criteria": "never_evaluated"
    //             },
    //         "name": "custom_name_picked_by_the_user"
    //       }
    //
    // While the this RPC has the power of forcing a channel to any valid state other than 'unclassified',
    // it is intended to be used with channel states that are designed for this functionality (i.e. that
    // are never evaluated).
    // Has to be called while acquiring data, fails otherwise.
    // The forced channels are reset (reset = every channel back to being evaluated) every time a
    // new acquisition sequence is started.
    //
    // NOTE:
    // Calls to lock_channel_states and unlock_channel_states cannot be done in the same time.
    // If any of these two is called while any of these is already running, the grpc will return
    // with an error.
    rpc lock_channel_states(LockChannelStatesRequest) returns (LockChannelStatesResponse) {}

    // Re-activates channels that have been turned-off with force_channels_to_state.
    // Note that 'turning off' refers to channel states only, everything else is still applied on the channel
    // (e.g. mux changes, saturation, commands etc)
    // No action is taken if the channel is already active.
    // Has to be called while acquiring data, fails otherwise.
    // NOTE:
    // Calls to lock_channel_states and unlock_channel_states cannot be done in the same time.
    // If any of these two is called while any of these is already running, the grpc will return
    // with an error.
    rpc unlock_channel_states(UnlockChannelStatesRequest) returns (UnlockChannelStatesResponse) {}

    // Get live reads sent in order to control sequencing behaviour.
    //
    // This method sends current reads (reads that are currently in the sequencer) to the user along
    // with live analysis data in order for real time decisions to be made.
    //
    // The method provides two streams:
    //
    // GetLiveReadsRequest stream:
    //      Sent by the user, provides MinKNOW with actions to take on current reads, actions
    //      taken are sumarised and sent back to the user in the GetLiveReadsResponse stream.
    // GetLiveReadsResponse stream:
    //      Sent to the user, contains a stream of ongoing sequencing information, sent as
    //      regularly as possible, with information on reads in progress, and feedback on actions
    //      taken on the data.
    //
    // note: This method operates on read chunks in MinKNOW, and will send at minimum, 1 read
    // chunk to the user. In order to reduce latency on the method, tune the following options:
    //
    // The raw chunk size data is processed in minknow (specified in samples):
    //      app_conf/hyperstream.raw_data_intermediate.size
    //      app_conf/hyperstream.raw_meta_data_intermediate.size
    //
    // The maximum read chunk size - changing the size read chunks are processed in minknow:
    //      analysis_conf/read_detection.break_reads_after_seconds
    //
    rpc get_live_reads(stream GetLiveReadsRequest) returns (stream GetLiveReadsResponse) {
        option idempotency_level = NO_SIDE_EFFECTS;
    }

    // Collects statistics about read (chunk) lengths and signal, split by channel, channel
    // configuration and read (chunk) classification.
    rpc get_read_statistics (GetReadStatisticsRequest) returns (GetReadStatisticsResponse) {
        option idempotency_level = NO_SIDE_EFFECTS;
    }

    // Returns various points of yield information for the ongoing experiment, such as complete
    // read information and basecaller progress.
    rpc get_experiment_yield_info (GetExperimentYieldInfoRequest) returns (GetExperimentYieldInfoResponse) {
        option idempotency_level = NO_SIDE_EFFECTS;
    }
}

message GetChannelStatesRequest {
    // The first channel (inclusive) to return data for.
    //
    // Note that channel numbering starts at 1.
    uint32 first_channel = 1 [(rpc_required) = true];

    // The last channel (inclusive) to return data for.
    //
    // Note that channel numbering starts at 1.
    uint32 last_channel = 2 [(rpc_required) = true];

    // If this is true, the returned messages will contain the
    // channel state id as opposed to the name. By default,
    // the response will contain channel states names.
    google.protobuf.BoolValue use_channel_states_ids = 3;

    // If `wait_for_processing` is true, then get_channel_states will wait until minknow starts
    // acquiring data instead of returning with an error
    //
    // Defaults to false
    bool wait_for_processing = 4;

    // Ensure the stream sends a message at least this often.
    //
    // There will usually be multiple channel updates a second, but in some circumstances (eg: a
    // flow cell with no sample loaded) there can be long periods of time without updates.
    //
    // Setting this value will ensure that if this period of time passes without there being any
    // channel state changes to report, an empty message will be sent. This can be useful to force a
    // minimum wakeup interval in the client code.
    google.protobuf.Duration heartbeat = 5;
}

message GetChannelStatesResponse {
    message ChannelStateData {
        // Represents the channel number, indexed from one. (i.e. what channel did the
        // channel state change happened on)
        uint32 channel = 1;

        // depending on the channel state request, MinKNOW can fill in either the name
        // or the criteria id of the channel state. The criteria id (or state_id) is
        // the number passed in the channel states configuration. Note that MinKNOW also
        // has some default channel states (like unclassified, pending mux change) which
        // receive unique ids - these are numbers bigger than 200.
        oneof state {
            uint32 state_id = 2;
            string state_name = 3;
        };

        // Indices of when the channel state was first seen.
        // For example, if a request is done half way through the experiment,
        // the first message will contain the current state on the requested
        // channels. The acquisition/analysis index of these would be from
        // when the channel states were set. These are exactly the same numbers
        // we see in the bulk file, in the 'states' table
        uint64 acquisition_raw_index = 4;
        uint64 analysis_raw_index = 5;
        uint64 trigger_time = 7;

        // Channel config (mux state) the channel state was determined on.
        device.ReturnedChannelConfiguration config = 6;
    }

    // The streamed data for all channels will be appended to this vector.
    // After the request is made, all the channel state changes are streamed through
    // this array. This is implemented in the idea of a sparse array because we can have
    // channels that remain in the same state for a long time.
    repeated ChannelStateData channel_states = 1;
}

message GetDataTypesRequest {}

message GetDataTypesResponse {
    message DataType {
        enum Type {
            SIGNED_INTEGER = 0;
            UNSIGNED_INTEGER = 1;
            FLOATING_POINT = 2;
        }

        // The basic type of the data item.
        Type type = 1;

        // Whether the type is big-endian (high-byte first).
        //
        // For numeric data types, if this is not set, they are little-endian (low-byte first).
        bool big_endian = 2;

        // The size of the data type in bytes.
        uint32 size = 3;
    }

    // The format of the uncalibrated (ADC) signal data returned by get_raw_signal_bytes().
    //
    // In the current release, this will describe 16-bit little-endian integers.
    DataType uncalibrated_signal = 1;

    // The format of the calibrated (picoamp) signal data returned by get_raw_signal_bytes().
    //
    // In the current release, this will describe 32-bit IEEE 754 floating point values.
    DataType calibrated_signal = 2;

    // The format of the bias voltage data returned by get_raw_signal_bytes().
    //
    // In the current release, this will describe 16-bit little-endian integers.
    DataType bias_voltages = 3;
}

message GetSignalBytesRequest {
    // The amount of data to return.
    //
    // If this is omitted, data will be streamed until the call is cancelled.
    oneof length {
        // The amount of data to return in seconds.
        //
        // The number of samples returned will be just enough to cover this period of time. Cannot
        // be specified at the same time as ``samples``.
        float seconds = 1;
        // The amount of data to return in samples.
        //
        // The result will contain exactly this many samples. If this is not possible, the call will
        // fail. Cannot be specified at the same time as ``seconds``.
        uint32 samples = 2;
    };

    // The first channel (inclusive) to return data for.
    //
    // Note that channel numbering starts at 1.
    uint32 first_channel = 3 [(rpc_required) = true];

    // The last channel (inclusive) to return data for.
    //
    // Note that channel numbering starts at 1.
    uint32 last_channel = 4 [(rpc_required) = true];

    // Whether to include channel configuration settings.
    bool include_channel_configs = 5;

    // Whether to include bias voltage information.
    bool include_bias_voltages = 6;

    // Whether the data should be calibrated.
    bool calibrated_data = 7;

    // When this value is set to true, then an empty message will be sent back
    // to the client to indicate that the backend has acknowleged the request,
    // and that any calls made that will affect the signal after that initial 
    // response will be reflected in the next messages
    bool return_when_listening = 8;
}

message GetSignalBytesResponse {
    message ChannelConfigChange {
        // The new channel configuration.
        device.ReturnedChannelConfiguration config = 1;

        // The offset in the returned data where the change was applied.
        uint64 offset = 2;
    }

    message ChannelData {
        // The signal data.
        //
        // This is the byte representation of a C-style array of values. Values are stored in order
        // and adjacent to each other.
        //
        // The type of the elements will depend on whether calibrated data was chosen. The
        // get_data_types() RPC call should be used to determine the precise format of the data, but
        // in general terms, uncalibrated data will be signed integers and calibrated data will be
        // floating-point numbers.
        //
        // Returning the data in this format allows it to be efficiently processed in dynamic
        // languages that can pass the data straight down to a native runtime. For example, in
        // Python, this data can be intepreted directly into a numpy array using numpy.fromstring().
        //
        // Calibrated data is in picoamps. Uncalibrated data is the raw values output by the
        // device's ADC (analogue-digital converter).
        bytes data = 1;

        // The configuration changes on the channel during data collection.
        //
        // If channel configuration changes were requested, this will contain all the channel
        // configuration changes that affect the returned data. This will include at least one
        // element, with offset 0, that describes the configuration at the time the first sample was
        // taken.
        //
        // Note that the offset is the zero-based index into the adc or picoamps list.
        //
        // The changes will be ordered by offset.
        repeated ChannelConfigChange config_changes = 3;
    };

    // The number of samples collected before the first sample included in this response.
    //
    // This gives the position of the first data point on each channel in the overall stream of data
    // being acquired from the device (since this period of data acquisition was started).
    uint64 samples_since_start = 1;

    // The number of seconds elapsed since data acquisition started.
    //
    // This is the same as ``samples_since_start``, but expressed in seconds.
    double seconds_since_start = 2;

    // The number of channels omitted at the start of the ``channels`` array.
    uint32 skipped_channels = 3;

    // The signal for each requested channel.
    //
    // Note that ``skipped_channels`` must be used to determine which channels are given here, as
    // not all channels will be included in every message. The channels that are provided are
    // contiguous and in order, with the first channel being ``first_channel + skipped_channels``
    // (where ``first_channel`` is from the request message).
    repeated ChannelData channels = 4;

    // The bias voltages set for each sample.
    //
    // If bias voltages were requested, this will provide voltage data, one voltage per sample. Note
    // that not every message may include bias_voltages (they will generally be included when
    // ``skipped_channels`` is 0, but that is not guaranteed).
    //
    // The get_data_types() RPC call should be used to determine the format of the data.
    bytes bias_voltages = 5;
}

message GetSignalMinMaxRequest {
    // The first channel (inclusive) to return data for.
    //
    // Note that channel numbering starts at 1.
    uint32 first_channel = 3 [(rpc_required) = true];

    // The last channel (inclusive) to return data for.
    //
    // Note that channel numbering starts at 1.
    uint32 last_channel = 4 [(rpc_required) = true];

    // The size of window to summarise.
    //
    // A value of zero will be rejected; there is no default.
    uint32 window_size = 5 [(rpc_required) = true];

    // Whether the data should be calibrated.
    bool calibrated_data = 7;
}

message GetSignalMinMaxResponse {
    message ChannelData {
        // The minimum value for each window.
        //
        // The type of the elements will depend on whether calibrated data was chosen.
        // Uncalibrated data will be signed integers and calibrated data will be
        // floating-point numbers.
        //
        // It would be nice to use the "oneof" enum-like type to
        // capture this, but you can't have repeated members in a oneof, and nor can
        // you have a repeated oneof field.  We can simply include message fields for both
        // types of data, as all fields are optional in proto3.  We will rely on the
        // code that constructs this message to guarantee that we don't try and put both
        // types of data into the same message.
        //
        // Calibrated data is in picoamps. Uncalibrated data is the raw values output by the
        // device's ADC (analogue-digital converter).
        //
        // This is guaranteed to be the same size as the respective foo_maxima field.
        repeated float calibrated_minima = 1;
        repeated int32 raw_minima = 2;

        // The maximum value for each window.
        //
        // See comments for the "minima" fields above for details of calibrated and
        // uncalibrated data.
        //
        // This is guaranteed to be the same size as the respective foo_minima field.
        repeated float calibrated_maxima = 3;
        repeated int32 raw_maxima = 4;
    };

    // The number of samples collected before the first sample included in this response.
    //
    // This gives the position of the first data point on each channel in the overall stream of data
    // being acquired from the device (since this period of data acquisition was started).
    uint64 samples_since_start = 1;

    // The number of seconds elapsed since data acquisition started.
    //
    // This is the same as ``samples_since_start``, but expressed in seconds.
    double seconds_since_start = 2;

    // The number of channels omitted at the start of the ``channels`` array.
    uint32 skipped_channels = 3;

    // The window bounds for each requested channel.
    //
    // Note that ``skipped_channels`` must be used to determine which channels are given here, as
    // not all channels will be included in every message. The channels that are provided are
    // contiguous and in order, with the first channel being ``first_channel + skipped_channels``
    // (where ``first_channel`` is from the request message).
    repeated ChannelData channels = 4;
}

message GetLiveReadsRequest {
    enum RawDataType {
        // Don't change the previously specified setting for raw data sent with live reads
        // note: If sent when there is no last setting, NONE is assumed.
        KEEP_LAST = 0;
        // No raw data required for live reads
        NONE = 1;
        // Calibrated raw data should be sent to the user with each read
        CALIBRATED = 2;
        // Uncalibrated data should be sent to the user with each read
        UNCALIBRATED = 3;
    }

    message UnblockAction {
        // Duration of unblock in seconds.
        double duration = 1;
    }

    message StopFurtherData {}

    message Action {
        string action_id = 1;
        // Channel name to unblock
        uint32 channel = 2;

        // Identifier for the read to act on.
        //
        // If the read requested is no longer in progress, the action fails.
        oneof read {
            string id = 3;
            uint32 number = 4;
        }

        oneof action {
            // Unblock a read and skip further data from this read.
            UnblockAction unblock = 5;

            // Skip further data from this read, doesn't affect the read data.
            StopFurtherData stop_further_data = 6;
        }
    }

    message StreamSetup {
        // The first channel (inclusive) to return data for.
        //
        // Note that channel numbering starts at 1.
        uint32 first_channel = 1;

        // The last channel (inclusive) to return data for.
        //
        // Note that channel numbering starts at 1.
        uint32 last_channel = 2;

        // Specify the type of raw data to retrieve
        RawDataType raw_data_type = 3;

        // Minimum chunk size read data is returned in.
        uint64 sample_minimum_chunk_size = 4;

        // Maximum read length MinKNOW will attempt to unblock
        // reads beyond this length will not be unblocked when Action's request,
        // instead minknow will skip any further data from the read.
        oneof max_unblock_read_length {
            // Maximum read length MinKNOW will attempt to unblock (in samples).
            //
            // A value of 0 will cause minknow to unblock reads of any length.
            // 
            uint64 max_unblock_read_length_samples = 5;

            // Maximum read length MinKNOW will attempt to unblock (in seconds).
            //
            // A value of 0.0 will cause minknow to unblock reads of any length.
            // 
            double max_unblock_read_length_seconds = 6;
        }

        // A set of classification identifiers which the client is interested in.
        // If a read starts with a classification not listed here the read is never sent to the client.
        repeated int32 accepted_first_chunk_classifications = 7;
    }

    message Actions {
        repeated Action actions = 2;
    }

    oneof request {
        // Read setup request, initialises channel numbers and type of data returned.
        //
        // note: Must be specified in the first message sent to MinKNOW. Once MinKNOW
        // has the first setup message reads are sent to the caller as requested.
        // The user can then resend a setup message as frequently as they need to in order
        // to reconfigure live reads - for example by changing if raw data is sent with
        // reads or not.
        StreamSetup setup = 1;

        // Actions to take given data returned to the user - can only be sent once the setup
        // message above has been sent.
        Actions actions = 2;
    }
}

message GetLiveReadsResponse {
    message ReadData {
        // The id of this read, this id is unique for every read ever produced.
        string id = 1;

        // The minknow assigned number of this read
        //
        // Read numbers always increment throughout the experiment, and are unique per channel -
        // however they are not necessarily contiguous.
        uint32 number = 2;

        // Absolute start point of this read
        uint64 start_sample = 3;

        // Absolute start point through the experiment of this chunk
        uint64 chunk_start_sample = 4;

        // Length of the chunk in samples
        uint64 chunk_length = 5;

        // All Classifications given to intermediate chunks by analysis
        //
        // See analysis_configuration.get_read_classifications for how to map these integers to names.
        repeated int32 chunk_classifications = 6;

        // Any raw data selected by the request
        //
        // The type of the elements will depend on whether calibrated data was chosen. The
        // get_data_types() RPC call should be used to determine the precise format of the data, but
        // in general terms, uncalibrated data will be signed integers and calibrated data will be
        // floating-point numbers.
        bytes raw_data = 7;

        // The median of the read previous to this read.
        // intended to allow querying of the approximate level of this read, comapred to the last.
        //
        // For example, a user could try to verify this is a strand be ensuring the median of the
        // current read is lower than the median_before level.
        float median_before = 8;

        // The media pA level of this read from all aggregated read chunks so far.
        float median = 9;

        // The classification of the chunk prior to this read starting.
        int32 previous_read_classification = 10;

        // The classification of the chunk prior to this read starting.
        statistics.ReadEndReason previous_read_end_reason = 11;
    };

    message ActionResponse {
        string action_id = 1;

        enum Response {
            SUCCESS = 0;
            FAILED_READ_FINISHED = 1;
            FAILED_READ_TOO_LONG = 2;
        }

        Response response = 2;
    }

    // The number of samples collected before the first sample included in this response.
    //
    // This gives the position of the first data point on each channel in the overall stream of data
    // being acquired from the device (since this period of data acquisition was started).
    uint64 samples_since_start = 1;

    // The number of seconds elapsed since data acquisition started.
    //
    // This is the same as ``samples_since_start``, but expressed in seconds.
    double seconds_since_start = 2;

    // In progress reads for the requested channels.
    //
    // Sparsely populated as not all channels have new/incomplete reads.
    map<uint32, ReadData> channels = 4;

    // List of responses to requested actions, informing the caller of results to requested
    // unblocks or discards of data.
    repeated ActionResponse action_responses = 5;
}

message ResetChannelStatesRequest
{}

message ResetChannelStatesResponse
{}

message GetReadStatisticsRequest {
  // List of channels required, indexed from 1.
  repeated uint32 channels = 1;

  // How long to collect the statistics for
  oneof duration {
    float seconds = 2;
    uint64 samples = 3;
  }

  // Whether to aggregate statistics on a read chunk or complete read basis.
  //
  // This will affect both durations (which will be the durations of read chunks or complete reads)
  // and classification aggregation (which will be based on the read chunk classification or the
  // complete read classification).
  enum ReadSplit {
    CHUNK = 0;
    COMPLETED_READ = 1;
  }
  ReadSplit read_split = 4 [(rpc_required) = true];

  // Disable current_statistics results in returned data.
  //
  // Intended for use when the consumer doesn't need specific fields
  // allowing the implementation to be more efficient.
  bool no_current_statistics = 5;

  // Disable chunk_statistics results in returned data.
  //
  // Intended for use when the consumer doesn't need specific fields
  // allowing the implementation to be more efficient.
  bool no_chunk_statistics = 6;

  // Specify classifications which the user wants information about.
  //
  // The default behaviour (when empty) is to return information on all classifications.
  //
  // Specifying which classifications the user needs information about may allow
  // the implementation to be more efficient.
  repeated string required_classifications = 7;
}

message GetReadStatisticsResponse {
  message Statistics {
    double min = 1;
    double max = 2;
    double mean = 3;
    double s_d = 4;
    double median = 6;
    double q_5 = 7; // Quantiles (percentiles)
    double q_10 = 8;
    double q_25 = 9;
    double q_75 = 10;
    double q_90 = 11;
    double q_95 = 12;
  }

  message ChunkStatistics {
      // Aggregated median_sd value from all classified reads.
      // Computed as median(median_sd[...])
      double median_sd = 1;

      // Aggregated median_sd value from all classified reads.
      //
      // Computed as median(median[...])
      double median = 2;
      
      // Aggregated range value from all classified reads.
      //
      // Computed as median(q90[...] - q10[...])
      double range = 3;
  }

  message PerClassificationData {
    // Statistics of read (chunk) durations. These will be in the same units as the requested
    // duration (if you ask for X seconds of data, you will get durations back in seconds, but if
    // you ask for X samples of data, you will get durations back in samples).
    //
    // NB: statistics may be estimates.
    Statistics duration_statistics = 1;

    // Statistics for all current (signal) values for all reads under this
    // channel/configuration/classification combination.
    //
    // NB: Statistics are calculated from raw data.
    Statistics current_statistics = 2;

    // Statistics generated from the analysed read chunks (or complete reads), rather
    // than the raw signal.
    ChunkStatistics chunk_statistics = 6;

    // The number of samples seen with this classification on this channel in this channel
    // configuration.
    uint64 samples_duration = 4;

    // The number of seconds spent in this classification on this channel in this channel
    // configuration.
    //
    // This is the same as ``samples_duration``, but expressed in seconds.
    double seconds_duration = 5;
  }

  message PerConfigurationData {
    // The channel configuration active during the reads these statistics were gathered for.
    device.ReturnedChannelConfiguration channel_configuration = 1;

    // Map from classification names to statistics about read (chunks) with that classification.
    map<string, PerClassificationData> classifications = 2;

    // If statistics about complete reads were requested, this field may contain data for a final,
    // incomplete read (whose classification is therefore unknown).
    //
    // This field will not be set if read chunks were requested, or if the data capture happened to
    // end at a complete read boundary.
    PerClassificationData incomplete = 3;
  }

  message PerChannelData {
    // Data for each channel configuration seen on this channel.
    //
    // Note that each channel configuration will only appear once in this list, and this list is
    // *not* in any way ordered by time. The only reason it is not a map is because of restrictions
    // on map key types.
    repeated PerConfigurationData configurations = 6;

    // The number of samples collected before this channel's first sample.
    uint64 samples_since_start = 2;

    // The number of seconds elapsed since data acquisition started.
    //
    // This is the same as ``samples_since_start``, but expressed in seconds.
    double seconds_since_start = 3;

    // The number of samples collected for this channel.
    uint64 samples_duration = 4;

    // The number of seconds of data captured for this session.
    //
    // This is the same as ``samples_duration``, but expressed in seconds.
    double seconds_duration = 5;
  }

  // Data for each requested channel, in the same order as requested.
  repeated PerChannelData channels = 1;

  // The number of samples collected before the first sample included in this response.
  //
  // This gives the position of the first data point which all channels share in the calculated
  // statistics. Each individual channel may have samples from read chunks previous to this sample
  // due to read boundaries not being consistent across channels.
  uint64 samples_since_start = 2;

  // The number of seconds elapsed before the first sample included in this response.
  //
  // This is the same as ``samples_since_start``, but expressed in seconds.
  double seconds_since_start = 3;
}

message LockChannelStatesRequest {
    // The channels that we want to 'deactivate' = set them to the given state until we re-activate them
    // with unlock_channel_states
    // If the channels are already deactivated, it will update the state to the new forced state given (if different).
    // Channels are indexed from 1.
    repeated uint64 channels = 1 [(rpc_required) = true];

    // Channel state name as specified in the channel state configuration.
    // It HAS to be different to 'unclassified', which denotes that the channel is active, but had not met
    // any successful criteria yet.
    string state_name = 2 [(rpc_required) = true];
}

message LockChannelStatesResponse {}

message UnlockChannelStatesRequest {
    // The channels to activate (active = they will be considered for channel state evaluation in the future).
    // Channels are indexed from 1.
    repeated uint64 channels = 1 [(rpc_required) = true];
}
message UnlockChannelStatesResponse {}

message GetExperimentYieldInfoRequest {}

message GetExperimentYieldInfoResponse{
    message CompleteReadInfo {
        uint64 pending_chunks = 1;
        uint64 pending_memory_reads = 2;
        uint64 pending_disk_reads = 15;
        uint64 pending_multi_disk_reads = 3;
        uint64 pending_skipped_reads = 4;
        uint64 pending_force_skipped_reads = 5;
        uint64 processed_memory_reads = 6;
        uint64 processed_disk_reads = 7;
        uint64 processed_skipped_reads = 8;
        uint64 processed_force_skipped_reads = 9;
        uint64 stored_reads_bytes_memory = 10;
        uint64 stored_read_supporting_bytes_memory = 16;
        uint64 stored_reads_bytes_disk = 11;
        uint64 discarded_error_bytes = 12;
        uint64 channels_writing_to_disk = 13;
        uint64 channels_writing_to_disk_tmp = 14;
    }

    message AcquisitionInfo {
        uint64 raw_per_channel = 1;
        uint64 frame_discontinuities = 2;
    }

    message AnalyserInfo {
        uint64 raw_per_channel = 1;
        uint64 total_selected_raw = 2;
        uint64 total_selected_events = 3;
        uint64 total_events = 4;
        uint64 total_read_chunks = 5;
        uint64 completed_selected_reads_count = 6;
        uint64 completed_unselected_reads_count = 7;
    }

    message BulkInfo {
        uint64 total_raw = 1;
        uint64 total_events = 2;
    }

    message HdfWriterInfo {
        uint64 pending_compressions = 1;
        uint64 pending_writes = 2;
        uint64 pending_hdf_tasks = 3;
        uint64 completed_writes = 4;
        uint64 dataset_bytes_data_in_flight = 5;
    }

    message BasecallStatistics {
        uint64 reads_in_progress = 1;
        uint64 reads_processed = 2;
        uint64 reads_skipped = 3;
        uint64 reads_force_skipped = 4;
        uint64 reads_failed_calling_filtered = 5;
        uint64 reads_failed_calling = 6;
        uint64 reads_called = 7;
        uint64 samples_called = 8;
        uint64 samples_skipped = 9;
        uint64 bases_passed_called = 10;
        uint64 bases_failed_called = 12;
        uint64 events_called = 11;
    }

    message HdfMultiReadWritingStatistics {
        uint64 reads_written = 1;
        uint64 passed_reads_written = 2;
        uint64 failed_reads_written = 3;
        uint64 force_skipped_reads_written = 4;
        uint64 raw_bytes_written = 5;
        uint64 fastq_bytes_written = 6;
        uint64 basecall_events_bytes_written = 7;
    }

    message FastqReadWritingStatistics {
        uint64 passed_reads_written = 1;
        uint64 skipped_reads = 2;
        uint64 forced_skipped = 3;
        uint64 failed_reads_written = 4;
        uint64 failed_reads_discarded = 5;
    }

    message ProtobufReadWritingStatistics {
        uint64 read_chunks_written = 1;
        uint64 read_chunks_discarded = 2;
        uint64 reads_written = 3;
        uint64 reads_discarded = 4;
    }

    message FileOperationQueueProgress {
        message FileTypeInfo {
            uint64 files_moved_successfully = 1;
            uint64 files_moved_to_fallback = 2;
            uint64 files_failed_to_move = 3;
        }

        uint64 pending_operations = 1;
        uint64 complete_successful_operations = 2;
        uint64 complete_failed_operations = 3;

        uint64 bytes_to_move_posted = 4;
        uint64 bytes_to_move_failed = 5;
        uint64 bytes_to_move_completed = 6;

        FileTypeInfo fast5 = 7;
        FileTypeInfo fastq = 8;
    }

    CompleteReadInfo complete_read_info = 1;
    AcquisitionInfo acquisition_info = 2;
    AnalyserInfo analyser_info = 3;
    BulkInfo bulk_info = 4;
    HdfWriterInfo hdf_writer_info = 5;
    BasecallStatistics basecaller_statistics = 6;
    HdfMultiReadWritingStatistics hdf_multi_read_writing_statisitics = 7;
    FastqReadWritingStatistics fastq_read_writing_statistics = 8;
    ProtobufReadWritingStatistics protobuf_read_writing_statistics = 9;
    FileOperationQueueProgress file_operation_queue_progress = 10;
}