/* 
  This schema specifies basic common elements that most BrainML schemas are
  expected to use and inherit from.
  Nothing is specific to a particular field of neuroscience.  Included are:
  
  View and Trace definitions
  Basic recording site definitions
  Basic protocol definition
  
  Experiment definition
 */
targetNamespace "urn:bml/brainml.org:internal/BrainML/4"
namespace "urn:bml/brainml.org:internal/BrainML/4"
namespace anSubj "urn:bml/brainml.org:med.cornell.edu/AnimalSubject/1"
namespace bmtl "urn:bml/brainml.org:internal/BrainMetaL/1"
import "http://brainml.org/schemas/internal/BrainMetaL/1/xml.xsd" namespace "http://www.w3.org/XML/1998/namespace"
import "http://brainml.org/schemas/internal/BrainMetaL/1/citation.xsd" namespace "urn:bml/brainml.org:internal/BrainMetaL/1"
import "http://brainml.org/schemas/med.cornell.edu/AnimalSubject/1/animalSubject.xsd" namespace "urn:bml/brainml.org:med.cornell.edu/AnimalSubject/1"

/* Link that must go to an experiment entity. */
element link_experiment restricts bmtl:link-type {
    required attribute dest { xs:anyURI } = "urn:bml/brainml.org:internal/BrainML/4,experiment"
}

/* Link that must go to a trace entity. */
element link_trace restricts bmtl:link-type {
    required attribute dest { xs:anyURI } = "urn:bml/brainml.org:internal/BrainML/4,trace"
}

/* Link going to a trace that serves as stimulus for containing trace, which
   should be a response. */
element link_stimulus restricts bmtl:link-type {
    required attribute dest { xs:anyURI } = "urn:bml/brainml.org:internal/BrainML/4,trace"
}

/* Link going to a trace that serves as response for containing trace, which
   should be a stimulus. */
element link_response restricts bmtl:link-type {
    required attribute dest { xs:anyURI } = "urn:bml/brainml.org:internal/BrainML/4,trace"
}

/* Link that must go to a recording_site entity. */
element link_recording_site restricts bmtl:link-type {
    required attribute dest { xs:anyURI } = "urn:bml/brainml.org:internal/BrainML/4,recording_site"
}

/* Contains a set of links to traces forming a logical group. */
element trace_grouping { trace_grouping-type }
complexType trace_grouping-type extends bmtl:collection-type {
    ( link_trace*, )
    
    /* A short description of the grouping type, e.g. 'analysis' or
       'simultaneous' etc.. */
    required attribute type { xs:normalizedString }
}

/* Short name/description of a View or Trace. */
element label { xs:normalizedString }

/* Unit of measure for horizontal axis (often a temporal unit). */
element horizontal_axis_units restricts bmtl:unit-type

/* Short, informative label for horizontal axis. */
element horizontal_axis_label { xs:normalizedString }

/* Unit of measure for vertical axis (dependent variable). */
element vertical_axis_units restricts bmtl:unit-type

/* Short, informative label for vertical axis. */
element vertical_axis_label { xs:normalizedString }

/* Recording start time for Trace. */
element t_start { xs:decimal }

/* Recording end time for Trace. */
element t_end { xs:decimal }

/* Indication of whether Trace represents stimulus signal or neuron response. */
element stimulus { xs:boolean }

/* Trace sampling rate, in units of horizontal axis. */
element t_rate { xs:decimal }

/* Number of trials contributing to View or Histogram's data. */
element number_of_trials { xs:positiveInteger }

/* Type of units reflected by bar height: 'probability', 'percentage', 'Hz',
   or 'count'. */
element vertical_axis_type restricts bmtl:vocab-type {
    attribute domain { xs:token } = "trace.histogram trace.vertical axis type"
}

/* First bin center for Histogram (in H-axis units). */
element bin_start { xs:decimal }

/* Width of bin in Histogram (in H-axis units). */
element bin_width { xs:decimal }

/* Number of bins in Histogram. */
element number_of_bins { xs:nonNegativeInteger }

/* Whether or not the first and last bar heights reflect measurement including
   h-axis values less than min or greater than max. */
element min_max_are_ranges { xs:boolean }

/* Minimum h-axis value in raw histogram. */
element min_value { xs:decimal }

/* maximum h-axis value in a raw histogram. */
element max_value { xs:decimal }

/* Paragraph-length description of Experiment. */
element annotation { xs:string }

/* Recording technique employed in collecting Trace. */
element recording_technique restricts bmtl:vocab-type {
    attribute domain { xs:token } = "trace.recording technique"
}

/* The nature of the data collected in Trace. */
element data_class restricts bmtl:vocab-type {
    attribute domain { xs:token } = "trace.data class"
}
complexType view-type extends bmtl:data_element-type {
    ( number_of_trials?, link_recording_site*, label )
    
    /* Ordering position of this View within its containing experiment. */
    required attribute seq { xs:int }
}

/* Superclass View element.  Do not use directly, but any View defined should
   declare itself in a substitution group with this. */
abstract element view { view-type }

/* 
  Not for inheritance, since we can't later say that the slot must be a
  subclass so that only certain trace types can appear within certain views.
 */
complexType view-type-full extends view-type {
    ( trace, )
}

/* View for containing time-series data. */
element time_series_view substitutes view { time_series_view-type }
complexType time_series_view-type extends view-type {
    ( horizontal_axis_units, time_trace+ )
}

/* View for containing X-Y (2-dimensional plot) data.  Traces share common
   X- and Y-axis units. */
element x_y_view substitutes view { x_y_view-type }
complexType x_y_view-type extends view-type {
    ( horizontal_axis_units, horizontal_axis_label, vertical_axis_units, vertical_axis_label, x_y_trace+ )
}

/* View for containing histogram data. */
element histogram_view substitutes view { histogram_view-type }
complexType histogram_view-type extends view-type {
    ( horizontal_axis_units, horizontal_axis_label, histogram_trace+ )
}

/* Superclass Trace element.  Do not use directly. */
abstract element trace { trace-type }
complexType trace-type extends bmtl:data_element-type {
    ( label, recording_technique?, data_class?, link_recording_site*, ( bmtl:dataset | bmtl:labeled_dataset ) )
    
    /* Order of this Trace relative to others in the same View. */
    required attribute seq { xs:nonNegativeInteger }
}

/* Superclass with common elements of all traces valid in time series view. */
abstract element time_trace { time_trace-type }
complexType time_trace-type extends trace-type {
    ( t_start, )
}

/* Trace consisting of a regularly-sampled list of data values. */
element time_series_trace substitutes time_trace { time_series_trace-type }
complexType time_series_trace-type extends time_trace-type {
    ( t_rate, stimulus, vertical_axis_units )
}

/* Trace consisting of a list of event times at which spikes occurred. */
element spike_train_trace substitutes time_trace { spike_train_trace-type }
complexType spike_train_trace-type extends time_trace-type {
    ( t_end, stimulus? )
}

/* Trace consisting of a list of event times and describing labels.
   These labels may be either strings, integers, or decimal values.
   Data should be contained in a 'labeled_dataset' element, whose first
   child is a decimal type dataset, and whose second child is a dataset
   of any type. */
element event_list_trace substitutes time_trace { event_list_trace-type }
complexType event_list_trace-type extends time_trace-type {
    ( t_end, stimulus, link_trace* )
}

/* The piecewise_series trace is a time series in which flat or linear sections
   are encoded compactly.  The data consists of a list of segments.  Each segment
   starts with a type code and a duration.  Type code may be 1, indicating a
   constant-value segment, 2, indicating a linear segment, 3, indicating a
   normal (fully-specified) segment, or 4, indicating an empty segment (gap).
   The duration is an integer count indicating the number of samples specified
   by this segment.  For constant-value segments, the next number is the
   constant value to be held for this segment.  For linear segments, the next
   number is the final value this segment reaches at the end of its duration.
   The values before it are to be interpolated linearly starting from the value
   of the series just before the linear segment begins.
   (A linear segment cannot begin a piecewise series -- use a length-0
   constant-value segment to indicate the starting value if needed.)
   For type 3 segments, the next duration numbers are the actual samples for
   this segment.
   For type 4 segments, there are no numbers following the duration.  Instead,
   the time series is understood to have no values (not been recorded) for the
   given duration. */
element piecewise_series_trace substitutes time_series_trace { piecewise_series_trace-type }
complexType piecewise_series_trace-type extends time_series_trace-type {
    (, )
}

/* Bivariate trace consisting of a list of x- and y-values.  Dataset 'dimensions'
   should have two values, the first indicating the number of data points in the
   trace (or *), the second indicating the size of each tuple.  This should be
   2 for plain (x,y) pairs, 3 for (x, y, y-error), 4 for
   (x, y, y-error, x-error).  To use asymmetrical error bars, set second
   dimension to 6 and use the format
   (x, y, +y-error, -y-error, +x-error, -x-error). */
element x_y_trace { x_y_trace-type }
complexType x_y_trace-type extends trace-type

/* Superclass for histogram traces. */
abstract element histogram_trace { histogram_trace-type }
complexType histogram_trace-type extends trace-type {
    ( number_of_trials, vertical_axis_label, vertical_axis_type )
}

/* Prebinned histogram trace.  Dataset 'dimensions' should have two values, the
   first indicating the number of data points in the trace (or *), the second
   indicating the size of each tuple, either 1 (value), 2 (value, +/- error),
   or 3 (value, + error, - error). */
element histogram_prebin_trace substitutes histogram_trace { histogram_prebin_trace-type }
complexType histogram_prebin_trace-type extends histogram_trace-type {
    ( bin_start, bin_width, number_of_bins?, min_max_are_ranges )
}

/* Raw histogram trace that the end-consumer selects bin size for.  The values
   provided here are raw values (e.g., the list of times after a marker that
   spikes occurred).  The binning process counts up the numbers of values
   within each range. */
element histogram_raw_trace substitutes histogram_trace { histogram_raw_trace-type }
complexType histogram_raw_trace-type extends histogram_trace-type {
    ( min_value?, max_value? )
}

/* Holds an entire submission. */
element experiment { experiment-type }
complexType experiment-type extends bmtl:data_element-type {
    ( label, annotation, submitter*, contributor+, bmtl:author*, bmtl:citation*, protocol, recording_site+, view+, trace_grouping* )
}

/* Account name (for submitters of data submissions). */
element username { xs:token }

/* A person who signed in and submitted data. */
element submitter { submitter-type }
complexType submitter-type extends bmtl:person-type-full {
    ( username, link_experiment? )
}

/* A person contributing to a data submission. */
element contributor { contributor-type }
complexType contributor-type extends bmtl:person-type {
    ( link_experiment?, )
}

/* Contains information on recording site (location and source). */
element recording_site { recording_site-type }
complexType recording_site-type extends bmtl:entity_element-type {
    ( identifier, recording_location, recording_source?, ( subject_or_preparation | link_subject_or_preparation ), link_experiment? )
}

/* Short, unique, human-readable name or code that should be same as any
   references in published work. */
element identifier { xs:normalizedString }

/* Description of the various recording locations. */
element recording_location {
    ( neural_structure_or_anatomy?, cytoarchitectural_area?, recording_layer?, cell_type?, ( anSubj:receptive_field | anSubj:motor_behavior )* )
    
    /* Keywords describing brain or body location(s). */
    element neural_structure_or_anatomy restricts bmtl:vocab-type {
        attribute domain { xs:token } = "recording location.neural structure / anatomy"
    }
    
    /* Cytoarchitectonic area recording site was found in (Brodmann scheme). */
    element cytoarchitectural_area restricts bmtl:vocab-type {
        attribute domain { xs:token } = "recording location.cytoarchitectural area"
    }
    
    /* Description of the recording layers. */
    element recording_layer restricts bmtl:vocab-type {
        attribute domain { xs:token } = "recording location.recording layer"
    }
    
    /* Description of the cell types. */
    element cell_type restricts bmtl:vocab-type {
        attribute domain { xs:token } = "recording location.cell type"
    }
}

/* Superclass for recording sources; do not use directly. */
element recording_source { xs:anyType }

/* Base entity for describing the subject or preparation in an experiment.
   Different models will extend this depending on what descriptors they
   require. */
element subject_or_preparation { subject_or_preparation-type }
complexType subject_or_preparation-type extends bmtl:entity_element-type {
    ( identifier, )
}
element link_subject_or_preparation restricts bmtl:link-type {
    required attribute dest { xs:anyURI } = "urn:bml/brainml.org:internal/BrainML/4,subject_or_preparation"
}

/* Experimental protocol. */
element protocol { protocol-type }
complexType protocol-type extends bmtl:method_element-type {
    ( preparation, description, stimulus_nudge*, link_experiment? )
}

/* Preparation type used in this Protocol. */
element preparation restricts bmtl:vocab-type {
    attribute domain { xs:token } = "protocol.preparation"
}

/* Short verbal description of Protocol. */
element description { xs:string }

/* Holds details on subject preparation and response elicitation. */
element stimulus_nudge { stimulus_nudge-type }
complexType stimulus_nudge-type {
    ( effector, pattern, location )
}

/* The agent effecting one aspect of the Protocol. */
element effector restricts bmtl:vocab-type {
    attribute domain { xs:token } = "stimulus nudge.effector"
}

/* The manner in which an agent acts to effect one aspect of the Protocol. */
element pattern restricts bmtl:vocab-type {
    attribute domain { xs:token } = "stimulus nudge.pattern"
}

/* The locus at which an agent acts to effect one aspect of the Protocol. */
element location restricts bmtl:vocab-type {
    attribute domain { xs:token } = "stimulus nudge.location"
}

/* Experimental condition.  This is a generic structure for holding information
   about the conditions under which data is collected that is not otherwise
   represented in the data model.  This provides a dimension of flexibility to
   allow recording of information not anticipated at the time of data model
   construction, however it is generally best to avoid use of this facility when
   possible because it prevents standardization on descriptors used.  This makes
   data more difficult to search for and link to data in other databases. */
element condition { condition-type }
complexType condition-type extends bmtl:method_element-type {
    
    /* A short descriptive name of what this condition represents. */
    required attribute name { xs:normalizedString }
    
    /* Data type for this condition's value: either 'numeric' or 'text'. */
    required attribute type { xs:token { /numeric|text/  } }
    
    /* Value for the experimental condition.  Should follow 'type'. */
    required attribute value { xs:normalizedString }
    
    /* For numeric condition values that represent measured quantities, specify
      the units.  Note this is not controlled in the way units generally are in
      BrainML (based on the BrainMetaL 'unit' type), but a plain string. */
    attribute units { xs:token }
}

/* Represents a channel containing a data stream recorded from some source,
   such as a neuron, or a stimulus variable. */
element signal_channel { signal_channel-type }
complexType signal_channel-type {
    
    /* Unique identifier for the channel. */
    required attribute id { xs:ID }
    
    /* Sequence number for the channel, out of its group. */
    required attribute seq { xs:positiveInteger }
    
    /* Short, precise, descriptive name for the channel. */
    required attribute name { xs:token }
    
    /* Units for the channel's values.  Note this is not controlled in the way
      units generally are in BrainML (based on the BrainMetaL 'unit' type),
      but a plain string. */
    required attribute units { xs:token }
}

/* Element specifying a computational analysis to be carried out.
   It contains a spike train data set together with attributional and
   other metadata, a grouping imposed on the dataset indicating how to
   structure the analysis, and a specification of the algorithm to be
   used in performing the analysis. */
element analysis_input { analysis_input-type }
complexType analysis_input-type extends bmtl:method_element-type {
    ( algorithm_settings+, experiment )
}

/* Contains specification of how to apply an algorithm.  This is
   an abstract place-holder extended by specific applications. */
abstract element algorithm_settings { algorithm_settings-type }
complexType algorithm_settings-type extends bmtl:data_element-type

/* Describes an algorithm for computational analysis. */
element algorithm { algorithm-type }
complexType algorithm-type extends bmtl:method_element-type {
    ( name, short_description?, long_description?, bmtl:author*, bmtl:citation*, module* )
}

/* Algorithm module, which is defined as a stage of an analysis algorithm
   that fulfills a distinct task. */
element module { module-type }
complexType module-type extends bmtl:method_element-type {
    ( name, short_description?, long_description?, user_input* )
    
    /* Sequence number for the module. */
    required attribute seq { xs:positiveInteger }
}

/* Defines the type of user setting, either a parameter or an option. */
abstract element user_input { user_input-type }
complexType user_input-type extends bmtl:method_element-type {
    ( name, display_name?, short_description? )
    
    /* State whether this parameter, option, or estimation method is required or not. */
    required attribute \required { xs:boolean }
}

/* User-settable algorithm entropy or variance estimation method. */
element estimation_method substitutes user_input { estimation_method-type }
complexType estimation_method-type extends user_input-type {
    ( method_item*, )
}

/* User-settable algorithm estimation method item. */
element method_item substitutes user_input { method_item-type }
complexType method_item-type extends user_input-type {
    ( vectorizable, default_value, item_option+ )
}

/* User-settable algorithm estimation method item. */
element item_option substitutes user_input { item_option-type }
complexType item_option-type extends user_input-type {
    ( value { xs:integer }, parameter*, option* )
}

/* User-settable algorithm module parameter.  A range of valid values
   may optionally specified. */
element parameter substitutes user_input { parameter-type }
complexType parameter-type extends user_input-type {
    ( vectorizable, default_value, range? )
}

/* Algorithm module option, which may take one or more values from a
   specified set. */
element option substitutes user_input { option-type }
complexType option-type extends user_input-type {
    ( vectorizable, default_value, option_set )
}

/* A short name such as a variable name or symbol representing a value. */
element name { xs:token }

/* A descriptive name that may be displayed in a user interface. */
element display_name { xs:normalizedString }

/* Short description (e.g., a sentence) of an algorithm, module or parameter. */
element short_description { xs:normalizedString }

/* Long description (e.g., a paragraph) of an algorithm or module. */
element long_description { xs:normalizedString }

/* Indication of whether parameter is vectorizable or not. */
element vectorizable { xs:boolean }

/* Default value for algorithm module parameter or option. */
element default_value { default_value-type }
complexType default_value-type extends bmtl:data_element-type {
    ( bmtl:dataset, )
}

/* Specifies a range of permitted values by means of min, min_or_equal,
   max, max_or_equal.  Range boundaries may be either numbers or the
   names of variables.  Mainly this is used for analysis algorithm
   description to specify the range of valid values for a parameter. */
element range { range-type }
complexType range-type extends bmtl:data_element-type {
    ( ( min { xs:token }? | min_or_equal { xs:token }? ), ( max { xs:token }? | max_or_equal { xs:token }? ) )
}

/* Set of permitted values for option. */
element option_set { option_set-type }
complexType option_set-type extends bmtl:data_element-type {
    ( bmtl:labeled_dataset, )
}

/* 
             Element containing the metadata of the experiment and
             results of a computational analysis.
 */
element analysis_output { analysis_output-type }
complexType analysis_output-type extends bmtl:data_element-type {
    ( experiment, output_data, message? )
}

/* 
              Element containing the submission information such as the
              status (e.g. PROCESSED, PROCESSING) of a
              computational analysis.
 */
element analysis_submission { analysis_submission-type }
complexType analysis_submission-type extends bmtl:data_element-type {
    ( status, date_received, date_sent, estimated_time, message? )
}

/* Status of an analysis or other online process, e.g. 'pending', 'processed'.
 */
element status { xs:string }

/* Message sent accompanying status to provide further information. */
element message { xs:normalizedString }

/* Date and time of receiving the results of the analysis.
    Formatted according to xs:dateTime standard, e.g. "2006-09-08T09:30:10Z". */
element date_received { xs:dateTime }

/* Date and time of submitting the analysis.
    Formatted according to xs:dateTime standard, e.g. "2006-09-08T09:30:10Z". */
element date_sent { xs:dateTime }

/* 
             The estimated amount of time in seconds for completion of the analysis.
 */
element estimated_time { xs:integer }

/* Contains output data as a result of computational analysis.  This is
   an abstract place-holder extended by specific applications. */
abstract element output_data { output_data-type }
complexType output_data-type extends bmtl:data_element-type