`rs_read_coorddata(fullname, aux)`

[data_out,aux_out]=rs_read_coorddata(fullname,aux) reads a coordinate file into a dataset structure with a single record

This is the preferred method for bringing coordinates from a single file into a dataset structure suitable for display and geometrical analysis.

For files generated by analysis of similarity judgments via [??how to refer to Python package], this will also import the goodness-of-fit data.
For multiple coordinate sets collected with the same experimental paradigm, use rs_get_coordsets, or use this routine and combine multiple dataset structures into a single dataset structure with rs_concat_coordsets.
A ray structure will be created.
To create a coordinate structure based on a quadratic form model, also use rs_get_coordsets.
For binary texture domain data with symmetry augmentation, use rs_get_coordsets.
To import coordinates generated externally or that exist as arrays rather than in a file, use rs_import_coordsets.

Input arguments:

fullname (char or singleton char array) –

full file name with path; if empty, it will be requested interactively. File names must contain the string '_coords'. See note below regarding setup files.
aux (struct) –
a structure, can be omitted, with fields
- opts_read (struct) – options for reading, can be omitted, with fields
  - if_gui (int) – 1 to use graphical interface to request data file name if 'fullname' is empty, 0 to use console; default is 1; see note below regarding customization
  - if_log (int) – 1 to log progress, 0 to omit; default is 1; see note below regarding customization
  - data_fullname_def (char) – prompt for data file if fullname' is empty; see note below regarding customization
  - ui_filter (char) – file name filter that appears in graphical user interface when if_gui=1; defaults to '_coords';see note below regarding customization
- opts_rays (struct) – options for identifying rays, may be omitted; see rs_findrays for details
- opts_check (struct) – options for consistency checking, with field
  - if_warn (int) – 1 to show warnings when datasets are checked for consistency, 0 to suppress; default is 1

Output arguments:

data_out ( struct ) –
dataset structure with one record, and fields
- ds (singleton cell array) – coordinate structure, ds{1}{idim} is an array of [nstims idim] of coordinates for the sole record
- sas (singleton cell array) – stimulus metadata structure, sas{1} is the stimulus metadata for the sole record
- sets (singleton cell array) – set metadata structure, sets{1} is the response metadata for the sole record
aux_out ( struct ) –
auxiliary outputs and parameter values used, with fields
- warnings (char) – warnings generated during consistency check
- warn_bad (int) – number of warnings that prevent further processing
- rayss (cell array of struct) – rayss{1} is the ray structure for the sole record
- opts_read (cell array of struct) – opts_read{1} is aux.opts_read, with defaults filled in
- opts_rays (cell array of struct) – opts_rays{1} are the options used for creating the ray structure for the sole record
- opts_qpred (cell array of struct) – empty (included for compatibility with rs_get_coordsets)
- syms_list (struct) – empty (included for compatibility with rs_get_coordsets)
- opts_check (struct) – aux.opts_check, with defaults filled in

Note regarding domain names, stimulus coordinates, and setup files

The domain name is determined from the data file name based on the string preceding '_coords' (or, opts_read.coord_string, if customized). This in turn determines how stimulus coordinates are specified.
- For non-reserved domain names (opts_read.type_class_aux, or any domain in opts_read.domain_list_def), stimulus coordinates are specified by 'type_coords' and no setup file is used.
- Other domain names are reserved, and stimulus coordinates are specified by a 'setup file', whose suggested name is constructed from the data file name up to the string preceding opts_read.coord_string, and appending opts_read.setup_suffix
- The domain name is also used to determine a 'type_class', which is used internally. This is carried out in psg_coorddata_parsename, as follows:
  - The domains 'faces*' are reserved; type_class is faces_mpi; used with a setup file
  - The domain 'irgb' is reserved; type_class is 'irgb'; used with a setup file
  - The domain 'mater' is reserved; type_class is 'mater'; used with a setup file
  - The domain opts_read.type_class_aux is NOT reserved; type class is type_class_aux; no setup file used
  - Any domain that is listed in opts_read.domain_list_def is NOT reserved; type class is 'domain'; no setup file used
- Otherwise, type_class is set to opts_read.type_class_def, ('btc' unless customized); used with a setup file
When a dataset structure is written by rs_write_coordsets, the setup file information, if any, will be embedded. When that file is read in and an embedded setup file is detected, no setup file is requested.
Also see note below regarding customization

Note regarding customization

The defaults for the following parameters can be set by editing the line containing generic.opts_read.[param_name] in rs_aux_defaults_define, running it once, and saving the workspace as rs_aux_defaults.mat.
- if_gui
- ui_filter
- if_log
- data_fullname_def
- setup_fullname_def
- domain_list_def
- setup_suffix
- permutes_ok
- coord_string
- type_class_aux

See also: rs_import_coordsets, rs_aux_customize, rs_findrays, rs_check_coordsets, PSG_READ_COORDDATA, PSG_MAKE_SETSTRUCT, PSG_FINDRAYS_SETOPTS, PSG_FINDRAYS.

Source code in src/rs_read_coorddata.m

function [data_out,aux_out]=rs_read_coorddata(fullname,aux)
% [data_out,aux_out]=rs_read_coorddata(fullname,aux) reads a `coordinate file` into a `dataset structure` with a single record
%
% This is the preferred method for bringing coordinates from a single file into a `dataset structure` suitable for display and geometrical analysis.
%
%  - For files generated by analysis of similarity judgments via [??how to refer to Python package], this will also import the goodness-of-fit data.
%  - For multiple coordinate sets collected with the same experimental paradigm, use `rs_get_coordsets`, or use this routine and combine multiple `dataset structures` 
%    into a single `dataset structure` with `rs_concat_coordsets`.
%  - A `ray structure` will be created.
%  - To create a `coordinate structure` based on a `quadratic form model`, also use `rs_get_coordsets`.
%  - For `binary texture domain` data with symmetry augmentation, use `rs_get_coordsets`.
%  - To import coordinates generated externally or that exist as arrays rather than in a file, use `rs_import_coordsets`.
%
% Args:
%   fullname (char or singleton char array): full file name with path; if empty, it will be requested interactively. File names must contain the string '_coords'. See note below regarding setup files.
%
%   aux (struct): a structure, can be omitted, with fields 
%
%     - opts_read (struct): options for reading, can be omitted, with fields
%
%         - if_gui (int): 1 to use graphical interface to request data file name if 'fullname' is empty, 0 to use console; default is 1; see note below regarding customization
%         - if_log (int): 1 to log progress, 0 to omit; default is 1; see note below regarding customization
%         - data_fullname_def (char): prompt for data file if fullname' is empty; see note below regarding customization
%         - ui_filter (char): file name filter that appears in graphical user interface when if_gui=1; defaults to '*_coords*';see note below regarding customization
%
%         - **Options related to stimulus coordinates, domains, and setup files (see notes below)** 
%         - type_coords (float 2-D array): stimulus coordinates to use for non-reserved domain names, one row for each stimulus; default is empty
%         - type_coords_def (char): stimulus coordinates to use if type_coords is unspecified or empty; options are 'none', 'zeros', 'ones', or 'eye', see `rs_import_coordsets`; default is 'none'; see `rs_import_coordsets` for further details and how to customize
%         - domain_list_def (cell array): paradigm names for generic domain experiments; default is {'cars','tools','dwellings'}; determined by customization during install
%         - paradigm_type_def (char): default paradigm type; default is determined by customization during install
%         - coord_string (char): a string in a data file name that delineates the end of the domain name; defaults to '_coords'
%         - setup_fullname_def (char): prompt for setup file name
%         - setup_suffix (char): suffix added to paradigm name to create the setup file name; default is 'S'
%         - type_class_aux (char): a specified domain name and type_class
%
%         - **Options for internal use and maintenance**
%         - permutes (struct): typically omitted; each field is a suggested ray permutation for the corresponding paradigm name, e.g., permutes.bgca=[2 1 3 4] specifies a reordering of the rays for paradigm 'bgca'
%         - permutes_ok (int): typically omitted; 1 to accept suggested ray permutation, 0 to keep standard order; default is 1; see note below regarding customization
%         - if_uselocal (int): typically omitted; 0 to use options in rs_aux_defaults, 1 is reserved for maintenance; default is 0
%
%     - opts_rays (struct): options for identifying rays, may be omitted; see `rs_findrays` for details
%
%     - opts_check (struct): options for consistency checking, with field
%
%         - if_warn (int): 1 to show warnings when datasets are checked for consistency, 0 to suppress; default is 1
%
% Returns:
%   data_out (struct): `dataset structure` with one record, and fields
%
%     - ds (singleton cell array): `coordinate structure`, ds{1}{idim} is an array of [nstims idim] of coordinates for the sole record
%     - sas (singleton cell array): `stimulus metadata structure`, sas{1} is the stimulus metadata for the sole record
%     - sets (singleton cell array): `set metadata structure`, sets{1} is the response metadata for the sole record
%
%   aux_out (struct): auxiliary outputs and parameter values used, with fields
%
%     - warnings (char): warnings generated during consistency check
%     - warn_bad (int): number of warnings that prevent further processing
%     - rayss (cell array of struct): rayss{1} is the `ray structure` for the sole record
%     - opts_read (cell array of struct): opts_read{1} is aux.opts_read, with defaults filled in
%     - opts_rays (cell array of struct): opts_rays{1} are the options used for creating the `ray structure` for the sole record
%     - opts_qpred (cell array of struct): empty (included for compatibility with `rs_get_coordsets`)
%     - syms_list (struct): empty (included for compatibility with `rs_get_coordsets`)
%     - opts_check (struct): aux.opts_check, with defaults filled in
%
% Note: Note regarding domain names, stimulus coordinates, and setup files
%     - The domain name is determined from the data file name based on the string preceding '_coords' (or, opts_read.coord_string, if customized).  This in turn determines how stimulus coordinates are specified.
%
%         - For non-reserved domain names (opts_read.type_class_aux, or any domain in opts_read.domain_list_def), stimulus coordinates are specified by 'type_coords' and no setup file is used.
%         - Other domain names are reserved, and stimulus coordinates are specified by a 'setup file', whose suggested name is constructed from the data file name up to the string preceding opts_read.coord_string, and appending opts_read.setup_suffix
%         - The domain name is also used to determine a 'type_class', which is used internally. This is carried out in psg_coorddata_parsename, as follows:
%
%             - The domains 'faces*' are reserved; type_class is faces_mpi; used with a setup file
%             - The domain 'irgb' is reserved; type_class is 'irgb'; used with a setup file
%             - The domain 'mater' is reserved; type_class is 'mater'; used with a setup file
%             - The domain opts_read.type_class_aux is NOT reserved; type class is type_class_aux; no setup file used
%             - Any domain that is listed in opts_read.domain_list_def is NOT reserved; type class is 'domain'; no setup file used
%
%         - Otherwise, type_class is set to opts_read.type_class_def, ('btc' unless customized); used with a setup file
%
%     - When a `dataset structure` is written by `rs_write_coordsets`, the setup file information, if any, will be embedded. When that file is read in and an embedded setup file is detected, no setup file is requested.
%     - Also see note below regarding customization
%
% Note: Note regarding customization
%     - The defaults for the following parameters can be set by editing the line containing generic.opts_read.[param_name] in  `rs_aux_defaults_define`, running it once, and saving the workspace as rs_aux_defaults.mat.
%
%         - if_gui
%         - ui_filter
%         - if_log
%         - data_fullname_def
%         - setup_fullname_def
%         - domain_list_def
%         - setup_suffix
%         - permutes_ok
%         - coord_string
%         - type_class_aux
%
%  See also: RS_IMPORT_COORDSETS, RS_AUX_CUSTOMIZE, RS_FINDRAYS, RS_CHECK_COORDSETS,
%   PSG_READ_COORDDATA, PSG_MAKE_SETSTRUCT, PSG_FINDRAYS_SETOPTS, PSG_FINDRAYS.
%
if (nargin<=1)
    aux=struct;
end
aux=filldefault(aux,'opts_read',struct);
aux.opts_read=filldefault(aux.opts_read,'type_coords',[]);
type_coords_def=getfield(getfield(rs_aux_customize(setfield(struct(),'opts_import',struct()),'rs_import_coordsets'),'opts_import'),'type_coords_def');
aux.opts_read=filldefault(aux.opts_read,'type_coords_def',type_coords_def);
%
aux=filldefault(aux,'opts_rays',struct);
%
aux=filldefault(aux,'opts_check',struct);
aux.opts_check=filldefault(aux.opts_check,'if_warn',1);
%
aux=rs_aux_customize(aux,'rs_read_coorddata');
%
data_out=struct;
aux_out=struct;
aux_out.warnings=[];
aux_out.warn_bad=0;
%
if iscell(fullname)
    fullname=fullname{1};
end
%
if isempty(fullname)
    if aux.opts_read.if_gui
        if_manual=0;
        if aux.opts_read.if_justsetup
            ui_prompt='Select a setup file';
            ui_filter={cat(2,'*',aux.opts_read.setup_suffix,'.mat'),'setup file'};
        else
            ui_prompt='Select a coordinate file';
            ui_filter=aux.opts_read.ui_filter;
        end
        while (if_manual==0 & isempty(fullname))
            [filename_short,pathname]=uigetfile(ui_filter,ui_prompt,'Multiselect','off');
            if  (isequal(filename_short,0) | isequal(pathname,0)) %use Matlab's suggested way to detect cancel
                if_manual=getinp('1 to return to selection from console','d',[0 1]);
            else
                fullname=cat(2,pathname,filename_short);
            end
        end
    end
end
if aux.opts_read.if_justsetup==0
    [d,sa,opts_read_used,pipeline]=psg_read_coorddata(fullname,[],aux.opts_read);
    opts_read_used.data_fullnames={opts_read_used.data_fullname}; %for compatibility with rs_get_coordsets
    opts_read_used.setup_fullnames={opts_read_used.setup_fullname}; %for compatibility with rs_get_coordsets
    opts_read_used.input_type_desc=aux.opts_read.input_types{1}; %rs_read_coorddata only reads experimental data, which is type 1
    opts_makeset.paradigm_type_def=aux.opts_read.paradigm_type_def;
    opts_makeset.domain_list_def=aux.opts_read.domain_list_def;
    opts_makeset.if_uselocal=aux.opts_read.if_uselocal;
    sets=psg_make_setstruct('data',opts_read_used.dim_list,opts_read_used.data_fullname,sa.nstims,pipeline,opts_makeset);
    %
    [rays,wmsg,opts_rays_used]=rs_findrays(sa,opts_read_used.setup_fullname,aux.opts_rays);
    if ~isempty(wmsg)
        aux_out=rs_warning(wmsg,0,aux_out);
    end
else
    setup_fullname=fullname;
    [d,sa,opts_read_used,pipeline]=psg_read_coorddata(fullname,setup_fullname,aux.opts_read);
    d=struct;
    sets=struct;
end
%
data_out.ds{1}=d;
data_out.sas{1}=sa;
data_out.sets{1}=sets;
aux_out.opts_check=aux.opts_check;
aux_out.opts_read{1}=opts_read_used;
aux_out.opts_rays{1}=opts_rays_used;
aux_out.rayss{1}=rays;
%for compatibility with rs_get_coordsets;
aux_out.opts_qpred{1}=struct;
aux_out.syms_list=struct();
%
%check consistency
%
check=rs_check_coordsets(data_out,aux.opts_check);
if ~isempty(check.warnings) %since strvcat([],[])~=[]
    aux_out.warnings=strvcat(aux_out.warnings,check.warnings);
    warn_leadin=getfield(getfield(rs_aux_customize(struct()),'overall'),'warn_leadin');
    for k=1:size(aux_out.warnings,1)
        disp(cat(2,warn_leadin,aux_out.warnings(k,:)));
    end
end
aux_out.warn_bad=aux_out.warn_bad+check.warn_bad;
return