1.1 HOW-TO use your Astro-WISE Context to set data scopes

1.1.1 Astro-WISE Context

1. Astro-WISE user identity
2. project
3. minimum privileges level

1.1.1.1 User

At the awe-prompt the creator of data object myobject can be printed to the screen with

awe> myobject._creator # Returns user id
990
awe> from common.database.Database import Database
awe> Database.users[myobject._creator] # Returns user name
'AWJJOPLIN'

1.1.1.2 Project

Figure: This diagram shows which Astro-WISE users are project members of Astro-WISE project A and B. A project in Astro-WISE is a set of Astro-WISE users who collaborate on a common data set. Project members are indicated in the diagram by a green tick mark. An Astro-WISE user can be member of more than one project. Each project has one or more Astro-WISE users as project members. One or more of the project members can be project manager (indicated with (pm)). A project manager has additional abilities and responsibilities to manage project data.

At the awe-prompt the project to which data object myobject belongs can be printed to the screen with

awe> myobject._project #Returns project id
14 
awe> from common.database.Database import Database
awe> Database.projects[myobject._project] # Returns project name
'WFI@2.2m'

Some projects have all Astro-WISE users as members: these are called public projects. Some projects have a subset of Astro-WISE users as members: these are called private projects. One or more of the Astro-WISE users in a project can also act as project manager. A project manager has additional abilities and responsibilities to manage data objects that belong to a project. The extra abilities/responsibilities are for data objects at privileges levels of 3 and larger. At these privileges levels the data objects are visible to persons which are not project members. The concept of privileges is explained next.

An overview of all projects in the database, their members, the project's manager etc. can be found on our webpages at the following address:
http://process.astro-wise.org/Projectshttp://process.astro-wise.org/Projects.

1.1.1.3 Privileges

Privileges of data objects determine which Astro-WISE users have access to the data object. Each data object in Astro-WISE has one of five privileges as listed in Table .

The initial privileges of a data object are set upon the creation/ingestion of the data entity. They can be changed after that.

At the awe-prompt the privileges of data object myobject can be printed to the screen with

awe> myobject._privileges
1

1.1.2 Using Context

Your Astro-WISE Context is defined by your Astro-WISE user identity, the current project you choose and the current minimum privileges level that you choose. The Astro-WISE user that you are is defined upon login as you login with a certain user name (e.g. AWJJOPLIN). Upon login, also a current project and a current minimum privileges level are set. These two initial selections depend on your login configuration. At the Astro-WISE command-line prompt, the python class context is the interface to view and change the selection of project and privileges level. You can import context at the Astro-WISE prompt via:

awe> from common.database.Context import context

awe> context.get_current_privileges()
1

awe> context.set_privileges(2)

To see which project is currently selected, use context.get_current_project(). If the project object is printed, a formatted overview will be given:

awe> print context.get_current_project()
   Project:     SONATE  (id = 14)
   Description: 1700 Square degree 5 band survey of the equatorial strip and 2dF
                South region
   Instrument:  OCAM
   Maximum Privileges: 4 (WORLD)
   Current Privileges: 1 (MyDB)

awe> context.set_project('BLUES')

To select at the same time the project and the minimum privileges level at the awe-prompt use:

awe> context.set_project('BLUES', privileges=2)

1.1.2.1 Data access scope

The philosophy in Astro-WISE is to increase efficiency in survey processing by sharing useful public data (such as calibration data). The philosophy of Context is therefore to allow users to select which data they want to see in their data access scope in addition to public data from Astro-WISE projects.

Whether a data object falls within the data access scope of the Context as currently configured depends on the values of 3 attributes which each data object has:

• _privileges
• _project
• _creator

The minimum privileges level chosen for your Context defines from which privileges level on you want to have access to data objects. Thus, by lowering the minimum privileges level you add data objects to your data access scope. A minimum privileges level of i mathend000# indicates data objects with privileges levels x 1#1 i mathend000# will fall in your data access scope. For privileges levels 1#1 3 mathend000# all data objects with that privileges level fall into your data scope. For privileges levels 2#2 2 mathend000# a subset of the data objects with that privileges level belong to your data scope. Table  lists the rules which decide which data objects fall within your data access scope. Figure  shows a graphical representation of the resulting data access scope for each of the five minimum privilegels levels that can be selected for your Context.

As an example, assume that you select your Context to have project='BLUES' and minimum privileges level=1. Then your data access scope will include

• data with privileges==1 which are created by you in any project
• data with privileges==2 which are in project='BLUES'
• data with privileges1#1 3 mathend000# in all projects, also those of which you are not a member

Figure: Schematic representations of the data access scope for five different settings of Context (listed on top of each diagram). In all Context settings the Astro-WISE user is set to 'User X' and the project in Context to 'Project A'. A separate diagram is shown for each of the five minimim privileges levels that User X can set for the Context. The columns on the diagram are divided over three projects. Per project there is one column for each project member. Such a column represents the data objects which belong to the project and which are created by that project member. The data objects can have 5 different privileges levels which are separated in rows. Thus each box in the diagram represents data objects which belong to the same project, have the same creator and the same privileges level (i.e., have the same values for attributes _project, _privileges and _creator. Green colored boxes indicate the data access scope of User X for the chosen Context settings: the data objects to which User X has access.

1.1.2.2 Data creation scope

Upon creation/ingestion of an object the values of its attributes _project, _privileges and _creator are :

• _project set to the id of the project of your Context
• _privileges set to the minimum privileges level of your Context
• _creator set to the id of your Astro-WISE user identity

Only project members can ingest/create data in a project. Data objects can not be created and ingested at all privileges levels. In private projects, the project members can create and ingest data objects only at privileges levels 1 and 2. Only project managers can then promote data objects to higher privileges levels up to privileges levels equal 5. This is called publishing and is described in the next section. In public projects the Astro-WISE users can ingest and create data object up to all privileges levels up to a maximum of 4.

1.1.3 Publishing of data objects

The philosophy of Astro-WISE is to share results across projects whenever beneficial. An example are shared calibration data. With time calibration scientists of projects will improve their knowledge and methods how to make the best calibration data for that instrument. For example, the improvements could be based on long term trend analysis. In this sense not individual nights but complete instruments become calibrated in Astro-WISE . The calibration scientists can share their improved calibration data with the Astro-WISE community by publishing his results to a privileges level of 3 or higher. Astro-WISE users, also in other projects, can then re-process their data using these improved calibration data. Furthermore, to improve their own calibrations of other periods they can inspect how the calibration was derived by the calibration scientist because they can access the data lineage of a data object. In conclusion, the idea is that with time data objects are promoted to higher privileges levels. This promotion to a higher privileges level is called publishing in Astro-WISE .

Only the creators and project managers can publish data objects of a project. Table  shows who can publish data objects to which privileges levels in public and private projects.

Publishing up to and including privileges level 3 is recursive: all dependencies are promoted to the published level as well.

Here is an example how to publish an object to privileges level 3:

awe> context.publish(object, privileges=3, commit=True, verbose=True)

The result of publishing is a larger number of people (Astro-WISE users and possibly persons without an Astro-WISE account) who can view and access the data as listed in Table 

1.1.3.1 Publishing of an object with dependencies in different projects

awe> context.publish(object, privileges=2, commit=True, verbose=True)

awe> thisobject.is_valid
1

awe> context.update_is_valid(thisobject,0)

awe> context.delete(myobject)

awe> thisobject.is_valid
1

awe> context.update_is_valid(thisobject,0)