Encoding categorization API

Categorizes all neurons in all datasets at all time ranges. Returns the neuron categorization, the p-values for it, and the raw (not multiple-hypothesis corrected) p-values.

Arguments:

• fit_results: CePNEM fit results.
• deconvolved_activity: Dictionary of deconvolved activity values at lattice points.
• P_ranges: Ranges of feeding values
• p: Significant p-value.
• θh_pos_is_ventral: Whether positive θh value corresponds to ventral (true) or dorsal (false) head bending.
• threshold_artifact: Deconvolved activity must differ by at least this much, to filter out motion artifacts
• threshold_weak: Non-deconvolved activity must differ by at least this much, to filter out weak overfitting encodings
• P_diff_thresh (optional, default 0): Minimum feeding variance in a time range necessary for trying to compute feeding info.
• rel_enc_str_correct (optional, default 0): Threshold for deleting neurons with too low relative encoding strength.

Categorizes all neurons from their deconvolved activities.

Arguments:

• deconvolved_activities_1: Deconvolved activities of neurons.
• deconvolved_activities_2: Either 0 (to check neuron encoding), or deconvolved activities of neurons at an earlier time point (to check encoding change).
• p: Significant p-value.
• θh_pos_is_ventral: Whether positive θh value corresponds to ventral (true) or dorsal (false) head bending.
• threshold_artifact: Deconvolved activity must differ by at least this much, to filter out motion artifacts
• threshold_weak: Non-deconvolved activity must differ by at least this much, to filter out weak overfitting encodings
• relative_encoding_strength: Relative encoding strength of the neurons
• rel_enc_str_correct: Threshold for deleting neurons with too low relative encoding strength.
• compute_feeding (optional, default true): Whether to consider feeding behavior in the analysis.
• ewma1 (optional): If set, compute EWMA difference between activities and include it in the all category. Put the EWMA values for the later timepoint here.
• ewma2 (optional): If set, compute EWMA difference between activities and include it in the all category. Put the EWMA values for the earlier timepoint here.

get_all_neurons_with_feature(fit_results::Dict{String, Any}, analysis_dict::Dict{String, Any}, beh::String, sub_behs::Union{Nothing, Vector{String}}, p::Float64=0.05)

Get all neurons that encode a given behavior or sub-behavior feature.

Arguments:

• fit_results::Dict{String, Any}: A dictionary containing the results of fitting CePNEM to neural data.
• analysis_dict::Dict{String, Any}: A dictionary containing the results of analyzing the neural data.
• beh::String: Find neurons that encode this behavior and the corresponding sub-behavior.
• sub_behs::Union{Nothing, Vector{String}}: Find neurons that encode this sub-behavior. If nothing, only encodings of the main behavior are considered.
• p::Float64=0.05: The p-value threshold for considering a neuron to have the given feature.

Returns:

• neurons_use::Dict{String, Vector{Int32}}: A dictionary containing the indices of the neurons with the given feature for each dataset.

get_random_sample_without_feature(fit_results::Dict{String, Any}, analysis_dict::Dict{String, Any}, neurons_with_feature::Dict{String, Vector{Int32}})

Get a random sample of neurons that do not encode a given feature.

Arguments:

• fit_results::Dict{String, Any}: A dictionary containing the results of fitting CePNEM to neural data.
• analysis_dict::Dict{String, Any}: A dictionary containing the results of analyzing the neural data.
• neurons_with_feature::Dict{String, Vector{Int32}}: A dictionary containing the indices of the neurons that encode the feature for each dataset.

Returns:

• neurons_use::Dict{String, Vector{Int32}}: A dictionary containing the indices of the neurons without the given feature for each dataset.
• traces_use::Dict{String, Array{Float64, 2}}: A dictionary containing the traces of the neurons without the given feature for each dataset.

get_subcats(beh)

Get the subcategories of a given behavior.

Arguments:

• beh::String: A string representing the behavior.

Returns:

• subcats::Vector{Tuple{String, String}}: A vector of tuples representing the subcategories of the behavior.

fit_state_classifier(x::Matrix{Float64}, t_stim::Int)

Fit a logistic regression model to classify whether a set of neurons contains "state" information about the indicator function of t_stim, based on neural data x and the time t_stim at which the hypothesized state change occurred. Returns the trained model and its accuracy.

Arguments

• x::Matrix{Float64}: Input data matrix of size (n_features, n_timepoints).
• t_stim::Int: Time of the hypothesized state change.

Returns

• model: Trained logistic regression model.
• accuracy: Accuracy of the trained model.

compute_state_neuron_candidates(
    analysis_dict::Dict, fit_results::Dict, datasets::Vector{String}, strategy::String,
    stim_times::Dict; stim_try=200:50:1400, delta_t::Int=190
)::Dict

Computes the state neuron candidates for each dataset in datasets. They are found by fitting a logistic regression model to the neural data and determining whether the model can predict the state change better than it can predict control time points.

The strategy for selecting the neurons is determined by the strategy argument, which can be one of "increase", "decrease", or "findall":

• "increase": Start from 0 neurons and add state changing neurons until performance no longer improves
• "decrease": Start from all neurons and remove non-state changing neurons until performance starts to degrade
• "findall": Find all neurons with positive performance

The stim_try argument is a range of timepoints to try for the controls.

Arguments

• analysis_dict::Dict: A dictionary containing the CePNEM analysis results.
• fit_results::Dict: A dictionary containing the CePNEM fit results.
• datasets::Vector{String}: A vector of datasets to use. They must all be heat-stimulation datasets.
• strategy::String: The strategy for selecting the neurons.
• stim_times::Dict: A dictionary containing the heat stimulus times for each dataset.
• stim_try: A range of timepoints to try for the state change controls.
• delta_t::Int: The minimum distance between the state change and control timepoints. (Control points closer than this to the real stim are excluded.)

Returns

• state_neuron_candidates::Dict: A dictionary containing the state neuron candidates for each dataset.

get_frac_responding(neurons::Vector{Int}, responses::Dict{String, Any}, response_keys::Vector{String}, decide_fn::Function; response_keys_2::Union{Nothing, Vector{String}}=nothing, decide_fn_2::Union{Nothing, Function}=nothing)

Calculate the fraction of neurons that respond to the heat stimulus in the given way.

Arguments:

• neurons::Vector{String}: A vector of neurons to consider.
• responses::Dict{String, Any}: A dictionary containing the responses of the neurons to the stimulus.
• response_keys::Vector{String}: A vector of keys corresponding to the response types to consider in the responses dictionary.
• decide_fn::Function: A function that takes a response and returns the strength of that response.
• response_keys_2::Union{Nothing, Vector{String}}=nothing: A vector of keys to access a second set of responses in the responses dictionary. If nothing, only the first set of responses is used. If set, this is used as a denominator to normalize the responses.
• decide_fn_2::Union{Nothing, Function}=nothing: A function that takes a response from the second set of responses and returns a boolean indicating whether the neuron responded. If nothing, all neurons are considered to have responded to the second set of responses.

Returns:

• frac_responding::Float64: The fraction of neurons that responded to the stimulus.

subcategorize_all_neurons!(fit_results::Dict, analysis_dict::Dict, datasets::Vector{String})

Subcategorizes all neurons in the given datasets based on their encoding properties and stores the results in analysis_dict.

Arguments

• fit_results::Dict: A dictionary containing the results of fitting CePNEM to the data.
• analysis_dict::Dict: A dictionary to store the results of the analysis.
• datasets::Vector{String}: A vector of dataset names to analyze.

Output

• analysis_dict is updated with the results of the analysis.

sum_subencodings(
    fit_results::Dict, analysis_dict::Dict, relative_encoding_strength::Dict,
    datasets::Vector{String}; mode::String="relative", sufficient_threshold::Float64=1/3
)

Calculate the sum of subencodings for each behavior and subcategory.

Arguments

• fit_results::Dict: A dictionary containing the results of fitting CePNEM to the data.
• analysis_dict::Dict: A dictionary containing the CePNEM analysis results, specifically the neuron categorization and relative encoding strength.
• relative_encoding_strength::Dict: A dictionary containing the relative encoding strength for each behavior in each neuron.
• datasets::Vector{String}: A vector of strings containing the names of the datasets to analyze.
• mode::String: A string indicating the mode of computation. Possible values are "relative", "encoding", and "sufficient". Default is "relative".
• sufficient_threshold::Float64: A float indicating the threshold for sufficient encoding. Default is 1/3. Does nothing for relative and sufficient modes.

Returns

• dict_result::Dict: A dictionary containing the sum of subencodings for each behavior and subcategory.

normalize_subencodings(dict_result::Dict) -> Dict

Normalize the subencodings in the given dictionary per behavior.

Arguments

• dict_result::Dict: A dictionary containing the sum of subencodings for each behavior and subcategory.

Returns

• dict_result_norm::Dict: A dictionary containing the normalized sum of subencodings for each behavior and subcategory.

getneuroncategory(dataset::String, rng::Int, neuron::Int, fitresults::Dict, neuroncategorization::Dict, relativeencodingstrength::Dict)::Tuple{Array{Tuple{String, String}, 1}, Array{Float64, 1}, Float64}

Returns the encoding categories, relative encoding strengths, and time constants for a given neuron in a given dataset and time range.

Arguments:

• dataset::String: The name of the dataset.
• rng::Int: The index of the time range.
• neuron::Int: The index of the neuron.
• fit_results::Dict: The dictionary of CePNEM fit results.
• neuron_categorization::Dict: The dictionary of neuron categorizations.
• relative_encoding_strength::Dict: The dictionary of relative encoding strengths.

Returns:

• encoding::Array{Tuple{String, String}, 1}: An array of tuples representing the encoding categories of the neuron.
• relative_enc_str::Array{Float64, 1}: An array of the relative encoding strengths of the neuron.
• τ::Float64: The time constant of the neuron, in seconds.

getencstats(fitresults::Dict, neuronp::Dict, Pranges::Dict; encodingchanges=nothing, Pdiffthresh::Float64=0.5, p::Float64=0.05, rngs_valid=nothing)

Returns a tuple containing a dictionary containing statistics about the encoding categories of neurons across all datasets and a list of skipped datasets.

Arguments:

• fit_results::Dict: CePNEM fit results.
• neuron_p::Dict: Dictionary of p-values for neuron categorization.
• P_ranges::Dict: Ranges of feeding values.
• P_diff_thresh::Float64 (optional, default 0.5): Minimum feeding variance in a time range necessary for trying to compute feeding info.
• p::Float64 (optional, default 0.05): Significant p-value.
• rngs_valid::Any (optional, default nothing): If set, restrict the ranges that are considered for each dataset to this.

Returns:

• result::Dict{String,Dict}: A dictionary containing statistics about the encoding categories of neurons across all datasets.

get_enc_stats_pool(fit_results::Dict, neuron_p::Dict, P_ranges::Dict; P_diff_thresh::Float64=0.5, p::Float64=0.05, rngs_valid=nothing)

This function calculates the encoding statistics for a pool of datasets. It calls the get_enc_stats function for each dataset and aggregates the results.

Arguments

• fit_results::Dict: A dictionary containing the results of fitting CePNEM to the data.
• neuron_p::Dict: A dictionary containing the p-values for neuron categorization.
• P_ranges::Dict: A dictionary containing the ranges of pumping information.
• P_diff_thresh::Float64: The minimum difference in pumping information required to consider a time range valid.
• p::Float64: Significant p-value.
• rngs_valid::Union{Nothing, Dict}: A dictionary containing the valid ranges for each dataset. If nothing, all ranges are considered valid.

Returns

• A tuple containing the following:
  • n_neurons_beh::Array{Int,1}: An array containing the number of neurons that encode each behavior.
  • n_neurons_npred::Array{Int,1}: An array containing the number of neurons that encode each number of behaviors.
  • n_neurons_fit_all::Int: The total number of neurons that encoded any behavior.
  • n_neurons_tot_all::Int: The total number of neurons.

make_deconvolved_lattice(fit_results, beh_percent, plot_thresh; dataset_mapping=nothing)

Makes deconvolved lattices for each dataset, time range, and neuron in fit_results. Returns velocity, head angle, and pumping ranges, and the deconvolved activity of each neuron at each lattice point defined by them, for both statistically useful ranges (first return value), and full ranges (second return value) designed for plotting consistency. Set dataset_mapping to change which behavioral dataset to use for computing ranges.

get_deconvolved_activity(sampled_trace_params, v_rng, θh_rng, P_rng)

Computes deconvolved activity of model NL8 for each sampled parameter in sampled_trace_params, at a lattice defined by v_rng, θh_rng, and P_rng.

compute_range(beh::Vector{Float64}, beh_percent::Real, beh_idx::Int)

Computes the valid range of a behavior beh (eg: velocity cropped to a given time range). Computes percentile based on beh_percent, and uses 4 points instead of 2 for velocity (beh_idx = 1)

deconvolved_model_nl8(params::Vector{Float64}, v::Float64, θh::Float64, P::Float64)

Evaluate model NL8, deconvolved, given params and v, θh, and P. Does not use the sigmoid. Expression is equivalent to evaluating NL10d since this function does not include the residual model.

neuron_p_vals(
    deconvolved_activity_1, deconvolved_activity_2, signal, threshold_artifact::Real, threshold_weak::Real, 
    relative_encoding_strength; compute_p::Bool=true, metric::Function=abs, stat::Function=median
)

Computes neuron p-values by comparing differences between two different deconvolved activities to a threshold. (Ie: the p-value of rejecting the null hypothesis that the difference is negative or less than the threshold - if p=0, then we can conclude the neuron has the given activity.) To find encoding of a neuron, set the second activity to 0. To find encoding change, set it to a different time window. To find distance between neurons, set compute_p = false and specify the metric (default abs) to use to compare medians of the two posteriors. To use a statistic other than median, change stat.

update_cmap!(cmap, x, y)

Updates choice map cmap to contain parameters x and/or neural data y.

prob_P_greater_Q(P,Q)

Computes Prob(p>q) + Prob(p=q)/2 for p~P, q~Q Here P and Q are arrays of samples.

evaluate_pdf_xgiveny!(x, y_cmap, args, log_ml_est)

Given parameters x (given as an array of the 9 parameters for nl8), observed data y_cmap (neural data, given as a choicemap), args (behavioral data), and log_ml_est from a Gen inference run on y, args, computes P(x | y, args) under model nl8. Updates y_cmap to contain x values as well.