Skip to content

Improve README wording and grammar #381

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
AbirajKangotra wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Improve README wording and grammar #381

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
114 changes: 41 additions & 73 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,104 +3,72 @@
![GitHub release](https://img.shields.io/github/release/INCF/neuroshapes.svg)

# Welcome to Neuroshapes
The goal of Neuroshapes is the development of open, use case driven and shared validatable data models (schemas, vocabularies) to enable the FAIR principles (Findable, Accessible, Interoperable and Reusable) for basic, computational and clinical neuroscience (meta)data.
The data models developed thus far entities for electrophysiology, neuron morphology, brain atlases, in vitro electrophysiology and computational modeling.
Future developments could include brain imaging, transcriptomic and clinical form data, as determined by community interests.
The goal of Neuroshapes is the development of open, use-case-driven and shared, validatable data models (schemas and vocabularies) to enable the FAIR principles (Findable, Accessible, Interoperable, and Reusable) for basic, computational, and clinical neuroscience (meta)data.

Table of contents:
The data models developed so far cover entities for electrophysiology, neuron morphology, brain atlases, in vitro electrophysiology, and computational modeling. Future developments could include brain imaging, transcriptomic, and clinical form data, as determined by community interests.

* [Goal](#goal)
* [Tutorials](#tutorials)
* [Adoption](#adoption)
* [Formats and standards](#formats-and-standards)
* [License](#License)
* [Testing the schemas](#testing-the-schemas)
* [Roadmap](#roadmap)
## Table of contents

- [Goal](#goal)
- [Tutorials](#tutorials)
- [Adoption](#adoption)
- [Formats and standards](#formats-and-standards)
- [Testing the schemas](#testing-the-schemas)
- [Roadmap](#roadmap)
- [License](#license)

# Goal

The main goal is to promote:
The main goal is to promote:

- The use of standard semantic markups and [linked data principles](https://www.w3.org/standards/semanticweb/data) as ways to structure metadata and related data. The [W3C RDF format](https://www.w3.org/RDF/) is leveraged, specifically its developer-friendly [JSON-LD](https://json-ld.org/) serialization. Adoption of linked data principles and JSON-LD eases federated access and discoverability of distributed neuroscience (meta)data over the web.

* the use of standard semantic markups and [linked data principles](https://www.w3.org/standards/semanticweb/data) as ways to structure metadata and related data: the [W3C RDF format](https://www.w3.org/RDF/) is leveraged, specifically its developer friendly [JSON-LD](https://json-ld.org/) serialization. The adoption of linked data principles and JSON-LD will ease federated access and discoverability of distributed neuroscience (meta)data over the web.
- The use of the [W3C SHACL (Shape Constraint Language)](https://www.w3.org/TR/shacl) recommendation as a rich metadata schema language that is formal, expressive, interoperable, machine-interpretable, and domain-agnostic. With SHACL, (meta)data quality can be enforced based on schemas and vocabularies rather than being fully encoded in procedural code. SHACL also provides key interoperability capabilities to ensure the evolution of standard data models and data longevity.

- The reuse of existing schemas and semantic markups (like [schema.org](http://schema.org/)) and existing ontologies and controlled vocabularies (including [NIFSTD – NIF Standard Ontologies](https://github.com/SciCrunch/NIF-Ontology)).

* the use of the [W3C SHACL (Shape Constraint Language)](https://www.w3.org/TR/shacl) recommendation as a rich metadata schema language which is formal and expressive; interoperable; machine interpretable; and domain agnostic. With SHACL, (meta)data quality can be enforced based on schemas and vocabularies (easily discoverable and searchable) rather than being fully encoded in procedural codes. SHACL also provides key interoperability capabities to ensure the evolution of standard data models and data longevity. It allows to incrementally build standard data models in term of semantics and sophistication.
- The use of the W3C PROV-O recommendation as a format to record (meta)data provenance. A SHACL version of W3C PROV-O is provided.



* the reuse of existing schemas and semantic markups (like [schema.org](http://schema.org/)) and existing ontologies and controlled vocabularies (including [NIFSTD - NIF Standard Ontologies](https://github.com/SciCrunch/NIF-Ontology))



* the use of W3C PROV-O recommendation as a format to record (meta)data provenance: a SHACL version of the W3C PROV-O is created.


Also, Neuroshapes aims at creating a community for an open and use case driven development of not only data models (schemas and vocabularies) and tools around them but also guidelines for FAIR neuroscience (meta)data.
Neuroshapes also aims to create a community for open, use-case-driven development of data models (schemas and vocabularies), tools around them, and guidelines for FAIR neuroscience (meta)data.

# Tutorials

A set of tutorials from the [Blue Brain Nexus Forge](https://nexus-forge.readthedocs.io/en/latest/#getting-started) project are available and use the schemas defined in Neuroshapes as data models to create and validate dataset as well as registering them in Blue Brain Nexus.

Try them in Binder [![Tutorials](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/BlueBrain/nexus-forge/v0.4.0?filepath=examples%2Fnotebooks%2Fgetting-started)
A set of tutorials from the [Blue Brain Nexus Forge](https://nexus-forge.readthedocs.io/en/latest/#getting-started) project are available and use the schemas defined in Neuroshapes as data models to create and validate datasets as well as register them in Blue Brain Nexus.

Try them in Binder:
https://mybinder.org/v2/gh/BlueBrain/nexus-forge/v0.4.0?filepath=examples%2Fnotebooks%2Fgetting-started

# Adoption

The following projects have adopted Neuroshapes:

* [Blue Brain Project](https://bluebrain.epfl.ch)
* [Human Brain Project](https://www.humanbrainproject.eu/en/)
* [Krembil Centre for Neuroinformatics](https://www.camh.ca/en/science-and-research/institutes-and-centres/krembil-centre-for-neuroinformatics)
- [Blue Brain Project](https://bluebrain.epfl.ch)
- [Human Brain Project](https://www.humanbrainproject.eu/en/)
- [Krembil Centre for Neuroinformatics](https://www.camh.ca/en/science-and-research/institutes-and-centres/krembil-centre-for-neuroinformatics)

# Formats and standards

All schemas in this repository conform to the [W3C SHACL recommendation](https://www.w3.org/TR/shacl) and are serialized using [JSON-LD](https://www.w3.org/TR/2014/REC-json-ld-20140116/).

## Testing shapes with examples

Two different tests are executed in the unittest. The first test validates that schemas conform with the SHACL specifications.
The second tests consist of having valid and invalid data samples that are going to be tested against the modeled shapes. These examples are placed in the `examples` directory and follow the directory structure of the shape they should be tested against.

```
|-- examples
| |-- neurosciencegraph
| | |-- datashapes
| | `-- commons
| | `-- list
| | |-- schema.json
| | `-- examples
| | |-- datashapes.json
| | `-- valid
| | | `-- recipe_ingredients_list.json
| | `-- invalid
| | `-- recipe_missing_ingredients.json
| `-- prov
`-- ...

```

Tests require python > 3.6, and pytest. To run them follow next:

# create your virtual environment and activate it
python3 -m venv env
source env/bin/activate
# install requirements
pip install pytest pyshacl
# run tests
pytest

To test a set of shapes inside shapes directory, an optional argument can be used:

pytest --testdir=shapes/neurosciencegraph/datashapes/atlas



## Testing the schemas

Two different tests are executed in the unit tests. The first test validates that schemas conform to the SHACL specifications. The second test uses valid and invalid data samples that are tested against the modeled shapes. These examples are placed in the `examples` directory and follow the directory structure of the shape they should be tested against.

Tests require Python > 3.6 and pytest. To run them:
python3 -m venv env
source env/bin/activate
pip install pytest pyshacl
pytest

To test a specific set of shapes:
pytest --testdir=shapes/neurosciencegraph/datashapes/atlas

# Roadmap

* Creation of an INCF/neuroshapes Special Interest Group
* INCF endorsement as a standard and best practice that support FAIR neuroscience data
* Extension of the current data model specifications
- Creation of an INCF/neuroshapes Special Interest Group
- INCF endorsement as a standard and best practice supporting FAIR neuroscience data
- Extension of the current data model specifications

# License
The license for all schemas and data is [CC-BY-4.0](https://github.com/INCF/neuroshapes/blob/master/LICENSE).

The license for all schemas and data is [CC-BY-4.0](https://github.com/INCF/neuroshapes/blob/master/LICENSE).