cogstat.cogstat

CogStat is a Python module and also a GUI-based application that analyses the data automatically after the data (with their measurement levels) and the tasks are specified.

class CogStatData:

CogStat object (data) and the available main analyses.

The analyses methods return an ordered dictionary.

  • The key is the name of the subsection, and the value is the output.
  • Only the values will be displayed in the order as they are stored in the dictionary.
  • The values can include HTML str, pandas styler, matplotlib figure, or the list of any of these (but no nested list).

The keys describe the analysis section. Some typical keys are (but others may also be used)

  • analysis
    • warning
  • raw data
  • sample
    • descriptives
    • sample effect size
  • population
    • assumption
    • estimation
    • population effect size
    • hypothesis test

Orthogonally,type of information may also be included in the key:

  • info: includes headings and additional details of the analysis
  • table: results in table/numerical format
  • chart: results in charts
  • or no information type is added
CogStatData(data, measurement_levels=None)

Initialize the cogstat data object.

In the spreaqdsheet or string input data:

  • First line should be the variable name --- If there are missing names, Unnamed:0, Unnamed:1, etc. names are given --- If there are repeating var names, new available numbers are added, e.g. a.1, a.2, etc.
  • Second line could be the measurement level

The measurement levels are set in the following order:

  • All variables are 'unknown'.
  • Then, if import data includes measurement level, then that information will be used.
  • Then, if measurement_levels parameter is set, then that will be used.
  • Finally, constraints (e.g., string variables can be nominal variables) will overwrite measurement levels.

More information on data handling: https://doc.cogstat.org/Handling-data

Data structure that is created:

  • self.orig_data_frame - pandas DataFrame, the original data without filtering
  • self.data_frame - pandas DataFrame, the actual data with optional filtering
  • self.data_measlevs - dictionary storing level of measurement of the variables (name:level):
    • 'nom', 'ord', or 'int' (ratio is included in 'int')
    • 'unk' - unknown: if no other level is given
  • self.filtering_status - list of two items:
    • [0] list of the variables the filtering is based on (or None)
    • [1] the name of the filtering method (or '')
  • self.import_source - list of 2 strings:
    • [0]: import data type
    • [1]: path to the data file or '' if the data source is not a file
  • self.import_message - text output of the imported process
    • can't return anything to caller, since we're in an __init__ method, so store the message here
Parameters
  • data (pandas.DataFrame or str): Data to be imported. This can be:
    • Pandas DataFrame
    • Clipboard data from a spreadsheet (identified as multiline string)
    • Filename (identified as one line text)
  • measurement_levels : None, list of {'nom', 'ord', 'int'} or dict of {str ({'nom', 'ord', 'int'}}): Optional measurement levels of the variables
    • None: measurement level of the import file or the clipboard information will be used
    • List of strings ('nom', 'ord', 'int'): measurement levels will be assigned to variables in that order. It overwrites the import data information. Additional constraints (e.g., string variables can be nominal variables) will overwrite this.
    • Dictionary, items are variable name and measurement level pairs: measurement levels will be assigned to the appropriate variables. It overwrites the import data information. Additional constraints (e.g., string variables can be nominal variables) will overwrite this.
def reload_data(self):

Reload actual data from the path it has been read previously.

Returns
  • list of a single str: Report in HTML format
def print_data(self, show_heading=True, brief=False):

Display the data.

Parameters
  • show_heading (bool): Add heading to the output string?
  • brief (bool): Should only the first few cases (True) or the whole data frame (False) be displayed?
Returns
  • str: HTML string showing the data.
def filter_outlier(self, var_names=None, mode='univariate'):

Filter self.data_frame based on outliers.

  • With univariate methods, all variables are investigated independently and cases are excluded if any variable shows they are outliers.
  • If mode is 'multivariate', then variables are jointly investigated for multivariate outliers.
  • If var_names is None or [], then the filtering will be switched off (i.e. all cases will be used).
  • If any values in the given variables are missing in a case, the whole case will also be excluded.

It modifies the self.filtering_status.

More information on CogStat outlier filtering: https://doc.cogstat.org/Filter-outliers

Parameters
  • var_names (None or list of str): Names of the variables the exclusion is based on or None to include all cases. Variables must be interval (or unknown) measurement level variables.
  • mode ({'univariate', 'multivariate'}): Mode of the exclusion: univariate: median +- 2.5 * MAD multivariate: Mahalanobis-MCD distance with .05 chi squared cut-off
Returns
  • list of str: List of HTML strings showing the filtered cases. The method modifies the self.data_frame in place.
  • list of charts: If cases were filtered, then filtered and remaining cases are shown.
def explore_variable(self, var_name='', frequencies=True, central_value=0.0):

Explore a single variable.

More information: https://doc.cogstat.org/Explore-variable

Parameters
  • var_name (str): Name of the variable
  • frequencies (bool): Should the frequencies be shown?
  • central_value (float): Test value for testing a central tendency.
Returns
  • dict: Results of the analysis
def reliability_internal(self, var_names=None, reverse_items=None):

Calculate internal consistency reliability using Cronbach's alpha, and it's confidence interval, as well as item-rest correlations and their confidence intervals.

More information: https://doc.cogstat.org/Internal-consistency-reliability-analysis

Parameters
  • var_names (list of str): Names of the variables or items.
  • reverse_items (list of str): Subset of var_names. Names of reverse-coded variables or items.
Returns
  • dict: Results of the analysis
def reliability_interrater(self, var_names=None, ratings_averaged=True, ylims=[None, None]):

Calculate inter-rater reliability using intraclass correlation. Use the McGraw and Wong, 1996 terms. Follow the Liljequist et al. 2019 strategy and display three indexes.

More information: https://doc.cogstat.org/Interrater-reliability-analysis

Parameters
  • var_names (list of str): Names of variables containing the ratings of the raters.
  • ratings_averaged (bool): Are the ratings averaged?
  • ylims (list of {int or float}): Limit of the y-axis for interval and ordinal variables instead of using automatic values.
Returns
  • dict: Results of the analysis
def regression( self, predictors=None, predicted=None, xlims=[None, None], ylims=[None, None]):

Explore a variable pair or explore multiple predictors and one predicted variable.

More information: https://doc.cogstat.org/Explore-relation-of-variables

Parameters
  • predictors (list of str): Name of the predictor variables.
  • predicted (str): Name of the predicted variable.
  • xlims (list of {int or float}): Limit of the x-axis for interval and ordinal variables instead of using automatic values.
  • ylims (list of {int or float}): Limit of the y-axis for interval and ordinal variables instead of using automatic values.
Returns
  • dict: Results of the analysis
def pivot( self, depend_name='', row_names=None, col_names=None, page_names=None, function='Mean'):

Compute a pivot table.

More information: https://doc.cogstat.org/Pivot-table

Parameters
  • depend_name (str): NAae of the dependent variables.
  • row_names (list of str): Variable names serving as row grouping variables.
  • col_names (list of str): Variable names serving as column grouping variables.
  • page_names (list of str): Variable names serving as page grouping variables.
  • function ({'N', 'Sum', 'Mean', 'Median', 'Lower quartile', 'Upper quartile', 'Standard deviation', 'Variance'}): Functions applied to pivot cells. Use localized version of the functions if CogStat is used in a non-English language.
Returns
  • list of str and image: Analysis results in HTML format
def diffusion( self, error_name='', RT_name='', participant_name='', condition_names=None, correct_coding='0', reaction_time_in='sec', scaling_parameter=0.1):

Run diffusion analysis on behavioral data.

Dataframe should include a single trial in a case (row).

More information: https://doc.cogstat.org/Behavioral-data-diffusion-analysis

Parameters
  • error_name (str): Name of the variable storing the errors. Correct and incorrect trials should be coded with 0 and 1. See the correct_coding parameter.
  • RT_name (str): Name of the variable storing response times. Time should be stored in sec or msec. See the reaction_time_in parameter.
  • participant_name (str): Name of the variable storing participant IDs.
  • condition_names (list of str): Name(s) of the variable(s) storing conditions.
  • correct_coding ({'0', '1'}): Are correct responses noted with 0 or 1? Incorrect responses are noted with the other value.
  • reaction_time_in ({'sec', 'msec'}): Unit of the reaction times
  • scaling_parameter (float): Usually either 0.1 or 1
Returns
  • dict: Results of the analysis
def compare_variables( self, var_names, factors=None, display_factors=None, ylabel='', ylims=[None, None]):

Compare repeated measures variables.

More information: https://doc.cogstat.org/Compare-repeated-measures-variables

Parameters
  • var_names (list of str): The variable to be compared.
  • factors (list of list of [str, int]): The factor names and their levels, e.g., [['name of the factor', number_of_the_levels], ['name of the factor 2', number_of_the_levels]] Factorial combination of the factors will be generated, and variables will be assigned respectively
  • display_factors (list of two lists of strings): Factors to be displayed on x-axis, and color (panel cannot be used for repeated measures data).
  • ylabel (str): Label for the y-axis
  • ylims (list of {int or float}): Limit of the y-axis for interval and ordinal variables instead of using automatic values.
Returns
  • dict: Results of the analysis
def compare_groups( self, var_name, grouping_variables=None, display_factors=None, single_case_slope_SE=None, single_case_slope_trial_n=None, ylims=[None, None]):

Compare groups.

More information: https://doc.cogstat.org/Compare-groups

Parameters
  • var_name (str): Name of the dependent variable
  • grouping_variables (list of str): List of name(s) of grouping variable(s).
  • display_factors (list of three list of strings): List of name(s) of grouping variable(s) displayed on x-axis, with colors, and on panels.
  • single_case_slope_SE (str): When comparing the slope between a single case and a group, variable name storing the slope SEs
  • single_case_slope_trial (int): When comparing the slope between a single case and a group, number of trials.
  • ylims (list of {int or float}): Limit of the y-axis for interval and ordinal variables instead of using automatic values.
Returns
  • dict: Results of the analysis
def compare_variables_groups( self, var_names=None, factors=None, grouping_variables=None, display_factors=None, single_case_slope_SE=None, single_case_slope_trial_n=None, ylabel='', ylims=[None, None]):

Compare mixed-design (repeated measures and groups) data.

More information: https://doc.cogstat.org/Compare-repeated-measures-variables-and-groups

Parameters
  • var_names (list of str): The variable to be compared.
  • factors (list of list of [str, int]): The repeated measures factors and their levels, e.g., [['name of the factor', number_of_the_levels], ['name of the factor 2', number_of_the_levels]] Factorial combination of the factors will be generated, and variables will be assigned respectively
  • grouping_variables (list of str): List of name(s) of grouping variable(s).
  • display_factors (list of three lists of strings): Factors (either repeated measures or groups or both) to be displayed on x-axis, color, and panel (but panel cannot be used for repeated measures data)
  • single_case_slope_SE (str): When comparing the slope between a single case and a group, variable name storing the slope SEs
  • single_case_slope_trial (int): When comparing the slope between a single case and a group, number of trials.
  • ylabel (str): Label for the repeated measures chart y-axis
  • ylims (list of {int or float}): Limit of the y-axis for interval and ordinal variables instead of using automatic values.
Returns
  • dict: Results of the analysis
def display(results):

Display the result dictionary in Jupyter Notebook.

Parameters
  • results (dict of {str, image, pandas styler, list}): HTML results.