Home > api-openbis-matlab > OpenBis.m

OpenBis

PURPOSE ^

SYNOPSIS ^

This is a script file.

DESCRIPTION ^


CROSS-REFERENCE INFORMATION ^

This function calls: This function is called by:

SUBFUNCTIONS ^

SOURCE CODE ^

0001 classdef OpenBis
0002     % OpenBis   High-level class for interacting with Python (pyBIS) Openbis objects
0003     % This class creates a MATLAB OpenBis object that encapsulates the Python (pyBIS) Openbis object
0004     % and provides methods for interacting with the Python (pyBIS) Openbis object.
0005     %
0006     % Usage:
0007     % Construct the MATLAB OpenBis object like this:
0008     % obi = OpenBis()
0009     % This will ask for URL, user name and password to connect to openBIS server.
0010     % These can also be provided as optional input arguments.
0011     %
0012     % Methods are generally called like this:
0013     % spaces = obi.get_spaces()
0014     % space = obi.get_space(code)
0015     %
0016     % Logout:
0017     % obi.logout()
0018     
0019     
0020     properties
0021         pybis % Python Openbis object
0022     end
0023     
0024     
0025     methods
0026         
0027         %% Constructor method
0028         function obj = OpenBis(varargin)
0029             % OpenBis   Constructor method for class OpenBis
0030             % Creates the Python Openbis object and logs into the server
0031             % Optional positional input arguments:
0032             % url ... URL of the openBIS server (incl. port)
0033             % user ... user name for openBIS
0034             % pw ... password for openBIS
0035             % Usage:
0036             % obi = OpenBis() --> opens UI to enter URL, user name and password
0037             % obi = OpenBis('server_url', 'user_name', 'user_password')
0038             
0039             if nargin > 0
0040                 url = varargin{1};
0041                 user = varargin{2};
0042                 pw = varargin{3};
0043             else
0044                 [url, user, pw] = user_url_pw_inputdlg;
0045             end
0046             
0047             o = py.pybis.Openbis(url, pyargs('verify_certificates', 0));
0048             o.login(user, pw, pyargs('save_token', 1));
0049             obj.pybis = o;
0050         end
0051         
0052         function logout(obj)
0053             %logout
0054             % Log out of openBIS.
0055             % Usage:
0056             % obi.logout()
0057             %
0058             % After logout, the session token is no longer valid.
0059             
0060             obj.pybis.logout();
0061         end
0062         
0063         function tf= is_session_active(obj)
0064             %is_session_active
0065             % Check if the session token is still active. Returns true or false.
0066             % Usage:
0067             % true_false = obi.is_session_active()
0068             
0069             tf  = obj.pybis.is_session_active();
0070         end
0071         
0072         function token = token(obj)
0073             %token
0074             % Returns the current session token.
0075             % Usage:
0076             % token = obi.token()
0077             
0078             token  = char(obj.pybis.token);
0079         end
0080         
0081         %% Masterdata methods
0082         % this section defines Matlab equivalents of the following pyBIS methods:
0083         %   get_experiment_types
0084         %   get_sample_types
0085         %   get_material_types
0086         %   get_dataset_types
0087         %   get_terms
0088         %   get_tags
0089         
0090         function experiment_types = get_experiment_types(obj)
0091             %get_experiment_types
0092             % Return a table of all available experiment types.
0093             % Usage:
0094             % experiment_types = obi.get_experiment_types()
0095             
0096             experiment_types = obj.pybis.get_experiment_types();
0097             experiment_types = df_to_table(experiment_types.df);
0098         end
0099         
0100         function sample_types = get_sample_types(obj)
0101             %get_sample_types
0102             % Return table of all available sample types.
0103             % Usage:
0104             % sample_types = obi.get_sample_types()
0105             
0106             sample_types = obj.pybis.get_sample_types();
0107             sample_types = df_to_table(sample_types.df);
0108         end
0109         
0110         function material_types = get_material_types(obj)
0111             %get_material_types
0112             % Return table of all available material types.
0113             % Usage:
0114             % material_types = obi.get_material_types()
0115             
0116             material_types = obj.pybis.get_material_types();
0117             material_types = df_to_table(material_types.df);
0118         end
0119         
0120         function dataset_types = get_dataset_types(obj)
0121             %get_dataset_types
0122             % Return table of all available dataset types.
0123             % Usage:
0124             % dataset_types = obi.get_dataset_types()
0125             
0126             dataset_types = obj.pybis.get_dataset_types();
0127             dataset_types = df_to_table(dataset_types.df);
0128         end
0129         
0130         function terms = get_terms(obj)
0131             %get_terms
0132             % Return table of all available terms.
0133             % Usage:
0134             % terms = obi.get_terms()
0135             
0136             terms = obj.pybis.get_terms();
0137             terms = df_to_table(terms.df);
0138         end
0139         
0140         function tags = get_tags(obj)
0141             %get_tags
0142             % Return table of all available tags.
0143             % Usage:
0144             % tags = obi.get_tags()
0145             
0146             tags = obj.pybis.get_tags();
0147             tags = df_to_table(tags.df);
0148         end
0149         
0150         
0151         %% Space methods
0152         % this section defines Matlab equivalents of the following pyBIS methods:
0153         %   get_spaces
0154         %   get_space
0155         %   new_space
0156         %   space.delete
0157         
0158         function spaces = get_spaces(obj)
0159             %get_spaces
0160             % Return table of all available spaces.
0161             % Usage:
0162             % spaces = obi.get_spaces()
0163             
0164             spaces = obj.pybis.get_spaces();
0165             spaces = df_to_table(spaces.df);
0166         end
0167         
0168         function space = get_space(obj, code)
0169             %get_space
0170             % Fetch space with matching space code and return the space object.
0171             % An error is raised if a space with the code is not found on the server.
0172             % Required input arguments:
0173             % code ... space code
0174             % Usage:
0175             % space = obi.get_space('code')
0176             
0177             space = obj.pybis.get_space(code);
0178         end
0179         
0180         function space = new_space(obj, code, description)
0181             %new_space
0182             % Create a new space with code and description and return the space object
0183             % Required input arguments:
0184             % code ... Space code
0185             % description ... Space description
0186             % Usage:
0187             % space = obi.new_space('code', 'description')
0188             
0189             space = obj.pybis.new_space(pyargs('code',  code, ...
0190                 'description', description));
0191             space.save;
0192         end
0193         
0194         function delete_space(obj, code, reason)
0195             %delete_space
0196             % Delete space with code and provide a reason for deletion
0197             % Required input arguments:
0198             % code ... Space code
0199             % reason ... reason for deletion
0200             % Usage:
0201             % obi.delete_space('code', 'reason')
0202             
0203             space = obj.pybis.get_space(code);
0204             space.delete(reason);
0205         end
0206         
0207         
0208         %% Project methods
0209         % this section defines Matlab equivalents of the following pyBIS methods:
0210         %   get_projects
0211         %   get_project
0212         %   new_project
0213         %   project.delete
0214         
0215         function projects = get_projects(obj, space, code)
0216             %get_projects
0217             % Return table of matching projects.
0218             % Input arguments:
0219             % space ... space to fetch projects from
0220             % project ... fetch projects matching code
0221             % Usage:
0222             % projects = obi.get_projects('space', 'code')
0223             
0224             projects = obj.pybis.get_projects(pyargs('space',  space, 'code', code));
0225             projects = df_to_table(projects.df);
0226         end
0227         
0228         function project = get_project(obj, id)
0229             %get_project
0230             % Fetch project with matching project id and return the project object.
0231             % An error is raised if a project with the id is not found on the server.
0232             % Required input arguments:
0233             % id ... project id
0234             % Usage:
0235             % project = obi.get_project('id')
0236             
0237             project = obj.pybis.get_project(id);
0238         end
0239         
0240         function project = new_project(obj, space, code, description)
0241             %new_project
0242             % Create a new project in space with code and description
0243             % Return the project object
0244             % Input arguments
0245             % space ... Space code
0246             % code ... Project code / id
0247             % description ... Project description
0248             % Usage:
0249             % project = obi.new_project('space', 'code', 'description')
0250             
0251             space = obj.pybis.get_space(space);
0252             project = space.new_project(pyargs('code', code,  'description', description));
0253             project.save();
0254         end
0255         
0256         function delete_project(obj, code, reason)
0257             %delete_project
0258             % Delete project with code and provide a reason for deletion
0259             % Required input arguments:
0260             % code ... Project code
0261             % reason ... reason for deletion
0262             % Usage:
0263             % obi.delete_project('code', 'reason')
0264             
0265             project = obj.pybis.get_project(code);
0266             project.delete(reason);
0267         end
0268         
0269         
0270         %% Experiment methods
0271         % this section defines the following Matlab methods:
0272         %   get_experiments
0273         %   get_experiment
0274         %   new_experiment
0275         
0276         function experiments = get_experiments(obj, varargin)
0277             %get_experiments
0278             % Return table of matching experiments.
0279             % Optional input arguments:
0280             % space ... space to fetch experiments from
0281             % type ... fetch experiments of specific type
0282             % project ... project to fetch experiments from
0283             % Usage:
0284             % experiments = obi.get_experiments()
0285             % experiments = obi.get_experiments('space', 'SPACE')
0286             % experiments = obi.get_experiments('space', 'SPACE', 'type', 'UNKNOWN')
0287             
0288             space = '';
0289             type = '';
0290             project = '';
0291             
0292             p = inputParser;
0293             addRequired(p, 'obj');
0294             addParameter(p, 'space', space, @ischar);
0295             addParameter(p, 'type', type, @ischar);
0296             addParameter(p, 'project', project, @ischar);
0297             parse(p, obj, varargin{:});
0298             a = p.Results;
0299             
0300             experiments = obj.pybis.get_experiments(pyargs('space', a.space, 'type', a.type, 'project', a.project));
0301             experiments = df_to_table(experiments.df);
0302         end
0303         
0304         function experiment = get_experiment(obj, id)
0305             %get_experiment
0306             % Return experiment with identifier
0307             % ID can be either the Space + Object code (e.g. /SPACE/123456789) or the PermID (e.g. 20181002164551373-1234)
0308             % Usage:
0309             % exp = obi.get_experiment('/SPACE/PROJECT/EXP')
0310             % exp = obi.get_experiment('permID')
0311             
0312             experiment = obj.pybis.get_experiment(id);
0313         end
0314         
0315         function exp = new_experiment(obj, type, code, project)
0316             %new_experiment
0317             % Create a new experiment of specific type in a defined project
0318             % Required input arguments:
0319             % type ... new experiment type - see: obi.get_experiment_types()
0320             % code ... new experiment code
0321             % project ... project for new experiment ('/SPACE/Project')
0322             % Usage:
0323             % exp = obi.new_experiment('DEFAULT_EXPERIMENT', 'EXP1234', '/SPACE/Project')
0324             
0325             % determine type object
0326             t = obj.pybis.get_experiment_type(type);
0327             
0328             % determine project type
0329             p = obj.get_project(project);
0330             
0331             % instantiate a new experiment object
0332             exp = py.pybis.pybis.Experiment(obj.pybis, pyargs('type', t, 'code', code, 'project', p));
0333             
0334             % save experiment
0335             exp.save();
0336         end
0337         
0338         
0339         %% Object methods
0340         % this section defines following Matlab methods related to openBIS objects / samples:
0341         %   get_object
0342         %   get_objects
0343         %   new_object
0344         %   delete_object
0345         
0346         function objects = get_objects(obj, varargin)
0347             %get_objects
0348             % Return a table of objects matching specified criteria
0349             % Optional keyword arguments:
0350             % id ... object identifier ('SPACE/PROJECT/')
0351             % Usage:
0352             % objects = obi.get_objects()
0353             % objects = obi.get_objects('id', 'SPACE/')
0354             
0355             defaultId = '';
0356             
0357             p = inputParser;
0358             addRequired(p, 'obj');
0359             addParameter(p, 'id', defaultId, @ischar);
0360             parse(p, obj, varargin{:});
0361             a = p.Results;
0362            
0363             objects = obj.pybis.get_objects(a.id);
0364             objects = df_to_table(objects.df);
0365         end
0366         
0367         function object = get_object(obj, id)
0368             %get_object
0369             % Return object (sample) corresponding to the id
0370             % ID can be either the Space + Object code (e.g. /SPACE/123456789) or the PermID (e.g. 20181002164551373-1234)
0371             % An error is raised if an object with the id is not found on the server.
0372             % Required input arguments:
0373             % id ... object id
0374             % Usage:
0375             % object = obi.get_object('id')
0376             
0377             object = obj.pybis.get_object(id);
0378         end
0379         
0380         function object = new_object(obj, type, space, code)
0381             %new_object
0382             % Create a new object of type in space with code
0383             % Return the object
0384             % Input arguments
0385             % type ... object type
0386             % space ... Space code
0387             % code ... object code
0388             % Usage:
0389             % object = obi.new_object('type', 'space', 'code')
0390             
0391             object = obj.pybis.new_object(pyargs('type', type, 'space', space, 'code', code));
0392             object.save();
0393         end
0394         
0395         function object = delete_object(obj, object, reason)
0396             %delete_object
0397             % Delete object and provide a reason for deletion
0398             % Required input arguments:
0399             % object ... object returned by get_object / new_object methods
0400             % reason ... reason for deletion
0401             % Usage:
0402             % obi.delete_object(object, 'reason')
0403             
0404             object.delete(reason)
0405         end
0406 
0407         
0408         %% Dataset methods
0409         % this section defines following Matlab methods:
0410         %   get_datasets
0411         %   get_dataset
0412         %   get_dataset_files
0413         %   dataset_download
0414         %   new_dataset
0415         %   new_dataset_container
0416         
0417         function datasets = get_datasets(obj, varargin)
0418             %get_datasets
0419             % Return table of matching datasets.
0420             % Optional input arguments:
0421             % code ... dataset code / permId
0422             % type ... dataset type
0423             % experiment ... datasets in experiment
0424             % project ... datasets in project
0425             % tags ... datasets with tags
0426             % Usage:
0427             % datasets = obi.get_datasets()
0428             % datasets = obi.get_datasets('type', 'RAW_DATA')
0429             % datasets = obi.get_datasets('experiment', '/SPACE/PROJECT/EXPERIMENT')
0430             
0431             defaultCode = '';
0432             defaultType = '';
0433             defaultExp = '';
0434             defaultProj = '';
0435             defaultTags = '';
0436             
0437             p = inputParser;
0438             addRequired(p, 'obj');
0439             addParameter(p, 'code', defaultCode, @ischar);
0440             addParameter(p, 'type', defaultType, @ischar);
0441             addParameter(p, 'experiment', defaultExp, @ischar);
0442             addParameter(p, 'project', defaultProj, @ischar);
0443             addParameter(p, 'tags', defaultTags, @ischar);
0444             parse(p, obj, varargin{:});
0445             a = p.Results;
0446             
0447             datasets = obj.pybis.get_datasets(pyargs('code', a.code, 'type', a.type, 'experiment', a.experiment, ...
0448                 'project', a.project, 'tags', a.tags));
0449             datasets = df_to_table(datasets.df);
0450         end
0451         
0452         function dataset = get_dataset(obj, permid, varargin)
0453             %get_dataset
0454             % Get dataset with permId. An error is raised if a dataset with the id is not found on the server.
0455             % Input arguments:
0456             % permId ... dataset permId
0457             % Usage:
0458             % dataset = obi.get_dataset('permId')
0459             
0460             only_data = false;
0461             
0462             p = inputParser;
0463             addRequired(p, 'obj');
0464             addRequired(p, 'permid', @ischar);
0465             addOptional(p, 'only_data', only_data, @islogical);
0466             parse(p, obj, permid, varargin{:});
0467             a = p.Results;
0468             
0469 %             dataset = obj.pybis.get_dataset(pyargs('permid', a.permid, 'only_data', a.only_data));
0470             dataset = obj.pybis.get_dataset(a.permid);
0471         end
0472         
0473         
0474         function files = get_dataset_files(obj, dataset, varargin)
0475             %get_dataset_files
0476             % Get list of files in a dataset starting with start_folder.
0477             % Input arguments:
0478             % dataset ... dataset object returned by get_dataset
0479             % start_folder ... starting folder for files (default: '/')
0480             % Usage:
0481             % files = obi.get_dataset_files(dataset)
0482             
0483             start_folder = '/';
0484             
0485             p = inputParser;
0486             addRequired(p, 'obj');
0487             addRequired(p, 'dataset');
0488             addOptional(p, 'start_folder', start_folder, @ischar);
0489             parse(p, obj, dataset, varargin{:});
0490             a = p.Results;
0491             
0492             files = dataset.get_files(pyargs('start_folder', a.start_folder));
0493             files = df_to_table(files);
0494         end
0495         
0496         function path_to_file = dataset_download(obj, dataset, files, varargin)
0497             %dataset_download
0498             % Download files in a dataset
0499             % dataset ... dataset object returned by get_dataset
0500             % files ... cell array of files
0501             % destination ... folder to download to (default: data)
0502             % wait_until_finished ... wait or download in the background (default: true)
0503             % workers ... number of workers to use for download (default: 10)
0504             % Usage:
0505             % path_to_files = obi.dataset_download(dataset, {'file1', 'file2'})
0506             
0507             destination = 'data';
0508             wait_until_finished = true;
0509             workers = 10;
0510             
0511             p = inputParser;
0512             addRequired(p, 'obj');
0513             addRequired(p, 'dataset');
0514             addRequired(p, 'files', @iscellstr);
0515             addParameter(p, 'destination', destination, @ischar);
0516             addParameter(p, 'wait_until_finished', wait_until_finished, @islogical);
0517             addParameter(p, 'workers', workers, @isscalar);
0518             
0519             parse(p, obj, dataset, files, varargin{:});
0520             a = p.Results;
0521             
0522             dataset.download(pyargs('files', a.files, 'destination', a.destination, 'wait_until_finished', a.wait_until_finished, 'workers', int16(a.workers)));
0523             
0524             path_to_file = fullfile(a.destination, dataset.char, a.files);
0525             
0526         end
0527         
0528         function dataset = new_dataset(obj, type, object, file_list, varargin)
0529             %new_dataset
0530             % Create a new dataset with files
0531             % type ... dataset type
0532             % object ... object for dataset (experiment)
0533             % file_list ... list of files (cell string) to upload to new dataset
0534             % properties ... structure with dataset properties (meta-data)
0535             % Usage:
0536             % dataset = obi.new_dataset('RAW_DATA', '/SPACE/PROJECT/OBJECT', {'file1', 'file2'}, 'properties', props)
0537             
0538             properties = struct;
0539             
0540             p = inputParser;
0541             addRequired(p, 'obj');
0542             addRequired(p, 'type', @ischar);
0543             addRequired(p, 'object', @ischar);
0544             addRequired(p, 'file_list', @iscellstr);
0545             addParameter(p, 'properties', properties, @isstruct);
0546             
0547             parse(p, obj, type, object, file_list, varargin{:});
0548             a = p.Results;
0549             
0550             dataset = obj.pybis.new_dataset(pyargs('type', a.type, 'experiment', a.object, ...
0551                 'files', a.file_list, 'props', a.properties));
0552             dataset.save();
0553             
0554         end
0555         
0556         function dataset = new_dataset_container(obj, type, experiment, object)
0557             %new_dataset_container
0558             % Create a new dataset container
0559             % type ... dataset container type
0560             % experiment ... experiment for dataset container
0561             % object ... object for dataset container
0562             % Usage:
0563             % dataset = obi.new_dataset_container('type', 'RAW_DATA', 'experiment', 'MY_EXP', 'object', 'MY_SAMPLE')
0564             
0565             p = inputParser;
0566             addRequired(p, 'obj');
0567             addRequired(p, 'type', @ischar);
0568             addRequired(p, 'experiment', @ischar);
0569             addRequired(p, 'object', @ischar);
0570             
0571             parse(p, obj, type, experiment, object, file_list);
0572             a = p.Results;
0573             
0574             dataset = obj.pybis.new_dataset(pyargs('type', a.type, 'experiment', a.experiment, 'sample', a.object, 'kind', 'CONTAINER'));
0575             dataset.save();
0576             
0577         end
0578         
0579         
0580     end
0581     
0582 end
0583 
0584

Generated on Tue 06-Jul-2021 16:01:18 by m2html © 2005