@@ -454,66 +454,76 @@ def representation_component_units(self):
454454 out [repr_name ] = repr_unit
455455 return out
456456
457- def realize_frame (self , representation ):
457+ def replicate (self , copy = False , ** kwargs ):
458458 """
459- Generates a new frame *with new data* from another frame (which may or
460- may not have data). Roughly speaking, the converse of
461- `copy_without_data` when ``copy`` is ``None``.
459+ Generates a new frame object that is a copy of this one, but possibly
460+ with frame attributes overriden and/or by reference.
461+
462+ If ``copy`` is set to `True` then a full copy of the internal arrays
463+ will be made. By default the replica will use a reference to the
464+ original arrays when possible to save memory. The internal arrays
465+ are normally not changeable by the user so in most cases it should not
466+ be necessary to set ``copy`` to `True`.
462467
463468 Parameters
464469 ----------
465- representation : BaseRepresentation
466- The representation to use as the data for the new frame.
470+ copy : bool, optional
471+ If True, the resulting object is a copy of the data. When False,
472+ references are used where possible. This rule also applies to the
473+ frame attributes.
474+
475+ Any additional keywords are treated as frame attributes to be set on the
476+ new frame object.
467477
468478 Returns
469479 -------
470480 frameobj : same as this frame
471- A new object with the same frame attributes as this one, but
472- with the ``representation`` as the data.
481+ Replica of this object, but possibly with new frame attributes.
473482 """
474- frattrs = dict ([(attr , getattr (self , attr ))
475- for attr in self .get_frame_attr_names ()
476- if attr not in self ._attr_names_with_defaults ])
477- return self .__class__ (representation , ** frattrs )
483+ return self ._apply ('copy' if copy else 'replicate' , ** kwargs )
478484
479- def replicate (self , copy = False , ** kwargs ):
485+ def replicate_without_data (self , copy = False , ** kwargs ):
480486 """
481- Generates a new frame object that is a copy of this one, but with some
482- frame attributes overriden, which may or may not have data.
483-
484- If ``copy`` is set to `True` then a full copy of the internal arrays
485- will be made. By default the replica will use a reference to the
486- original arrays when possible to save memory. The internal arrays
487- are normally not changeable by the user so in most cases it should not
488- be necessary to set ``copy`` to `True`.
489-
490- This method can also be set to drop the representation data entirely by
491- setting ``copy`` to ``None``. In this mode, it is the converse of
492- `realize_frame`.
487+ Generates a new frame object that is a copy of this one, but without
488+ data, and possibly with new frame attributes. Effectively, the converse
489+ of `realize_frame`.
493490
494491 Parameters
495492 ----------
496- copy : bool or None, optional
497- If True, the resulting object is a copy of the data. When False,
498- references are used where possible. When None, the data are dropped
499- entirely in the resulting object (i.e., it becomes a "bare" frame).
493+ copy : bool, optional
494+ If True, the resulting object has copies of the frame attributes.
495+ When False, references are used where possible.
500496
501497 Any additional keywords are treated as frame attributes to be set on the
502498 new frame object.
503499
504500 Returns
505501 -------
506502 frameobj : same as this frame
507- Replica of this object, but possibly with no data and possibly new
508- frame attributes.
503+ Replica of this object, but without data and possibly with new frame
504+ attributes.
509505 """
510- if copy is None :
511- method = 'replicatenodata'
512- elif copy :
513- method = 'copy'
514- else :
515- method = 'replicate'
516- return self ._apply (method , ** kwargs )
506+ kwargs ['_framedata' ] = None
507+ return self ._apply ('copy' if copy else 'replicate' , ** kwargs )
508+
509+ def realize_frame (self , representation ):
510+ """
511+ Generates a new frame *with new data* from another frame (which may or
512+ may not have data). Roughly speaking, the converse of
513+ `replicate_without_data`.
514+
515+ Parameters
516+ ----------
517+ representation : BaseRepresentation
518+ The representation to use as the data for the new frame.
519+
520+ Returns
521+ -------
522+ frameobj : same as this frame
523+ A new object with the same frame attributes as this one, but
524+ with the ``representation`` as the data.
525+ """
526+ return self ._apply ('replicate' , _framedata = representation )
517527
518528 def represent_as (self , new_representation , in_frame_units = False ):
519529 """
@@ -801,9 +811,8 @@ def _apply(self, method, *args, **kwargs):
801811 kwargs : dict
802812 Any keyword arguments for ``method``.
803813 """
804- if method == 'replicatenodata' :
805- data = None
806- method = 'replicate'
814+ if '_framedata' in kwargs :
815+ data = kwargs ['_framedata' ]
807816 else :
808817 data = self .data if self .has_data else None
809818
0 commit comments