simphony / docs Goto Github PK

Matching the issue in wrapper development, the mentions of cuba.Class should be updated to cuba.Entity.

Requirements:

• The admin can review the subscriber list.
• A subscriber can unsubscribe via an 'unsubscribe' link.

Nice-to-have:

• The admin must approve the subscription request.
• The mailing list platform can maintain multiple mailing lists (e.g., for EMMO, SimPhony, SimPhony-workshop, etc.)

Possible platforms:

• Wordpress. We can set up a server and purchase a domain name for Simphony and other projects as well.
• LISTSERV

Apart from the jupyter tutorials, it would be nice to have some recordings explaining different concepts and functionalities

The current UML diagram in the detailed design section is out of date. It should be replaced with something similar to the following one:

@startuml
  allow_mixing
  actor User

  () pico

  rectangle SemanticLayer {

   class Cuds {
    Session session
    UUID uuid
    OntollogyEntity oclass
    --
    add() : Cuds
    get() : Cuds
    remove() : void
    update() : void
    iter() : Iterator<Cuds>
   }

   abstract class OntologyEntity {
     String name
     URIRef iri
     String tblname
     OntologyNamespace namespace
     Set direct_superclasses
     Set direct_subclasses
     Set superclasses
     Set subclasses
     String description
     --
     get_triples() : triple
     is_superclass_of() : bool
     is_subclass_of() : bool
   }
   class OntologyClass implements OntologyEntity {
       Dict attributes
       Dict own_attributes
   }

   class OntologyRelationship implements OntologyEntity {
     OntologyRelationship inverse
   }

   class OntologyAttribute implements OntologyEntity {
     URIRef datatype
     --
     convert_to_datatype() : Any
     convert_to_basic_type() : Any
   }

   class OntologyNamespace {
     --
     get_iri() : URIRef
     get_default_rel() : OntologyRelationship
     get() : OntologyEntity

   }

   class NamespaceRegistry {
     --
     get() : OntologyNamespace
     update_namespaces() : void
     from_iri() : OntologyEntity
     clear() : Graph
     store() : void
     load() : void
   }
  }

  rectangle InteroperabilityLayer {

   class Registry <dict> {
   }

   abstract class Session {
    Registry : registry
    --
    store() : void
    load() : Cuds
    sync() : void
   }

   class SomeWrapperSession implements Session {
    List added
    List updated
    List removed
    SyntacticLayer syntactic
    --  
   }
  }

  rectangle SyntacticLayer {
    class SyntacticLayer {
    }
  }

  database backend


  ' -----------------------
  ' ------ RELATIONS ------
  ' -----------------------
  User -up-> OntologyClass : interacts_with
  Cuds -left> OntologyClass : instance_of
  OntologyEntity -> OntologyNamespace : part_of
  OntologyNamespace -> NamespaceRegistry : contained_in
  OntologyClass -left> OntologyAttribute : has

  pico -> NamespaceRegistry : manages

  Cuds -> Session : has_a
  Session -> Registry : manages

  SomeWrapperSession -> SyntacticLayer : manages

  SyntacticLayer -> backend : acts_on

  OntologyRelationship -[hidden]> OntologyAttribute

  ' -----------------------
  ' -------- NOTES --------
  ' -----------------------


  @enduml

Present the most important concepts in a Frequently Asked Questions section to simplify understanding

[![Documentation Status](https://readthedocs.org/projects/simphony/badge/?version=latest)](https://simphony.readthedocs.io/en/latest/?badge=latest)

Similar to the SimLammps tutorial.

However, it would probably be better to fix the wrapper to modify data (not just generate an output branch) before.

It could be helpful to add an overview section that specifies all the features of SimPhoNy

To make sure that everything works fine when building the docs, onw has to start the build process manually.
It would be nice to know that automatically, before merge a PR.

• Update the link, badges and information in the Readme
• Remove GitLab's CI file
• Move issues

At this location, plus a few others at the same page:

Explain via a simple wrapper, how the functions work and what their purpose is

Explain details of the add method and best practices to avoid unexpected behaviour

From @yoavnash:
Specifically, it is better to initialize the cuds object all with the same session. Problematic scenario:

1. a is in the db (also in the db session)
2. b and c are in the core session
3. add b to a
4. add b to c
5. add c to wrapper
6. commit

Somehow the connection between a and b is not stored in the DB, probably because of mixing the session copies of the objects

It is still helpful to add them for futute versions of OSP core.

Create a simple example where the transport session is used to connect to a remote server.

There is some code available here.

In the yml configuration file for installing OWL ontologies, the keyword format is not specified, which is relevant if the file that is being installed has a specific format. For example:

...
format: turtle

Link to the docs page: https://simphony.readthedocs.io/en/latest/owl.html

Maybe add more information from ownCloud\MatInfo-future\products\SimPhoNy\osp-core-in-detail-urba

Add a code of conduct in the contribute section, explaining the behaviour and tone that should be followed

It's alpha2

The tutorials should probably be updated to include these as well

Maybe have a discussion on the perfect name name of the top-level class.

cuba.Class was awkward, because an instance would be a "Class" CUDS-object but should probably be an "Object" CUDS-object,

So I changed it back to what it was in the very beginning: cuba.Entity, which is also kinda awkward, because everything in the ontology is an entity, isn't it?

OWL uses owl:Thing as top-level Class.

See simphony/simphony-osp#231

Refer to slides from Session 3 of the SimDOME workshop for a graph of the process. A UML graph could also help

The ontology file has been renamed from ontology.simlammps.yml to simlammps.ontology.yml. The tutorial in the docs should reflect that.

The API uses remove because it is considered as a detach. For permanent erasing, we use delete.

Might be relevant to clarify this difference in the docs.

The functions used to query the ontology is provided in https://simphony.readthedocs.io/en/latest/jupyter/ontology-interface.html

There is no API reference for it to be found.

Add notes:

• Vector dimensions are fixed in the ontology
• If you need vectors of multiple dimension, multiple attributes need to be defined.
• They are experimental and will be replaced as soon as EMMO has decided on a way to represent vectors in RDF.

A simple an straight forward page with the contact details for the people involved

This is mentioned in the first tutorial, but no tutorial is available yet.

There is a typo (oclass instead of oclas) in file docs/docs/source/jupyter/sessions_and_vars.ipynb in line 13.

Ideally with a tutorial

I frequently asked myself in which sense osp-core is different to other (semantic) technologies out there. For example, neo4j + ontologies: here and here, RDF, etc.. It is a difficult topic to grasp and it takes quite some time to digest the small differences. In addition, it is hard to relate them to the big picture.

Those are discussions that pop up quite often, especially with externals or new team members (like me). It would be very beneficial for the whole project if we could refer to a documentation section where common similar applications are compared to osp-core (RDF, neo4j, ...). At the same time, we could point out the advantages of osp-core. Note that such a documentation should be "for dummies", i.e. we should keep it as easy as possible to follow.

A first step would be to gather all technologies that we consider "similar" and work out the differences. There was already a first try packed in an issue: simphony/simphony-osp#332

Define a proper section about the ontology.

In the ontology formats, split between YAML and OWL.

• YAML:
  • Does not require ALL_UPPER anymore.
  • Example for the attribute format in YAML.
  • None as a possible default value for a data attribute.
  • Explanation about the relationship characteristics
• OWL:
  • Add information about the format

The new syntax is pico uninstall all

OSP-core's README contains the recommended installation commands (via pip).

The docs should be updated to match, or refer to said page.