Proposal API

This is an API for working with proposals. It lets you list runs, read metadata from MyMDC, open data with EXtra-data, access DAMNIT results, and make simple run timelines.

Quick example:

from extra.proposal import Proposal

# Open a proposal
proposal = Proposal(1234)

# Print general information about the proposal
proposal.info()

# Get a table of samples and the runs they have
proposal.samples_table()

# Get DAQ data from extra-data for run 10
proposal[10].data()

# Get DAMNIT data through the DAMNIT API
proposal[10].damnit()

extra.proposal.Proposal

Proposal(proposal: int | str, user_id: Optional[str] = None, user_secret: Optional[str] = None, user_email: Optional[str] = None, timeout=10)

Proposal object. It can be instantiated as Proposal(2112) or Proposal("p002112")

Parameters:

Name	Type	Description	Default
proposal	int | str	Proposal number.	required
user_id	Optional[str]	UID (can be generated at https://in.xfel.eu/metadata/oauth/applications). Defaults to None.	None
user_secret	Optional[str]	Secret (can be generated at https://in.xfel.eu/metadata/oauth/applications). Defaults to None.	None
user_email	Optional[str]	User's email. Defaults to None.	None

Raises:

Type	Description
ProposalNotFoundError	The proposal does not exist.

instrument property

instrument: str

The instrument this proposal belongs to (e.g. "SPB", "MID").

damnit

damnit()

Access DAMNIT results from this proposal.

Returns:

Type	Description
Damnit	A Damnit object for this proposal.

Raises:

Type	Description
FileNotFoundError	If no DAMNIT database exists for this proposal.

title

title() -> str

Get the proposal title from myMdC

runs

runs() -> list[int]

Get the sorted list of runs available in RAW.

run_techniques

run_techniques(run: int) -> list[dict]

Get the techniques associated with a run from myMdC.

Parameters:

Name	Type	Description	Default
run	int	The run number.	required

Returns:

Type	Description
list[dict]	A list of technique dictionaries with 'identifier' and 'name' keys.

run_sample_name

run_sample_name(run: int) -> str

Get the sample name for a run from myMdC.

Parameters:

Name	Type	Description	Default
run	int	The run number.	required

Returns:

Type	Description
str	The sample name.

run_type

run_type(run: int) -> str

Get the run type for a run from myMdC.

Parameters:

Name	Type	Description	Default
run	int	The run number.	required

Returns:

Type	Description
str	The run type (e.g. "Sample", "Dark", "Calibration").

samples_table

samples_table()

Get a table of samples and their associated runs from myMdC.

Returns:

Type	Description
DataFrame	A DataFrame with columns 'name', 'id', 'url', 'description', and 'runs'.

info

info()

Print summary information about this proposal.

extra.proposal.RunReference

RunReference(proposal: Proposal, run_num: int)

A reference to a specific run within a proposal.

Provides access to run data, metadata, and DAMNIT results. Typically obtained by indexing a Proposal object.

Example:

prop = Proposal(1234)
run = prop[42]  # Returns a RunReference
data = run.data()  # Open DAQ data with extra_data

data

data(**kwargs)

Open the data of this run with extra_data.

Parameters:

Name	Type	Description	Default
**kwargs		Additional arguments passed to open_run().	{}

Returns:

Type	Description
DataCollection	A DataCollection for this run.

damnit

damnit()

Access DAMNIT results from this run.

Returns:

Type	Description
RunVariables	A RunVariables object for this run.

sample_name

sample_name() -> str

Get the sample name from myMdC for this run.

Returns:

Type	Description
str	The sample name.

run_type

run_type() -> str

Get the run type from myMdC for this run.

Returns:

Type	Description
str	The run type (e.g. "Sample", "Dark", "Calibration").

techniques

techniques() -> list[dict]

Get the run techniques from myMdC for this run.

Returns:

Type	Description
list[dict]	A list of technique dictionaries with 'identifier' and 'name' keys.

plot_timeline

plot_timeline()

Plot a timeline of when this run was taken, migrated, and calibrated.

Returns:

Type	Description
Axes	A matplotlib.axes.Axes object.