diff --git a/code/Contents.m b/code/Contents.m index a3befc43..370d52d2 100644 --- a/code/Contents.m +++ b/code/Contents.m @@ -1,5 +1,5 @@ % openMINDS Metadata Models -% Version 0.9.1 24-02-2024 +% Version 0.9.1.1 26-02-2024 % % Copyright (c) 2023, openMetadataInitiative -% ---------------------------------- +% ------------------------------------------ diff --git a/code/livescripts/crewMemberCollection.mlx b/code/livescripts/crewMemberCollection.mlx index 1a39a70b..47f48caa 100644 Binary files a/code/livescripts/crewMemberCollection.mlx and b/code/livescripts/crewMemberCollection.mlx differ diff --git a/docs/tutorials/crewMemberCollection.html b/docs/tutorials/crewMemberCollection.html index b6a7828d..20b21ce5 100644 --- a/docs/tutorials/crewMemberCollection.html +++ b/docs/tutorials/crewMemberCollection.html @@ -40,21 +40,21 @@ .rightPaneElement .textElement { padding-top: 2px; padding-left: 9px;} .S9 { margin: 10px 10px 9px 4px; padding: 0px; line-height: 21px; min-height: 0px; white-space: pre-wrap; color: rgb(33, 33, 33); font-family: Helvetica, Arial, sans-serif; font-style: normal; font-size: 14px; font-weight: 400; text-align: left; } .S10 { border-left: 1px solid rgb(217, 217, 217); border-right: 1px solid rgb(217, 217, 217); border-top: 1px solid rgb(217, 217, 217); border-bottom: 1px solid rgb(217, 217, 217); border-radius: 4px 4px 0px 0px; padding: 6px 45px 4px 13px; line-height: 18.004px; min-height: 0px; white-space: nowrap; color: rgb(33, 33, 33); font-family: Menlo, Monaco, Consolas, "Courier New", monospace; font-size: 14px; } -.S11 { border-left: 1px solid rgb(217, 217, 217); border-right: 1px solid rgb(217, 217, 217); border-top: 0px none rgb(33, 33, 33); border-bottom: 1px solid rgb(217, 217, 217); border-radius: 0px 0px 4px 4px; padding: 0px 45px 4px 13px; line-height: 18.004px; min-height: 0px; white-space: nowrap; color: rgb(33, 33, 33); font-family: Menlo, Monaco, Consolas, "Courier New", monospace; font-size: 14px; }

Metadata instances and collections

In this example we will create a metadata collection for the crew members of the "Heart of Gold" Spacecraft as described in the openMINDS getting started guide.
We start by importing a csv file with crew member information:
currentPath = fileparts(matlab.desktop.editor.getActiveFilename);
filePath = fullfile(currentPath, "data", "spacecraft_crew_members.csv");
crewMembers = readtable(filePath, "TextType", "String")
crewMembers = 4×5 table
 givenNamefamilyNamealternateNameemailmemberOf
1"Arthur""Dent"<missing>"arthur-dent@hitchhikers-guide.galaxy""Heart of Gold Spacecraft Crew"
2"Ford""Prefect"<missing>"ford-prefect@hitchhikers-guide.galaxy""Heart of Gold Spacecraft Crew"
3"Tricia Marie""McMillan""Trillian Astra""trillian-astra@hitchhikers-guide.galaxy""Heart of Gold Spacecraft Crew"
4"Zaphod""Beeblebrox"<missing>"zaphod-beeblebrox@hitchhikers-guide.galaxy""Heart of Gold Spacecraft Crew"

Create instances

Let us create a set of metadata instances from this table that represents the crew members. We assume that memberOf provides the full name of a consortium each person is affiliated to. Since members might be affiliated to the same consortium we assume further that the same full name means the same consortium. We can also assume that the email is unique for each person.
With these assumptions we will create:
We start by creating an empty metadata collection for storing metadata instances.
% Create an empty metadata collection
collection = openminds.Collection(...
"Name", "Crew Members", ...
"Description", "Crew members of the 'Heart of Gold' spacecraft")
collection =
Collection with properties: +.S11 { border-left: 1px solid rgb(217, 217, 217); border-right: 1px solid rgb(217, 217, 217); border-top: 0px none rgb(33, 33, 33); border-bottom: 1px solid rgb(217, 217, 217); border-radius: 0px 0px 4px 4px; padding: 0px 45px 4px 13px; line-height: 18.004px; min-height: 0px; white-space: nowrap; color: rgb(33, 33, 33); font-family: Menlo, Monaco, Consolas, "Courier New", monospace; font-size: 14px; }

Metadata instances and collections

In this example we will create a metadata collection for the crew members of the "Heart of Gold" Spacecraft as described in the openMINDS getting started guide.
We start by importing a csv file with crew member information:
currentPath = fileparts(matlab.desktop.editor.getActiveFilename);
filePath = fullfile(currentPath, "data", "spacecraft_crew_members.csv");
crewMembers = readtable(filePath, "TextType", "String")
crewMembers = 4×5 table
 givenNamefamilyNamealternateNameemailmemberOf
1"Arthur""Dent"<missing>"arthur-dent@hitchhikers-guide.galaxy""Heart of Gold Spacecraft Crew"
2"Ford""Prefect"<missing>"ford-prefect@hitchhikers-guide.galaxy""Heart of Gold Spacecraft Crew"
3"Tricia Marie""McMillan""Trillian Astra""trillian-astra@hitchhikers-guide.galaxy""Heart of Gold Spacecraft Crew"
4"Zaphod""Beeblebrox"<missing>"zaphod-beeblebrox@hitchhikers-guide.galaxy""Heart of Gold Spacecraft Crew"

Create instances

Let us create a set of metadata instances from this table that represents the crew members. We assume that memberOf provides the full name of a consortium each person is affiliated to. Since members might be affiliated to the same consortium we assume further that the same full name means the same consortium. We can also assume that the email is unique for each person.
With these assumptions we will create:
  • a metadata Collection for storing metadata instances
  • a unique set of Consortium instances based on the name given in the memberOf column
  • a ContactInformation instance based on the email column
  • a Person instance for each table row with:
  • the givenName, familyName, and alternateName (if available)
  • a link to the respective ContactInformation instance
  • a person-specific embedded Affiliation instance that links to the respective Consortium instance
We start by creating an empty metadata collection for storing metadata instances.
% Create an empty metadata collection
collection = openminds.Collection(...
"Name", "Crew Members", ...
"Description", "Crew members of the 'Heart of Gold' spacecraft")
collection =
Collection with properties: Name: "Crew Members" Description: "Crew members of the 'Heart of Gold' spacecraft" Nodes: dictionary with unset key and value types -
The collection will hold instances in a dictionary object of the Nodes property. Note: the Name and Description are optional and are currently not stored with the metadata instances.
We move on and start creating instances for the consortia:
% Define a utility function for creating instance ids:
createId = @(str) lower(sprintf('_:%s', replace(str, ' ', '-')));
 
% Extract the unique "memberOf" names to create dictionary
% with unique "Consortium" instances
uniqueConsortiumNames = unique(crewMembers.memberOf);
 
consortia = dictionary;
for consortiumName = uniqueConsortiumNames'
consortia(consortiumName) = openminds.core.Consortium(...
'id', createId(consortiumName), ...
'fullName', consortiumName );
end
 
disp(consortia)
dictionary (stringopenminds.core.actors.Consortium) with 1 entry: +
The collection will hold instances in a dictionary object of the Nodes property. Note: the Name and Description are optional and are currently not stored with the metadata instances.
We move on and start creating instances for the consortia:
% Define a utility function for creating instance ids:
createId = @(str) lower(sprintf('_:%s', replace(str, ' ', '-')));
 
% Extract the unique "memberOf" names to create dictionary
% with unique "Consortium" instances
uniqueConsortiumNames = unique(crewMembers.memberOf);
 
consortia = dictionary;
for consortiumName = uniqueConsortiumNames'
consortia(consortiumName) = openminds.core.Consortium(...
'id', createId(consortiumName), ...
'fullName', consortiumName );
end
 
disp(consortia)
dictionary (stringopenminds.core.actors.Consortium) with 1 entry: - "Heart of Gold Spacecraft Crew" ⟼ [Heart of Gold Spacecraft Crew] (Consortium)
We have now created a dictionary that holds the Consortium instances. Since all the persons in this example belongs to the same consortium, this dictionary only holds one instance.
We can also look at the Consortium instance in more detail:
disp(consortia("Heart of Gold Spacecraft Crew"))
Consortium (https://openminds.ebrains.eu/core/Consortium) with properties: + "Heart of Gold Spacecraft Crew" ⟼ [Heart of Gold Spacecraft Crew] (Consortium)
We have now created a dictionary that holds the Consortium instances. Since all the persons in this example belongs to the same consortium, this dictionary only holds one instance.
We can also look at the Consortium instance in more detail:
disp(consortia("Heart of Gold Spacecraft Crew"))
Consortium (https://openminds.ebrains.eu/core/Consortium) with properties: contactInformation: [None] (ContactInformation) fullName: "Heart of Gold Spacecraft Crew" homepage: "" shortName: "" - Required Properties: fullName
The Consortium instance has four properties, and we have filled out fullName. Whenever you create an openMINDS instance in MATLAB, you can either supply one or more name-value pairs when you create the instance (as we did above), or you can first create the instance and then assign values using dot-indexing on the instance object.
consortium = openminds.core.Consortium();
consortium.fullName = "Heart of Gold Spacecraft Crew"
consortium =
Consortium (https://openminds.ebrains.eu/core/Consortium) with properties: + Required Properties: fullName
The Consortium instance has four properties, and we have filled out fullName. Whenever you create an openMINDS instance in MATLAB, you can either supply one or more name-value pairs when you create the instance (as we did above), or you can first create the instance and then assign values using dot-indexing on the instance object.
consortium = openminds.core.Consortium();
consortium.fullName = "Heart of Gold Spacecraft Crew"
consortium =
Consortium (https://openminds.ebrains.eu/core/Consortium) with properties: contactInformation: [None] (ContactInformation) fullName: "Heart of Gold Spacecraft Crew" @@ -62,16 +62,16 @@ shortName: "" Required Properties: fullName -
When the instance is displayed, you will see all the properties are part of the instance type, and which of those are required (Note: at the moment of writing this guide, required properties are not enforced). The display should also give information about what types are expected for each of the property values. For example, the contactInformation property requires a ContactInformation instance (as indicated by the annotation in the brackets). If you want to learn more about the types as you explore the instances, you can always press the links in the instance display and they will take you to the openMINDS documentation page for that instance.
The consortium in this example does not have contact information, but we will move on and create ContactInformation types for each of the persons:
% Create a dictionary to hold "ContactInformation" instances
contacts = dictionary;
 
for email = crewMembers.email'
contacts(email) = openminds.core.ContactInformation(...
'id', createId(email), ...
'email', email );
end
disp(contacts)
dictionary (stringopenminds.core.actors.ContactInformation) with 4 entries: +
When the instance is displayed, you will see all the properties that are part of the instance type, and which of those are required (Note: at the moment of writing this guide, required properties are not enforced). The display should also give information about what types are expected for each of the property values. For example, the contactInformation property requires a ContactInformation instance (as indicated by the annotation in the brackets). If you want to learn more about the types as you explore the instances, you can always press the links in the instance display and they will take you to the openMINDS documentation page for that instance.
The consortium in this example does not have contact information, but we will move on and create ContactInformation types for each of the persons:
% Create a dictionary to hold "ContactInformation" instances
contacts = dictionary;
 
for email = crewMembers.email'
contacts(email) = openminds.core.ContactInformation(...
'id', createId(email), ...
'email', email );
end
disp(contacts)
dictionary (stringopenminds.core.actors.ContactInformation) with 4 entries: "arthur-dent@hitchhikers-guide.galaxy" ⟼ [arthur-dent@hitchhikers-guide.galaxy] (ContactInformation) "ford-prefect@hitchhikers-guide.galaxy" ⟼ [ford-prefect@hitchhikers-guide.galaxy] (ContactInformation) "trillian-astra@hitchhikers-guide.galaxy" ⟼ [trillian-astra@hitchhikers-guide.galaxy] (ContactInformation) - "zaphod-beeblebrox@hitchhikers-guide.galaxy" ⟼ [zaphod-beeblebrox@hitchhikers-guide.galaxy] (ContactInformation)
This gave us four ContactInformation instances. Finally we will create Person instances and attach the ContactInformation and Consortium instances:
% Extract data to create a list of "Person" instances where each "Person"
% instance will link to their respective "ContactInformation" instance and
% embed an "Affiliation" instance that links to the respective "Consortium" instance
persons = openminds.core.Person.empty;
 
for iRow = 1:height(crewMembers)
 
person = crewMembers(iRow,:);
fullName = person.givenName + " " + person.familyName;
persons(end+1) = openminds.core.Person( ...
'id', createId(fullName), ...
'givenName', person.givenName, ...
'familyName', person.familyName, ...
'alternateName', person.alternateName, ...
'contactInformation', contacts(person.email), ...
'affiliation', openminds.core.Affiliation('memberOf', consortia(person.memberOf) )); %#ok<SAGROW>
end

Add instances to collection and export collection

Now that we have all the instances, we can add them to the collection. It is sufficient to add the Person instances because the collection will autmatically detect linked and embedded instances and add them automatically to the Nodes property.
collection.add(persons)
disp(collection)
Collection with properties: + "zaphod-beeblebrox@hitchhikers-guide.galaxy" ⟼ [zaphod-beeblebrox@hitchhikers-guide.galaxy] (ContactInformation)
This gave us four ContactInformation instances. Finally we will create Person instances and attach the ContactInformation and Consortium instances:
% Extract data to create a list of "Person" instances where each "Person"
% instance will link to their respective "ContactInformation" instance and
% embed an "Affiliation" instance that links to the respective "Consortium" instance
persons = openminds.core.Person.empty;
 
for iRow = 1:height(crewMembers)
 
person = crewMembers(iRow,:);
fullName = person.givenName + " " + person.familyName;
persons(end+1) = openminds.core.Person( ...
'id', createId(fullName), ...
'givenName', person.givenName, ...
'familyName', person.familyName, ...
'alternateName', person.alternateName, ...
'contactInformation', contacts(person.email), ...
'affiliation', openminds.core.Affiliation('memberOf', consortia(person.memberOf) )); %#ok<SAGROW>
end

Add instances to collection and export collection

Now that we have all the instances, we can add them to the collection. It is sufficient to add the Person instances because the collection will automatically detect linked and embedded instances and add them automatically to the Nodes property.
collection.add(persons)
disp(collection)
Collection with properties: Name: "Crew Members" Description: "Crew members of the 'Heart of Gold' spacecraft" - Nodes: dictionary (string ⟼ cell) with 9 entries
As described above, we see that the Nodes hold 9 instances. We can look at the Nodes and we should expect to see 4 Person instances, 4 ContactInformation instances and 1 Consortium instance.
disp(collection.Nodes)
dictionary (stringcell) with 9 entries: + Nodes: dictionary (string ⟼ cell) with 9 entries
As described above, we see that the Nodes hold 9 instances. We can look at the Nodes and we should expect to see 4 Person instances, 4 ContactInformation instances and 1 Consortium instance.
disp(collection.Nodes)
dictionary (stringcell) with 9 entries: "_:arthur-dent" ⟼ {[Dent, Arthur] (Person)} "_:arthur-dent@hitchhikers-guide.galaxy" ⟼ {[arthur-dent@hitchhikers-guide.galaxy] (ContactInformation)} @@ -81,7 +81,7 @@ "_:tricia-marie-mcmillan" ⟼ {[McMillan, Tricia Marie] (Person)} "_:trillian-astra@hitchhikers-guide.galaxy" ⟼ {[trillian-astra@hitchhikers-guide.galaxy] (ContactInformation)} "_:zaphod-beeblebrox" ⟼ {[Beeblebrox, Zaphod] (Person)} - "_:zaphod-beeblebrox@hitchhikers-guide.galaxy" ⟼ {[zaphod-beeblebrox@hitchhikers-guide.galaxy] (ContactInformation)}
A note here: Since the collection holds a mix of different types, each type is inside a cell (as indicated by the curly brackets). In order to get an instance from the Nodes, we need to use curly bracket indexing:
person = collection.Nodes{"_:arthur-dent"}
person =
Person (https://openminds.ebrains.eu/core/Person) with properties: + "_:zaphod-beeblebrox@hitchhikers-guide.galaxy" ⟼ {[zaphod-beeblebrox@hitchhikers-guide.galaxy] (ContactInformation)}
A note here: Since the collection holds a mix of different types, each type is inside a cell (as indicated by the curly brackets). In order to get an instance from the Nodes, we need to use curly bracket indexing:
person = collection.Nodes{"_:arthur-dent"}
person =
Person (https://openminds.ebrains.eu/core/Person) with properties: affiliation: Heart of Gold Spacecraft Crew (Affiliation) alternateName: <missing> @@ -92,7 +92,7 @@ givenName: "Arthur" Required Properties: givenName -
Finally, we can save the collection
% Save the instances to the openMINDS userdata folder:
savePath = fullfile(userpath, "openMINDS_MATLAB", "demo", "crew_members.jsonld");
collection.save(savePath)
 
% Check out the saved metadata:
str = fileread(savePath);
disp(str)
{ +
Finally, we can save the collection
% Save the instances to the openMINDS userdata folder:
savePath = fullfile(userpath, "openMINDS_MATLAB", "demo", "crew_members.jsonld");
collection.save(savePath)
 
% Check out the saved metadata:
str = fileread(savePath);
disp(str)
{ "@context": { "@vocab": "https://openminds.ebrains.eu/vocab/" }, @@ -222,9 +222,9 @@ % column % * a |ContactInformation| instance based on the |email| column % * a |Person| instance for each table row with: -% * the |givenName|, |familyName|, and |alternateName| (if available) -% * a link to the respective |ContactInformation| instance -% * a person-specific embedded |Affiliation| instance that links to the respective +% * the |givenName|, |familyName|, and |alternateName| (if available) +% * a link to the respective |ContactInformation| instance +% * a person-specific embedded |Affiliation| instance that links to the respective % |Consortium| instance %% % We start by creating an empty metadata collection for storing metadata instances. @@ -273,14 +273,14 @@ consortium = openminds.core.Consortium(); consortium.fullName = "Heart of Gold Spacecraft Crew" %% -% When the instance is displayed, you will see all the properties are part of -% the instance type, and which of those are required (Note: at the moment of writing -% this guide, required properties are not enforced). The display should also give -% information about what types are expected for each of the property values. For -% example, the |contactInformation| property requires a |ContactInformation| instance -% (as indicated by the annotation in the brackets). If you want to learn more -% about the types as you explore the instances, you can always press the links -% in the instance display and they will take you to the openMINDS documentation +% When the instance is displayed, you will see all the properties that are part +% of the instance type, and which of those are required (Note: at the moment of +% writing this guide, required properties are not enforced). The display should +% also give information about what types are expected for each of the property +% values. For example, the |contactInformation| property requires a |ContactInformation| +% instance (as indicated by the annotation in the brackets). If you want to learn +% more about the types as you explore the instances, you can always press the +% links in the instance display and they will take you to the openMINDS documentation % page for that instance. % % The consortium in this example does not have contact information, but we will @@ -319,7 +319,7 @@ end %% Add instances to collection and export collection % Now that we have all the instances, we can add them to the |collection|. It -% is sufficient to add the |Person| instances because the collection will autmatically +% is sufficient to add the |Person| instances because the collection will automatically % detect linked and embedded instances and add them automatically to the |Nodes| % property. diff --git a/docs/tutorials/crewMemberCollection.md b/docs/tutorials/crewMemberCollection.md index ce37bb86..4a7b1607 100644 --- a/docs/tutorials/crewMemberCollection.md +++ b/docs/tutorials/crewMemberCollection.md @@ -113,7 +113,7 @@ consortium = Required Properties: fullName ``` -When the instance is displayed, you will see all the properties are part of the instance type, and which of those are required (Note: at the moment of writing this guide, required properties are not enforced). The display should also give information about what types are expected for each of the property values. For example, the contactInformation property requires a ContactInformation instance (as indicated by the annotation in the brackets). If you want to learn more about the types as you explore the instances, you can always press the links in the instance display and they will take you to the openMINDS documentation page for that instance. +When the instance is displayed, you will see all the properties that are part of the instance type, and which of those are required (Note: at the moment of writing this guide, required properties are not enforced). The display should also give information about what types are expected for each of the property values. For example, the contactInformation property requires a ContactInformation instance (as indicated by the annotation in the brackets). If you want to learn more about the types as you explore the instances, you can always press the links in the instance display and they will take you to the openMINDS documentation page for that instance. The consortium in this example does not have contact information, but we will move on and create ContactInformation types for each of the persons: @@ -162,7 +162,7 @@ end ``` # Add instances to collection and export collection -Now that we have all the instances, we can add them to the collection. It is sufficient to add the Person instances because the collection will autmatically detect linked and embedded instances and add them automatically to the Nodes property. +Now that we have all the instances, we can add them to the collection. It is sufficient to add the Person instances because the collection will automatically detect linked and embedded instances and add them automatically to the Nodes property. ```matlab collection.add(persons) diff --git a/openMINDS_MATLAB.pkg.prj b/openMINDS_MATLAB.pkg.prj index 8b18b563..85285cdd 100644 --- a/openMINDS_MATLAB.pkg.prj +++ b/openMINDS_MATLAB.pkg.prj @@ -1,13 +1,13 @@ - + openMINDS Metadata Models Eivind Hennestad eivihe@uio.no A MATLAB toolbox to create metadata instances using the openMINDS metadata models MATLAB package for the openMINDS metadata models. The package contains all the latest openMINDS schemas as MATLAB classes in addition to schema base classes and utility methods - ${PROJECT_ROOT}/img/light_openMINDS-MATLAB-logo.png - 0.9.0 + ${PROJECT_ROOT}/img/light_openMINDS-MATLAB-logo_toolbox.png + 0.9.1.1 ${PROJECT_ROOT}/openMINDS Metadata Models.mltbx @@ -111,20 +111,22 @@ ${PROJECT_ROOT}/code/Contents.m ${PROJECT_ROOT}/code/gettingStarted.mlx ${PROJECT_ROOT}/code/internal + ${PROJECT_ROOT}/code/livescripts ${PROJECT_ROOT}/code/mixedtypes ${PROJECT_ROOT}/code/schemas ${PROJECT_ROOT}/code/selectOpenMindsVersion.m ${PROJECT_ROOT}/code/setup.m + ${PROJECT_ROOT}/code/startup.m - /Users/Eivind/Code/MATLAB/Github-Ehennestad/openMINDS_MATLAB/openMINDS Metadata Models.mltbx + /Users/eivihe/Code/MATLAB/Repositories/openMINDS_MATLAB/openMINDS Metadata Models.mltbx - /Applications/MATLAB_R2022b.app + /Applications/MATLAB_R2023b.app @@ -136,9 +138,9 @@ false false false - 13.1 - false - true + 13.5 + true + false maci64 true