Agent¶
Definition: An autonomous actor that bears some form of responsibility for an activity taking place, for the existence of an entity, or for another agent’s activity.
Description and Use:
- Agents make contributions to Artifacts. An agent can be an individual Person, an Organization of multiple individuals acting together, or a Computational Agent such as a software program or algorithm.
- Agents can belong to Organizations, and act on behalf or in the context of an Organization when contributing to an Artifact. For example, curators generating these variant pathogenicity interpretations do so in the context of the ClinGen organization, which provides administrative, technical, and funding support for their contributions.
- The CAM model for Agent is minimal - providing only a few generic attributes. Future versions may provide more detailed specifications, but at present it is up to implementations to extend this base model as needed to meet their use cases.
Information Model:
| Field | Description | Cardinality | Requirement | Data Type |
|---|---|---|---|---|
| id | A unique string that identifies the agent. | 1..1 | MUST | identifier |
| type | The high-level class to which the agent belongs (‘Person’, ‘Organization’, or ‘Computational Agent’). | 1..1 | MUST | class |
| label | A free-text name for the agent. | 0..1 | MAY | string |
| description | A free-text description of the agent. | 0..1 | MAY | string |
| externalID | Additional identifier(s) for the agent that come from an external system or authority. | 0..m | MAY | identifier |
| url | A URL where information about the agent can be found. | 0..m | MAY | url |
| qualified Contribution | A particular contribution made by the agent to an artifact. | 0..m | MAY | Contribution |
.
Implementation Notes:
Agent Instances:
- Agent is an ‘abstract class’, and therefore SHOULD NOT be directly instantiated. A concrete subclass (Person, Organization, or Computational Agent) SHOULD be selected to represent any agent in the data. The attributes defined for the abstract Agent class are inherited and extended by its child classes.
Agent Identity Criteria:
- Agent instances in CAM are scoped to be independent of the context in which the agent operates. An instance of a Person agent represents _the person, not the person _as they contribute to a particular project or organization. So agent ‘identity’ is based only on who the person is, not additionally on the context in which they are acting. This is different than how some models, including PROV, scope the notion of an Agent to represent a person acting in a particular context. We applied the former perspective on Agent identity, as we felt it to be more flexible, simpler to apply, and better facilitate data query and integration.
- This decision has implications for how an Agent instances are created in the data. For example, consider a person ‘Steven’ who is a curator in different projects for the ClinGen and ENIGMA organizations. In a CAM-based dataset, there would be a _single Agent instance_ representing Steven, who may contribute to some curated artifacts as an agent for ClinGen and others as an agent for ENIGMA. The context of these contributions is captured in the ‘hadOrganizationalContext’ field of the Contribution object. In a PROV dataset, there would be _two separate instances for Steven_ - one for representing his actions on behalf of ClinGen, and the other for representing his actions on behalf of ENIGMA. Here the context of contribution is part of the Agent object itself.
Extensions to the Agent Class:
- Implementations requiring more than the minimal attributes provided for describing agents MAY extend the model as needed, following the recommendations in the Implementation Guide. Extesnion may involve creating additional attributes for exsiting classes, and/or defineing additional subtypes. We recommend use of community standards where possible for describing agents (e.g. FOAF), to enable data sharing and interoperability.
Person¶
Definition: A human being.
Description and Use:
- Persons are human beings with agency who contribute to artifacts.
- Person is a concrete subclass of Agent. It can be instantiated in the data, and inherits from its abstract parent Agent class.
- At present the CAM does not define additional person-specific attributes - preferring a minimal but extensible model that allows implementation control over how Persons are represented.
Information Model:
- This class inherits from the Agent class defined above, and does not define additional attributes.
Examples:
- In the research domain, examples may include an individual researcher, teacher, curator, administrator, technician, …
Implementation Notes:
Person Identifiers:
- Identifiers for Persons SHOULD come from an open and authoritative provider. ORCIDs are becoming a de facto standard in this space, and are strongly recommended. But other identifier systems/providers exist (e.g. ResearcherID, ISNI).
Person Contributions in Organizations:
- If the person making a contribution is acting as a member of an organization, this MAY be captured using the organizationalContext attribute of the Contribution class. Alternatively, the Organization itself may be indicated as the agent making the contribution.
Extensions to the Person Class:
- As noted above, this minimal Person model is meant to be extended with additional attributes by implementations as needed to suit their requirements. Examples of information that may be useful include given and family name, date of birth, employer, organizational memberships, professional titles, etc. We recommend looking to community standards such as FOAF to provide modeling constructs here, to facilitate data sharing and interoperability.
Membership in Organizations:
- The details of a Person’s membership in an Organization (dates they were active, roles/status they held, etc.) could support advanced queries relating contributions to organizational membership (e.g. “Find all contributions made in 2014 by persons who were members of organization X that year”). Details about organizational membership are not yet represented in the CAM, but this capability may be added in the future, and for now implementations can define their own models to support these use cases.
Organization¶
Definition: A group of agents (typically persons) structured and managed to achieve a common goal.
Description and Use:
- Organization is a concrete subclass of Agent. It can be instantiated in the data, and inherits from its abstract parent Agent class. But at present the CAM does not define additional organization-specific attributes.
- Organizations as defined here may include and group of individuals organized around a shared task or goal, including companies, academic interest groups, consortia, charitable foundations, formal research collaborations. A group does not have to be formally recognized as an organization to be treated as such in the CAM.
- An organization can collectively be credited as making a contribution when it directly or indirectly supports the creation or modification of an artifact, e.g. through funding, defining, directing the work, and/or through its members performing the work.
Information Model:
- This class inherits from the Agent class defined above, and does not define additional attributes.
Examples:
- Scientific consortia such as the Global Alliance for Genomics and Health and ClinGen.
- Businesses/companies such as the publisher Elsevier
- A medical non-profit organization scuch as the American Heart Association
- A government agency such as the Centers for Disease Control
- A philanthropic fraternity such as Shriners International
- A group of students assigned to complete a class project
Implementation Notes:
Capturing Organization Contributions:
- Contributions of an organization to an artifact can be captured in two ways: (1) Directly as the asserted agent in a contribution, in cases where it reflects the collective effort of a group, or it is not important to capture the roles or actions of individual members acting on behalf of an organization; or (2) Indirectly as an organization on whose behalf an individual member’s contribution was performed (using the organizationalContext attribute of the Contribution class).
Extensions to the Organization Class:
- As noted above, this minimal Organization model is meant to be extended with additional attributes by implementations as needed to suit their requirements. We recommend looking to community standards such as FOAF to provide modeling constructs here, to facilitate data sharing and interoperability.
Computational Agent¶
Definition: A software program or algorithm that can autonomously execute tasks to achieve a specified goal.
Description and Use:
- A software program need not conceive of or initiate the task on its own to be considered an agent - it must only be capable of autonomously executing a programmed task.
Information Model:
- This class inherits from the Agent class defined above, and does not define additional attributes.
Examples:
- An algorist (computer algorithm designed to generate art)
- An algorithm that automatically generates an ontology by mining text for Wikipedia
Implementation Notes:
Inferring ‘Transitive Credit’ to Software Creators
- As man-made entities, computational agents can be considered Artifacts, and contributions to them can be captured using the CAM. When this is done, ‘transitive credit’ can be inferred for software creators for Artifacts the software produces.