diff --git a/docs/assets/images/Fig10.png b/docs/assets/images/Fig10.png new file mode 100644 index 0000000000..8eeaab8d16 Binary files /dev/null and b/docs/assets/images/Fig10.png differ diff --git a/docs/assets/images/Fig11.png b/docs/assets/images/Fig11.png new file mode 100644 index 0000000000..751adb483b Binary files /dev/null and b/docs/assets/images/Fig11.png differ diff --git a/docs/assets/images/Fig12.png b/docs/assets/images/Fig12.png new file mode 100644 index 0000000000..7c994b2126 Binary files /dev/null and b/docs/assets/images/Fig12.png differ diff --git a/docs/assets/images/Fig13.png b/docs/assets/images/Fig13.png new file mode 100644 index 0000000000..49df232e9a Binary files /dev/null and b/docs/assets/images/Fig13.png differ diff --git a/docs/assets/images/Fig14.png b/docs/assets/images/Fig14.png new file mode 100644 index 0000000000..ace841cc09 Binary files /dev/null and b/docs/assets/images/Fig14.png differ diff --git a/docs/assets/images/Fig15.png b/docs/assets/images/Fig15.png new file mode 100644 index 0000000000..4089a633ca Binary files /dev/null and b/docs/assets/images/Fig15.png differ diff --git a/docs/assets/images/Fig16.png b/docs/assets/images/Fig16.png new file mode 100644 index 0000000000..89faba31c8 Binary files /dev/null and b/docs/assets/images/Fig16.png differ diff --git a/docs/assets/images/Fig17.png b/docs/assets/images/Fig17.png new file mode 100644 index 0000000000..7fa9d0631a Binary files /dev/null and b/docs/assets/images/Fig17.png differ diff --git a/docs/assets/images/Fig18.png b/docs/assets/images/Fig18.png new file mode 100644 index 0000000000..beafcc7ccb Binary files /dev/null and b/docs/assets/images/Fig18.png differ diff --git a/docs/assets/images/Fig19.png b/docs/assets/images/Fig19.png new file mode 100644 index 0000000000..293e35bd80 Binary files /dev/null and b/docs/assets/images/Fig19.png differ diff --git a/docs/assets/images/Fig2.png b/docs/assets/images/Fig2.png new file mode 100644 index 0000000000..429926d8c6 Binary files /dev/null and b/docs/assets/images/Fig2.png differ diff --git a/docs/assets/images/Fig20.png b/docs/assets/images/Fig20.png new file mode 100644 index 0000000000..aa513978b6 Binary files /dev/null and b/docs/assets/images/Fig20.png differ diff --git a/docs/assets/images/Fig21.png b/docs/assets/images/Fig21.png new file mode 100644 index 0000000000..ce50371897 Binary files /dev/null and b/docs/assets/images/Fig21.png differ diff --git a/docs/assets/images/Fig22.png b/docs/assets/images/Fig22.png new file mode 100644 index 0000000000..129bd16328 Binary files /dev/null and b/docs/assets/images/Fig22.png differ diff --git a/docs/assets/images/Fig23.png b/docs/assets/images/Fig23.png new file mode 100644 index 0000000000..e1df40f948 Binary files /dev/null and b/docs/assets/images/Fig23.png differ diff --git a/docs/assets/images/Fig24.png b/docs/assets/images/Fig24.png new file mode 100644 index 0000000000..2a64af12ab Binary files /dev/null and b/docs/assets/images/Fig24.png differ diff --git a/docs/assets/images/Fig25.png b/docs/assets/images/Fig25.png new file mode 100644 index 0000000000..c302c754a1 Binary files /dev/null and b/docs/assets/images/Fig25.png differ diff --git a/docs/assets/images/Fig26.png b/docs/assets/images/Fig26.png new file mode 100644 index 0000000000..72dbd78f32 Binary files /dev/null and b/docs/assets/images/Fig26.png differ diff --git a/docs/assets/images/Fig27.png b/docs/assets/images/Fig27.png new file mode 100644 index 0000000000..cf12efa0ca Binary files /dev/null and b/docs/assets/images/Fig27.png differ diff --git a/docs/assets/images/Fig28.png b/docs/assets/images/Fig28.png new file mode 100644 index 0000000000..2735ea023f Binary files /dev/null and b/docs/assets/images/Fig28.png differ diff --git a/docs/assets/images/Fig29.png b/docs/assets/images/Fig29.png new file mode 100644 index 0000000000..d2171d5107 Binary files /dev/null and b/docs/assets/images/Fig29.png differ diff --git a/docs/assets/images/Fig3.png b/docs/assets/images/Fig3.png new file mode 100644 index 0000000000..3f7641fe2c Binary files /dev/null and b/docs/assets/images/Fig3.png differ diff --git a/docs/assets/images/Fig30.png b/docs/assets/images/Fig30.png new file mode 100644 index 0000000000..e6de43b6c5 Binary files /dev/null and b/docs/assets/images/Fig30.png differ diff --git a/docs/assets/images/Fig31.png b/docs/assets/images/Fig31.png new file mode 100644 index 0000000000..24bb1fdd37 Binary files /dev/null and b/docs/assets/images/Fig31.png differ diff --git a/docs/assets/images/Fig32.png b/docs/assets/images/Fig32.png new file mode 100644 index 0000000000..0127068ab3 Binary files /dev/null and b/docs/assets/images/Fig32.png differ diff --git a/docs/assets/images/Fig33.png b/docs/assets/images/Fig33.png new file mode 100644 index 0000000000..7eb04b193f Binary files /dev/null and b/docs/assets/images/Fig33.png differ diff --git a/docs/assets/images/Fig34.png b/docs/assets/images/Fig34.png new file mode 100644 index 0000000000..57a15bf145 Binary files /dev/null and b/docs/assets/images/Fig34.png differ diff --git a/docs/assets/images/Fig35.png b/docs/assets/images/Fig35.png new file mode 100644 index 0000000000..66c638acb1 Binary files /dev/null and b/docs/assets/images/Fig35.png differ diff --git a/docs/assets/images/Fig36.png b/docs/assets/images/Fig36.png new file mode 100644 index 0000000000..4c4e2c4703 Binary files /dev/null and b/docs/assets/images/Fig36.png differ diff --git a/docs/assets/images/Fig37.png b/docs/assets/images/Fig37.png new file mode 100644 index 0000000000..3e520d307b Binary files /dev/null and b/docs/assets/images/Fig37.png differ diff --git a/docs/assets/images/Fig38.png b/docs/assets/images/Fig38.png new file mode 100644 index 0000000000..b19838c557 Binary files /dev/null and b/docs/assets/images/Fig38.png differ diff --git a/docs/assets/images/Fig39.png b/docs/assets/images/Fig39.png new file mode 100644 index 0000000000..2f8494591b Binary files /dev/null and b/docs/assets/images/Fig39.png differ diff --git a/docs/assets/images/Fig4.png b/docs/assets/images/Fig4.png new file mode 100644 index 0000000000..4b0dc908de Binary files /dev/null and b/docs/assets/images/Fig4.png differ diff --git a/docs/assets/images/Fig40.png b/docs/assets/images/Fig40.png new file mode 100644 index 0000000000..d534c06cb1 Binary files /dev/null and b/docs/assets/images/Fig40.png differ diff --git a/docs/assets/images/Fig41.png b/docs/assets/images/Fig41.png new file mode 100644 index 0000000000..aac82663d0 Binary files /dev/null and b/docs/assets/images/Fig41.png differ diff --git a/docs/assets/images/Fig5.png b/docs/assets/images/Fig5.png new file mode 100644 index 0000000000..94eee99708 Binary files /dev/null and b/docs/assets/images/Fig5.png differ diff --git a/docs/assets/images/Fig6.png b/docs/assets/images/Fig6.png new file mode 100644 index 0000000000..2c0c171c42 Binary files /dev/null and b/docs/assets/images/Fig6.png differ diff --git a/docs/assets/images/Fig7.png b/docs/assets/images/Fig7.png new file mode 100644 index 0000000000..231bc2a070 Binary files /dev/null and b/docs/assets/images/Fig7.png differ diff --git a/docs/assets/images/Fig8.png b/docs/assets/images/Fig8.png new file mode 100644 index 0000000000..0fab627c5f Binary files /dev/null and b/docs/assets/images/Fig8.png differ diff --git a/docs/assets/images/Fig9.png b/docs/assets/images/Fig9.png new file mode 100644 index 0000000000..7fa6551a03 Binary files /dev/null and b/docs/assets/images/Fig9.png differ diff --git a/docs/user-guide/project.md b/docs/user-guide/project.md index f386893780..0e046d35ca 100644 --- a/docs/user-guide/project.md +++ b/docs/user-guide/project.md @@ -6,11 +6,11 @@ Once you are [logged in](/user-guide/#login), the dashboard displays the list of ![Project list and project menu](../assets/images/dashboard.png)* - By clicking on the project name, you get access to the full project information.* -System administrator can create your new research project. Essential information are required such as the project name, a short project description and institution information. +A system administrator can create a new research project. This currently requires essential information such as the project name, a shortcode and a shortname (both provided by DaSCH). A short project description is optional, but highly recommended. ![Create a new project](../assets/images/project-create-new.png)
*Form to create a new project.*
-As project administrator or system administrator, you can define your project, add your team members, create permission groups and as most important, define your data model (ontology) and the lists of your project. +As project administrator or system administrator, you can define your project, add your team members, create permission groups and - most important - define your data model (ontology) and the lists of your project. ![Project management available functionalities](../assets/images/project-info.png)* - Project management functionalities; e.g. Incunabula project. Project information page is displayed without restricted content, the other functionalities are reserved for project admin and system admin.* @@ -18,7 +18,7 @@ As project administrator or system administrator, you can define your project, a ## Collaboration -As system admin, you can add users as project member and define their permissions roles: *Who is able to edit or to see data in the project?* Data includes the research sources and their metadata. [Permissions](/user-guide/project/#permission-groups) can be set for the entire project or for single metadata fields. +As a system administrator, you can add users as project members and define their permissions roles: *Who is able to edit or to see your project data?* Data includes the research sources and their metadata. [Permissions](/user-guide/project/#permission-groups) can be set for the entire project or for single metadata fields. A user menu with different actions is accessible for each member of the project (link to the right side of the user line). The admin can appoint another user as project admin (or remove this permission), edit user's information, change user's password if forgotten, and remove a user. @@ -28,120 +28,218 @@ A user menu with different actions is accessible for each member of the project --- -## Permission groups -⚠ *NOT YET IMPLEMENTED* +## Data model -Project admin can create one or several permission groups in their project to set specific permissions on data to a user group. +The definition of the data model (*ontology*) is the most important step. The data model is indispensable for structuring your data. Our platform provides a tool for an easy creation of one or more project data models. First, you have to know which data and sources you want to work with. The data model can be flexible and customizable. ---- +The question which you have to answer before you create your data model is **according to which criteria do you organize your data**? In this respect it may be useful to ask yourself: -## Data model +- *How are your data organized?* +- *What are the goals you want to achieve, which research questions do you want to answer?* -The most important step in the project is the definition of the data model. DSP-APP will provide a tool for easy creation of data models. First, you have to know which data and sources you want to work with. The data model can be flexible and customizable. With DSP-APP, you can comply with the FAIR data standard, but compliance is not required to analyze your data. +As soon as you have come to a conclusion concerning the structure of your data, you're all set to create your data model. -The questions to answer in creating your data model: -- *What kind of data do I have in my project?* -- *What are the sources and what are their metadata?* +### Create your data model -**For example:** You have interviewed 20 people. During these interviews that you recorded, you talked about photographs. Among all the data collected during the project, the most important are: +**Go to *Data model* and click *New data model*** -- audio-files of the interview -- transcribed text of conversations (or transcribe the files within the web application) -- photographs -- data about the person you interviewed -- location where the photograph was taken +Go to your project, select the tab `Data model` (step 1) and click the button `New data model` (step 2) as shown below: +![Data model.](../assets/images/Fig2.png) -Diagram 1 shows the relationships of the data by resource classes from these experiences. +By clicking `New data model`, a dialog box opens: +![Define new data model.](../assets/images/Fig3.png) -![Relationship of the data by resource classes](../assets/images/diagram-data-model.png)*Relationship of the data by resource classes* -### Create your data model +**Create data model** -Go to your project, select the tab `Data model` and click on button `New data model` or `Create your first data model` (in case of a brand new project). This will open a form in a dialog box where you have to set a unique name and a label. Optional you can also add a short description of form of a comment. +Now you have to set a unique name (*please consider the NOTE*) and you can add a comment. Push the button `Create` to create your data model. -> **_NOTE:_** There are some rules for the unique name: +> **_NOTE:_***There are some rules for the unique name:* > -> - must be at least 3 characters long -> - shouldn't begin with a number -> - shouldn't begin with the letter v and a number -> - spaces or special characters are not allowed -> - may not contain these reserved words: -> - knora -> - ontology -> - salsah -> - shared -> - simple -> - standoff -> - the unique name can't be changed afterwards - -The label is a combination of project's shortname and the unique name. You can replace with any other string. - -![Data model editor | Step 1: Start by creating a new data model.](../assets/images/data-model-create.png)*Data model editor | Step 1: Start by creating a new data model.* +> - *must be at least 3 characters long* +> - *shouldn't start with a number* +> - *shouldn't start with the letter v and a number* +> - *spaces or special characters are not allowed* +> - *may not contain these reserved terms:* +> - *knora* +> - *ontology* +> - *salsah* +> - *shared* +> - *simple* +> - *standoff* +> - *the unique name can't be changed afterwards!* + +*The label is a combination of the project's shortname and the unique name. You can replace it with any other string.* +![Define the name of your data model.](../assets/images/Fig4.png) + +After the creation of your data model, your page should look like this: +![Layout after the creation of data model.](../assets/images/Fig5.png) --- -### Create the resource CLASSES +### Create resource CLASSES + +You can then create a resource class by clicking the button `+ Create new class`: +![Create new resource class.](../assets/images/Fig6.png) -In the data model editor, you create your resource classes by selecting a default representation type from a predefined list on the right-hand side. +By clicking `+ Create new class`, a small window pops up with six basic types to choose from: +![Choose the type of your resource class.](../assets/images/Fig7.png) -Click on `+ Create new class` and select a representation type for your resource class. +Which type you choose depends on the data type which you need to describe. Let's assume you have pdf-documents of books and they have a number of pages. To describe this in an ontology, you create a class as `Document` by clicking on `Document`. A dialog box pops up which looks like this: +![Create a class with type *Document*.](../assets/images/Fig8.png) -![Data model editor | Step 2: Create all your main resource classes by selecting a predefined representation type; e.g. for a taped interview, select the representation type "Audio / Sound / Interview".](../assets/images/data-model-class-select-representation.png)*Data model editor | Step 2: Create all your main resource classes by selecting a predefined representation type; e.g. for a taped interview, select the representation type "Audio / Sound / Interview".* +For the label you could write *Book*, and you should add a preferably meaningful comment in at least one of the predefined languages English (en), German (de), French (fr) or Italian (it). Then click the `Submit` button: +![Give a label and a description.](../assets/images/Fig9.png) -In our example with the interview and the photographs, you drag and drop the following main resource classes from the list on the right-hand side: -- Audio / Sound / Interview -- Transcript -- Image / Photograph / Postcard -- Person -- Location / Place +Now you have created your first class *Book*, as seen below: +![Layout after the creation of the resource class.](../assets/images/Fig10.png) --- -### Select or create the PROPERTIES for each resource class +### Add PROPERTIES to a resource class - +Now you can add properties to your class. Your pdf of a book has a number of pages. Hence, it may be useful to define the number of pages as one of the properties of your class *Book*. Click on `+ Add Property` in the *Book* box: +![Create a property.](../assets/images/Fig11.png) -There are two possibilites to add properties to a resource class: +Theoretically, you have two options now. If you defined properties before, you may simply add them here (second option in the following image). If you just start adding properties, you have to choose `Create new from type`. +![Two options for defining properties.](../assets/images/Fig12.png) -#### Create new property by selecting from list of default property types +By hovering over `Create new from type`, a new dialog box appears: +![Create new property.](../assets/images/Fig13.png) -![Data model editor | Step 3: Add properties to your resource class by selecting from list of default property types.](../assets/images/data-model-property-select-type.png)*Data model editor | Step 3: Add properties to your resource class by selecting from list of default property types.* +You can choose from a selection of the following basic types with various subtypes: +- Text (*Short*, *Paragraph*, *Rich Text*) +- List (*Dropdown*) +- Boolean (*Yes/No* selection; checkbox) +- Date / Time (*Date*, *Timestamp*, *Time sequence*) +- Number (*Integer*, *Decimal*) +- Link / Relation (*Resource Class*, *External URL*) +- Location (*Place*; a [geonames-identifier](https://www.geonames.org/)) +- Shape (*color*) -#### Select from list of existing properties +Since in our example you want to add a property for the number of pages of your book, you choose `Number`. Now you will see that you can either choose the type `Decimal` or `Integer` for your property. +![Property types.](../assets/images/Fig14.png) -If you have already created some properties in another resource classes or in the property section you can select one of them to add it to the resource class. This way you have to define — for example — a "Title" property only once. +Page numbers have no decimal places, thus you will selecet `Integer` as type for your property. The following window pops up: +![Property of integer type.](../assets/images/Fig15.png) -![Data model editor | Step 3: Add properties to your resource class by selecting from list of already existing properties](../assets/images/data-model-property-select-existing.png)*Data model editor | Step 3: Add properties to your resource class by selecting from list of already existing properties* +In the field *Property label* add for example *Number of pages*, in the comment section you should add a meaningful explanation. It might also make sense to toggle `Required field?` since every PDF Document consists of a number of pages. If you toggle it, the number of pages MUST be given if you add data to the class *Book* - it would then be a required field, not an optional one and data could only be saved if you add the number of pages. +![Label and description of property.](../assets/images/Fig16.png) -In both cases it will open the property form where you have to define a label and optional a comment. If you have selected an existing property, you can also change the label and comment. Be careful in this case, because it can have an effect on other resource classes that use the same property! +If you want to define a property which can have more than one value, you should tick `Multiple values?`. For the number of pages of a book this does not make sense, but in the case you want to define a property describing which people are mentioned in your *Book*, the option multiple values is likely to be needed. -The property type can't be changed here. Depending on the property type you have to set additional attributes, e.g. in a resource link property you have to select a resource class to which the property will point to. Similar in case of a list property where you have to select the corresponding list. In both cases a the linked resource class or the list should already exist. +Now you should see the new property in the box as seen below: +![Layout after the creation of the property.](../assets/images/Fig17.png) -![Data model editor | Step 4: Define property's label and comment and set the cardinality corresponding to the resource class.](../assets/images/data-model-property-create.png)*Data model editor | Step 4: Define property's label and comment and set the cardinality corresponding to the resource class.* +### Define Lists +One of the possible property types to choose from is *List*. Lists are very useful if you want to use controlled vocabulary to describe something. Typical examples are keywords. In your book example it may be useful to define a property which describes to which category of literature your pdf of a book belongs. **Before** you can add a property of type *List* to your data model, you have to define this list. For the definiton of a list you have to change to the `Lists` tab: +![List tab.](../assets/images/Fig34.png) -For each property in a resource class you can define some rules. For example you can define if one of the property can have `multiple` values or if a property is a mandatory (`requiered`) field. +Click `Create your first list`. If there is already a list defined, click `New list`. A new window pops up where you have to enter a name for your list (`List label`) and a short description, then click `Create`. +![Create new list.](../assets/images/Fig35.png) -After adding more than one property to a resource class you can change the displayed order by drag'n'drop the properties in the list. +As soon as the list is created you can continue with the definition of your data model. You can define the individual list items later. How to do this will be explained below. We first focus on the definition of a list property in the data model. Currently there is only one option for displaying a property of type *List*, namely *Dropdown*. It is capable of displaying flat as well as hierarchical lists. +![Define a property of type *List*.](../assets/images/Fig40.png) - +The resource class *Transcript* has the resource classes *Audio-Interview*, *Photograph* and *Person* as linked properties. Furthermore, the resource class *Photograph* has the class *Location* as linked property. In such a way we reflect the central position of *Transcript* in our data model.