ResearchObject module

class rohub.ResearchObject.ResearchObject.ResearchObject(title=None, research_areas=None, description=None, access_mode=None, ros_type=None, use_template=False, owner=None, editors=None, readers=None, creation_mode=None, identifier=None, post_request=True)

Bases: object

Class Representation of Rohub’s research object.

Note

editable attributes:
- title
- research_areas
- description
- access_mode
- ros_type
- template
- owner
- editors
- readers
- creation_mode
read-only attributes:
- identifier
- shared_link
- status
- created
- creator
- modificator
- modified
- importer
- rating
- number_of_ratings
- number_of_likes
- number_of_dislikes
- quality
- size
- doi
- api_link
- created_by
- metadata
- contributors_credits
- authors_credits
- number_of_all_aggregates
- number_of_resources
- original_created_on
- parent_ro
- contributed_by
- number_of_views
- number_of_forks
- authored_by
- snapshotter
- user_liked
- cloned
- archived
- contributors
- geolocation
- read_only
- created_on
- credits
- forker
- number_of_downloads
- number_of_folders
- original_created_by
- golden
- archiver
- forked
- number_of_events
- modified_on
- sketch
- user_rate
- modified_by
- original_creator_name
- imported
- snapshotted
- number_of_archives
- quality_calculated_on
- user_disliked
- number_of_snapshots
- number_of_annotations
- number_of_comments
- content
- annotations
- publishers
- copyrights
- completeness_score
- completeness_calculate_on
- completeness_check_report
- number_of_references
- cite_as
- license
- funding
- communities
- main_entity
add_annotations(resources=None, body_specification_json=None)

Function that adds annotations to the research object.

Parameters

  • resources (list) – resources to which annotations will be applied, optional

  • body_specification_json (str/dict/list) – path to the JSON file or Python serializable object (dict, list), optional

Returns

response content from the API

Return type

dict

add_community(community_identifier)

Function that adds a community to the research object.

See also

list_communities() ros_set_community()

Parameters

community_identifier (str) – community identifier

Returns

response content from the API

Return type

dict

add_external_resource(res_type, input_url, title=None, folder=None, description=None)

Function that adds external resource to the research object.

See also

list_valid_resource_types()

Note

The newly created resource object will return a Python object that has its own set of methods and attributes. You may want to assign it to a variable to make it easy to work with. For example: my_res = ros_add_external_resource(**your set of params)

Parameters

  • res_type (str) – type of resource

  • input_url (str) – resource’s url

  • title (str) – resource’s title, optional

  • folder (str) – folder’s path, optional

  • description (str) – resource’s description

Returns

newly created resource object

Return type

Resource

add_folders(name, description=None, parent_folder=None)

Function that adds folders to the research object.

Parameters

  • name (str) – folder’s name

  • description (str) – folder’s description, optional

  • parent_folder (str) – parent folder path, optional

Returns

response content from the API

Return type

dict

add_funding(grant_identifier, grant_name, funder_name, grant_title=None, funder_doi=None)

Function that adds funding information to the research object.

Note

two auxiliary functions can be used to get some examples for funders and grants from the Zenodo database, respectively: zenodo_list_funders() zenodo_list_grants() check documentation of the above to get usage details

Parameters

  • grant_identifier (str) – grant’s identifier

  • grant_name (str) – grant’s name

  • funder_name (str) – funder’s name

  • grant_title (str) – grant’s title, optional

  • funder_doi (str) – funder’s doi, optional

Returns

service identifier for the newly created funding

Return type

str

add_geolocation(body_specification_json)

Function that adds geolocation to the research object.

Parameters

body_specification_json (str/dict/list) – path to the JSON file or Python serializable object (dict, list)

Returns

response content from the API

Return type

dict

add_internal_resource(res_type, file_path, title=None, folder=None, description=None)

Function that adds internal resource to the research object.

See also

list_valid_resource_types()

Note

The newly created resource object will return a Python object that has its own set of methods and attributes. You may want to assign it to a variable to make it easy to work with. For example: my_res = ros_add_internal_resource(**your set of params)

Parameters

  • res_type (str) – type of resource

  • file_path (str) – resource’s file path

  • title (str) – resource’s title, optional

  • folder (str) – folder’s path, optional

  • description (str) – resource’s description

Returns

newly created resource object

Return type

Resource

add_keywords(keywords)

Function that adds set of keywords to the research object.

Parameters

keywords (list) – list of keywords

Returns

response content from the API

Return type

dict

add_main_entity(main_entity)

Function that associates main entity with the Research Object.

See also

list_valid_resource_types()

Parameters

main_entity – main entity

Type

main_entity: str

Returns

response content from the API

Return type

dict

add_resource_from_zip(path_to_zip)

Function that adds resource from the zip package to the research object.

Parameters

path_to_zip (str) – path to the existing zip package

Returns

response content from the API

Return type

dict

add_sketch(path_to_sketch_file)

Function that adds sketch to the Research Object.

Parameters

path_to_sketch_file – path to the existing file that will be uploaded as sketch

Type

path_to_sketch_file: str

Returns

response content from the API

Return type

dict

add_triple(the_subject, the_predicate, the_object, annotation_id, object_class=None)

Function that adds triple to the annotations and validates if annotations are associated with research object.

See also

list_triple_object_classes()

Parameters

  • the_subject (str) – triple’s subject

  • the_predicate (str) – triple’s predicate

  • the_object (str) – triple’s object

  • annotation_id (str) – annotation’s identifier

  • object_class (str) – object’s class, optional

Returns

response content from the API

Return type

dict

aggregate_datacube(dataset_id, product_id=None, product_media_type=None)

Function that aggregates datacube from adam platform to a research object.

Parameters

  • dataset_id (str) – dataset identifier

  • product_id (str) – product identifier, optional

  • product_media_type – media type, has to be one of: image/tiff, image/png or application/xml, optional

Returns

response from api

Return type

dict

archive(title=None, description=None, create_doi=None, external_doi=None, publication_services=None)

Function that creates research object’s archive.

See also

list_valid_publication_services()

Note

if one chooses to use doi it can be provided in two ways: 1) through setting create_doi to True, then doi will be generated for you 2) through passing your doi using external_doi parameter create_doi = True and external_doi are mutually exclusive, therefore they can’t be used simultaneously!

Note

if on chooses to use publications services the result will be loaded as an RO-crate!

Warning

user needs to make sure that he has service credentials associated with his profile for the publication services that he would like to use! If that is not the case, warning will be shown and the ros will not be published as intended!

Parameters

  • title (str) – archive title, optional

  • description (str) – archive description, optional

  • create_doi (bool) – doi is created if True, False otherwise, optional, False is the default

  • external_doi (str) – existing doi value that will be associated with the snapshot, optional

  • publication_services (list) – services where the archive should be published into

Returns

archive identifier

Return type

str

completeness(verbose=False)

Function that shows completeness score and details for the research object.

Parameters

verbose (bool) – if True full details will be displayed, otherwise only score with basic metadata, optional.

Returns

completeness information

Return type

dict

delete()

Function that deletes Research Object.

Warning

The research object will be deleted from the service and will no longer appear in the API. This doesn’t mean that object created in your local scope will be removed!

Returns

response content from the API

Return type

dict

delete_communities()

Function that deletes association between community/communities and the research object.

Returns

None

Return type

None

delete_folder(path)

Function that deletes a folder inside the research object based on its path.

Note

Path should be constructed using “/” as a separator. For example “my_folder” inside the parent folder with name “parent_folder” should be references like this: parent_folder/my_folder.

Parameters

path (str) – folder’s full path

Returns

None

Return type

None

delete_funding(funding_identifier)

Function that deletes specific funding associated with research object.

Parameters

funding_identifier (str) – funding’s identifier

Returns

None

Return type

None

delete_keywords()

Function that deletes all keywords associated with the research object.

Returns

None

Return type

None

delete_license()

Function that deletes association between license and research object.

Returns

None

Return type

None

delete_main_entity()

Function that deletes main entity association for the Research Object.

Returns

None

Return type

None

enrich()

Functions for applying enrichment to the research object.

Warning

The enrichment process can take a while. We recommend waiting a few minutes and then checking a job status manually by running a prompted command.

Returns

API response

Return type

dict

export_to_rocrate(filename=None, path=None, use_format='jsonld')

Function for downloading research object metadata as RO-crate.

Parameters

  • filename (str) – plain filename without extension, optional - if not provided username will be used instead

  • path (str) – folder path to where file should be downloaded, optional - default is current working directory

  • use_format (str) – format choice for acquired data - either jsonld or zip

Returns

None

fork(title=None, description=None)

Function that creates research object’s fork.

Parameters

  • title (str) – fork title, optional

  • description (str) – fork description, optional

Returns

fork identifier

Return type

str

get_content()

Function that loads content related to the research object.

Note

result is accessible through content attribute after the execution

Returns

None

Return type

None

list_annotations()

Function that lists all annotations associated with the research object.

Returns

set of selected information regarding each annotation

Return type

list

list_authors()

Function that lists authors associated with the research object.

Returns

response containing authors details

Return type

dict

list_communities()

Function that shows list of communities associated with the Research Object.

Returns

list containing keywords details

Return type

list

list_contributors()

Function that lists contributors associated with the research object.

Returns

response containing contributors details

Return type

dict

Function that lists copyrights associated with the research object.

Returns

response containing copyright details

Return type

dict

list_folders()

Function that lists folders associated with research object.

Returns

table containing selected information about all associated folders

Return type

Panda’s DataFrame

list_fundings()

Function that lists fundings associated with the research object.

Returns

response containing fundings details

Return type

dict

list_keywords()

Function that shows list of keywords for associated with the research object.

Returns

response containing keywords details

Return type

dict

list_license()

Function that lists license associated with the research object.

Returns

response containing license details

Return type

dict

list_publications()

Function that lists publication details related to the research object.

Returns

set of selected information regarding each publication

Return type

list

list_resources()

Function that lists resources that are associated with the research object.

Returns

table containing selected information about all associated resources

Return type

Panda’s DataFrame

list_sketch()

Function that list details about sketch associated with the Research Object.

Returns

response content from the API

Return type

dict

list_triples(identifier)

Function that lists all triples related to a specific annotation that is a part of research object.

Warning

If provided annotation is not a part of research object the error will be thrown!

Parameters

identifier (str) – annotation’s identifier

Returns

set of selected information regarding each triple

Return type

list

load_full_metadata()

Function that loads full meta information of research object.

See also

show_full_metadata()

Note

results are accessible in two ways:
1) API’s response which can be displayed using show_full_metadata
2) Accessing a single attribute containing a piece of metadata
- created_by
- metadata
- contributors_credits
- authors_credits
- number_of_all_aggregates
- number_of_resources
- original_created_on
- parent_ro
- contributed_by
- number_of_views
- number_of_forks
- authored_by
- snapshotter
- user_liked
- cloned
- archived
- contributors
- geolocation
- read_only
- created_on
- credits
- forker
- number_of_downloads
- number_of_folders
- original_created_by
- golden
- archiver
- forked
- number_of_events
- modified_on
- sketch
- user_rate
- modified_by
- original_creator_name
- imported
- snapshotted
- number_of_archives
- quality_calculated_on
- user_disliked
- number_of_snapshots
- number_of_annotations
- number_of_comments
- publishers
- copyrights
- completeness
- completeness_calculate_on
- completeness_check_report
- number_of_references
- cite_as
- license
- funding
- communities
- main_entity
Returns

None

make_golden()

Function that makes research object golden.

Warning

Research object’s completeness has to be 100% to make and keep it golden!

See also

completeness()

Returns

response containing keywords details

Return type

dict

set_authors(agents)

Function that sets authors to the research object.

Note

The order in which agents are provided as input is preserved in the API!

See also

The template for providing data for non-existing users is as follows: {“agent_type”: “user”, “display_name”: “example_display_name”, “email”:”example_email”, “orcid_id”:”example_orcid_id”, “affiliation”: “example_affiliation”}

Parameters

agents (list) – usernames representing authors, if one doesn’t exist it will be automatically created

Returns

response content from the API

Return type

dict

set_community(community_identifier)

Function that sets community for the research object.

See also

list_communities() ros_add_community()

:param community_identifier community identifier :type community_identifier: str :return: response content from the API :rtype: dict

set_contributors(agents)

Function that sets contributors to the research object.

Note

The order in which agents are provided as input is preserved in the API!

See also

The template for providing data for non-existing users is as follows: {“agent_type”: “user”, “display_name”: “example_display_name”, “email”:”example_email”, “orcid_id”:”example_orcid_id”, “affiliation”: “example_affiliation”}

Parameters

agents (list) – usernames representing contributors, if one doesn’t exist it will be automatically created

Returns

response content from the API

Return type

dict

Function that sets copyright holders to the research object.

Note

The order in which agents are provided as input is preserved in the API!

See also

The template for providing data for non-existing users/organizations is as follows: USER: {“agent_type”: “user”, “display_name”: “example_display_name”, “email”:”example_email”, “orcid_id”:”example_orcid_id”, “affiliation”: “example_affiliation”} ORGANIZATION: {“agent_type”: “organization”, “display_name”: “example_display_name”, “email”: “example_email”, “organization_url”: “example_url”, “ror_identifier”: “example_ror”}

Parameters

agents (list) – usernames/organizations representing holders, if one doesn’t exist it will be automatically created

Returns

response content from the API

Return type

dict

set_keywords(keywords)

Function that sets list of keywords to the research object.

Parameters

keywords (list) – list of keywords

Returns

response content from the API

Return type

dict

set_license(license_id)

Function that sets license information to the research object.

Parameters

license_id (str) – license’s identifier

Returns

response content from the API

Return type

dict

set_publishers(agents)

Function that sets publishers to the research object.

Note

The order in which agents are provided as input is preserved in the API!

See also

The template for providing data for non-existing users/organizations is as follows: USER: {“agent_type”: “user”, “display_name”: “example_display_name”, “email”:”example_email”, “orcid_id”:”example_orcid_id”, “affiliation”: “example_affiliation”} ORGANIZATION: {“agent_type”: “organization”, “display_name”: “example_display_name”, “email”: “example_email”, “organization_url”: “example_url”, “ror_identifier”: “example_ror”}

Parameters

agents (list) – usernames/organizations representing publishers, if one doesn’t exist it will be automatically created

Returns

response content from the API

Return type

dict

show_full_metadata()

Function that displays full metadata information associated with the research object.

See also

load_full_metadata()

Returns

response content from the API

Return type

dict

show_metadata()

Function that displays basic metadata information associated with the research object.

Returns

response content from the API

Return type

dict

snapshot(title=None, description=None, create_doi=None, external_doi=None, publication_services=None)

Function that creates research object’s snapshot.

See also

list_valid_publication_services()

Note

if one chooses to use doi it can be provided in two ways: 1) through setting create_doi to True, then doi will be generated for you 2) through passing your doi using external_doi parameter create_doi = True and external_doi are mutually exclusive, therefore they can’t be used simultaneously!

Note

if on chooses to use publications services the result will be loaded as an RO-crate!

Warning

user needs to make sure that he has service credentials associated with his profile for the publication services that he would like to use! If that is not the case, warning will be shown and the ros will not be published as intended!

Parameters

  • title (str) – snapshot title, optional

  • description (str) – snapshot description, optional

  • create_doi (bool) – doi is created if True, False otherwise, optional, False is the default

  • external_doi (str) – existing doi value that will be associated with the snapshot, optional

  • publication_services (list) – services where the snapshot should be published into

Returns

snapshot identifier

Return type

str

undo_golden()

Function that makes research object stop being golden.

Returns

None

Return type

None

update()

Function for updating research object in the service.

Note

After executing update the research object will be updated in the service with accordance to the changes that were made to the python object in your local scope.

Returns

response content from the API

Return type

dict

update_funding(funding_identifier, grant_identifier=None, grant_name=None, grant_title=None, funder_doi=None, funder_name=None)

Function that updates specific funding associated with research object.

See also

list_fundings()

Parameters

  • funding_identifier (str) – funding’s identifier

  • grant_identifier (str) – grant’s identifier, optional

  • grant_name (str) – grant’s name, optional

  • funder_name (str) – funder’s name, optional

  • grant_title (str) – grant’s title, optional

  • funder_doi (str) – funder’s doi, optional

Returns

response content from the API

Return type

dict