cytopy.data.project¶

Every analysis is controlled using the Project class, the highest structure in the hierarchy of documents in the central MongoDB database. You can create multiple experiments for a Project, each attaining to a different staining panel. Experiments are accessed and managed through the Project class.

Projects also house the subjects (represented by the Subject class; see cytopy.data.subject) of an analysis which can contain multiple meta-data.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Classes:

Project(*args, **values)

A project is the highest controlling structure of an analysis and houses all the experiments, their associated FileGroups and the populations contained in each FileGroup and the populations clusters.

class cytopy.data.project.Project(*args, **values)¶

A project is the highest controlling structure of an analysis and houses all the experiments, their associated FileGroups and the populations contained in each FileGroup and the populations clusters.

Project can be used to create new experiments and to load existing experiments to interact with.

Single cell data is stored in HDF5 files and the meta-data stored in MongoDB. When creating a Project you should specify where to store these HDF5 files. This data is stored locally and the local path is stored in ‘data_directory’. This will be checked each time the object is initiated but can be changed using the ‘update_data_directory’ method.

project_id¶

unique identifier for project

Type: str, required

subjects¶

List of references for associated subjects; see Subject

Type: list

start_date¶

date of creation

Type: DateTime

owner¶

user name of owner

Type: str, required

experiments¶

List of references for associated fcs files

Type: list

data_directory¶

Path to the local directory for storing HDF5 files.

Type: str, required

Miscellaneous:

`DoesNotExist`
`MultipleObjectsReturned`

Methods:

`add_experiment`(experiment_id, panel_definition)	Add new experiment to project.
`add_subject`(subject_id, **kwargs)	Create a new subject and associated to project; a subject is an individual element of a study e.g.
`delete`([delete_h5_data])	Delete project (wrapper function of mongoengine.Document.delete)
`delete_experiment`(experiment_id)	Delete experiment
`get_experiment`(experiment_id)	Load the experiment object for a given experiment ID
`get_subject`(subject_id)	Given a subject ID associated to Project, return the Subject document
`list_experiments`()	Lists experiments in project
`list_subjects`()	Generate a list of subject ID for subjects associated to this project
`update_data_directory`(data_directory[, move])	Update the data directory for this Project.

exception DoesNotExist¶

exception MultipleObjectsReturned¶

add_experiment(experiment_id: str, panel_definition: str) → cytopy.data.experiment.Experiment ¶

Add new experiment to project. Note you must provide either a path to an excel template for the panel definition (panel_definition) or the name of an existing panel (panel_name). If panel_definition is provided, then the panel_name will be used to name the new Panel document associated to this experiment. If no panel_name is provided, then the panel name will default to “{experiment_id}_panel”.

Parameters

experiment_id (str) – experiment name
panel_definition (str or dict) – Path to excel template for generating the panel

Returns

Newly created FCSExperiment

Return type

Experiment

Raises

DuplicateExperimentError – If given experiment ID already exists

add_subject(subject_id: str, **kwargs) → cytopy.data.subject.Subject ¶

Create a new subject and associated to project; a subject is an individual element of a study e.g. a patient or a mouse

Parameters

subject_id (str) – subject ID for the new subject
kwargs – Additional keyword arguments to pass to Subject initialisation (see cytopy.data.subject.Subject)

Returns

Return type

None

Raises

DuplicateSubjectError – If subject already exists

delete(delete_h5_data: bool = True, *args, **kwargs) → None¶

Delete project (wrapper function of mongoengine.Document.delete)

Parameters

delete_h5_data (bool (default=True)) – Delete associated HDF5 data
args – positional arguments to pass to parent call (see mongoengine.Document.delete)
kwargs – keyword arguments to pass to parent call (see mongoengine.Document.delete)

Returns

Return type

None

delete_experiment(experiment_id: str)¶

Delete experiment

Parameters: experiment_id (str) –
Returns
Return type: None

get_experiment(experiment_id: str) → cytopy.data.experiment.Experiment ¶

Load the experiment object for a given experiment ID

Parameters: experiment_id (str) – experiment to load
Returns
Return type: Experiment
Raises: MissingExperimentError – If requested experiment does not exist in this project

get_subject(subject_id: str) → cytopy.data.subject.Subject ¶

Given a subject ID associated to Project, return the Subject document

Parameters: subject_id (str) – subject ID to pull
Returns
Return type: Subject
Raises: MissingSubjectError – If desired subject does not exist

list_experiments() → list¶

Lists experiments in project

Returns
Return type: List

list_subjects() → list¶

Generate a list of subject ID for subjects associated to this project

Returns: List of subject IDs
Return type: List

update_data_directory(data_directory: str, move: bool = True)¶

Update the data directory for this Project. It is recommended that you let cytopy migrate the existing directory by letting ‘move’ equal True.

Parameters

data_directory (str) – Local path to HDF5 data
move (bool (default=True)) – If True, will attempt to move the existing data_directory

Returns

Return type

None

Raises

InvalidDataDirectory – If provided path does not exist